# Token conversion triggers Source: https://docs.settlemint.com/docs/api-reference/tokens/token-conversion-triggers Read the conversion triggers on a DALP token, including the effective price after discount and cap, and the published, disabled, and republished lifecycle of each trigger. When you submit a conversion, you reference a `triggerId`, and DALP prices and authorises that conversion against the named trigger. A conversion trigger is the priced, authorised round a holder converts against, and it carries the round price, the discount and cap that produce the effective price, an expiry, and an active flag. Discover the triggers on a token, read the effective price each one offers, and audit when a trigger was published, disabled, or republished using the two read endpoints below. Both are read-only: they list and report triggers but cannot publish, disable, or execute against them. ## List triggers [#list-triggers] Call `GET /api/v2/tokens/{tokenAddress}/conversion/triggers` for the source token that carries the Conversion feature. The response uses the standard DALP paginated list shape. ```bash curl --globoff "$DAPI_URL/api/v2/tokens/0x1111111111111111111111111111111111111111/conversion/triggers?page[limit]=50&filter[active]=true" \ -H "X-Api-Key: $DALP_API_TOKEN" ``` ```json { "data": [ { "triggerId": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "denominationAsset": "0x3333333333333333333333333333333333333333", "roundPricePerShareWad": "1", "roundPricePerShareWadExact": "1000000000000000000", "effectivePriceWad": "0.95", "effectivePriceWadExact": "950000000000000000", "publishedAt": "2026-06-06T12:00:00.000Z", "expiresAt": "2026-07-06T12:00:00.000Z", "metadataHash": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", "active": true, "disabledAt": null, "totalConversions": 12, "totalPrincipalConverted": "1000", "totalPrincipalConvertedExact": "1000000000000000000000" } ], "meta": { "total": 1, "facets": {} }, "links": { "self": "/v2/tokens/0x1111111111111111111111111111111111111111/conversion/triggers?page%5Boffset%5D=0&page%5Blimit%5D=50" } } ``` If the token has no attached Conversion feature in the indexed tenant scope, DALP returns an empty `data` array with `total` set to `0`. It does not infer triggers from another token or tenant. ### Trigger fields [#trigger-fields] | Field | Meaning | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | `triggerId` | On-chain trigger identifier (bytes32 hex). Use it when submitting a conversion and when joining to conversion records. | | `denominationAsset` | Address of the asset the trigger is priced in. | | `roundPricePerShareWad` and `roundPricePerShareWadExact` | Published round price per share, in display and raw WAD (1e18) forms, before discount and cap. | | `effectivePriceWad` and `effectivePriceWadExact` | Price a holder actually receives: `min(roundPrice * (10000 - discountBps) / 10000, capPrice)`. DALP computes this server-side. | | `publishedAt` | When the trigger was published on-chain. | | `expiresAt` | When the trigger expires. An epoch-zero timestamp means the trigger does not expire. | | `metadataHash` | Hash of the off-chain metadata document for the trigger, when present. | | `active` | Whether the trigger is currently active. Disabled triggers stay in the list for history. | | `disabledAt` | When the trigger was disabled, or `null` while it is still active. | | `totalConversions` | Number of conversions executed against the trigger. | | `totalPrincipalConverted` and `totalPrincipalConvertedExact` | Total principal converted against the trigger, in display and raw forms. | The effective price is the number to show a holder and to reconcile against, because the round price does not yet account for the configured discount and cap. The raw `*Exact` fields carry the precise on-chain values; use them for any arithmetic and use the display fields for presentation. ### Query controls [#query-controls] The list endpoint supports pagination, sorting, filtering, and facets using the standard JSON:API query pattern. | Control | Supported fields | Notes | | ---------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Sort | `publishedAt`, `expiresAt` | Use `sort=-publishedAt` to read the most recently published trigger first. | | Filter | `active`, `publishedAt`, `expiresAt` | Use `filter[active]=true` to drop disabled triggers. The `active` flag tracks whether a trigger was disabled, not whether it is still within its expiry window, so check `expiresAt` against the current time before treating a trigger as convertible. | | Facets | `active` | Use the `active` facet to count active versus disabled triggers in one response. | | Pagination | `page[limit]`, `page[offset]` | Page through triggers instead of assuming every trigger fits in one response. | ## Read trigger lifecycle events [#read-trigger-lifecycle-events] Call `GET /api/v2/tokens/{tokenAddress}/conversion/events` to read the append-only lifecycle of the token's conversion triggers. Each event records a point at which a trigger was published, disabled, or republished. ```bash curl --globoff "$DAPI_URL/api/v2/tokens/0x1111111111111111111111111111111111111111/conversion/events?sort=-blockTimestamp" \ -H "X-Api-Key: $DALP_API_TOKEN" ``` ```json { "data": [ { "triggerId": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "kind": "published", "eventIndex": 0, "denominationAsset": "0x3333333333333333333333333333333333333333", "roundPricePerShareWad": "1", "roundPricePerShareWadExact": "1000000000000000000", "expiresAt": "2026-07-06T12:00:00.000Z", "metadataHash": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", "blockNumber": "184920", "blockTimestamp": "2026-06-06T12:00:00.000Z", "txHash": "0xdddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd", "logIndex": 3 } ], "meta": { "total": 1, "facets": {} }, "links": { "self": "/v2/tokens/0x1111111111111111111111111111111111111111/conversion/events?sort=-blockTimestamp&page%5Boffset%5D=0&page%5Blimit%5D=50" } } ``` ### Event fields [#event-fields] | Field | Meaning | | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `triggerId` | The trigger this event applies to. | | `kind` | The lifecycle action: `published`, `disabled`, or `republished`. | | `eventIndex` | Position of the event in the trigger's own lifecycle sequence. | | `denominationAsset`, `roundPricePerShareWad`, `roundPricePerShareWadExact`, `expiresAt`, `metadataHash` | The terms recorded at the event. Pricing and expiry fields are populated for publish and republish, and can be `null` for a disable. | | `blockNumber`, `blockTimestamp`, `txHash`, `logIndex` | On-chain coordinates of the event, for audit and ordering. | A `republished` event records that a trigger's terms were observed again on-chain; it appends a new event row rather than mutating an earlier one. Each trigger is identified by a unique `triggerId`, so introducing new conversion terms means publishing a fresh trigger with its own `triggerId`, not re-publishing an existing one. To rebuild the full history of a trigger, read its events in `blockTimestamp` order and treat the latest publish or republish observation as the terms recorded at any point in time. ### Query controls [#query-controls-1] | Control | Supported fields | Notes | | ---------- | ----------------------------- | ---------------------------------------------------------------------------------------- | | Sort | `kind`, `blockTimestamp` | The default order is newest first. DALP uses block number and log index as tie-breakers. | | Filter | `kind`, `blockTimestamp` | Use `filter[kind]=disabled` to find when triggers were taken out of service. | | Facets | `kind` | Use the `kind` facet to count publish, disable, and republish events. | | Pagination | `page[limit]`, `page[offset]` | Page through the full history for audit exports. | ## SDK and CLI [#sdk-and-cli] The same reads are available through the SDK and CLI. ```ts fixture=dalp-client const triggers = await client.token.conversionTriggers({ params: { tokenAddress: "0x1111111111111111111111111111111111111111" }, query: { filter: { active: true } }, }); const events = await client.token.conversionTriggerEvents({ params: { tokenAddress: "0x1111111111111111111111111111111111111111" }, query: { sort: "-blockTimestamp" }, }); ``` ```bash dalp tokens conversion-triggers 0x1111111111111111111111111111111111111111 dalp tokens conversion-trigger-events 0x1111111111111111111111111111111111111111 ``` ## Behaviour and failure cases [#behaviour-and-failure-cases] * If the token has no attached Conversion feature, both endpoints return an empty paginated response rather than an error. * A disabled trigger stays in the trigger list with `active` set to `false` and a populated `disabledAt`, so historical pricing remains readable. * The events endpoint is append-only. A `republished` event is a new row recording a fresh on-chain observation of a trigger's terms, never an edit to an existing row. * Both endpoints read indexed data. The read does not make a live contract call, publish a trigger, or execute a conversion. ## Related [#related] * [Token conversion records](/docs/api-reference/tokens/token-conversion-records) * [Conversion token feature](/docs/architects/components/token-features/conversion) * [Token lifecycle API](/docs/api-reference/tokens/token-lifecycle) * [API reference](/docs/api-reference/reference/openapi)