# Token conversion records Source: https://docs.settlemint.com/docs/developers/api-integration/tokens/token-conversion-records Read indexed conversion lifecycle records for a DALP token, including replay identifiers, status, converted amounts, and target-side issuance details. Token conversion records show how a convertible instrument moved from an accepted conversion to target-token issuance. DALP exposes the records as a paginated token API so an integration can reconcile the loan-side conversion record with the target-side issuance record. Use this reference after a holder conversion or mandatory conversion has been submitted and you need to read the indexed outcome for reporting, audit, or back-office reconciliation. The endpoint is read-only: it cannot publish triggers, execute conversions, or decide whether an off-chain financing or legal conversion event was valid. ## Endpoint [#endpoint] Call `GET /api/v2/tokens/{tokenAddress}/conversion/records` 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/records?page[limit]=50&sort=-initiatedAt" \ -H "X-Api-Key: $DALP_API_TOKEN" ``` ```json { "data": [ { "conversionId": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "triggerId": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "holder": "0x2222222222222222222222222222222222222222", "principalConverted": "1000", "principalConvertedExact": "1000000000000000000000", "interestConvertedWad": "25", "interestConvertedWadExact": "25000000000000000000", "targetReceived": "500", "targetReceivedExact": "500000000000000000000", "effectivePriceUsedWad": "2", "effectivePriceUsedWadExact": "2000000000000000000", "status": "Minted", "initiatedAt": "2026-06-06T12:00:00.000Z", "finalizedAt": "2026-06-06T12:00:02.000Z", "isForced": false, "forcedBy": null, "issuedRecipient": "0x2222222222222222222222222222222222222222", "amountMinted": "500", "amountMintedExact": "500000000000000000000", "issuedAt": "2026-06-06T12:00:02.000Z" } ], "meta": { "total": 1, "facets": {} }, "links": { "self": "/v2/tokens/0x1111111111111111111111111111111111111111/conversion/records?sort=-initiatedAt&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 conversion records from another token or tenant. ## Query controls [#query-controls] The endpoint supports pagination, sorting, filtering, and facets using the standard JSON:API query pattern. | Control | Supported fields | Notes | | ---------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | | Sort | `initiatedAt`, `finalizedAt`, `status`, `isForced` | The default sort is newest `initiatedAt` first. DALP uses `conversionId` as a stable tie-breaker. | | Filter | `holder`, `status`, `initiatedAt`, `finalizedAt`, `isForced` | Address filters for `holder` are normalised before DALP queries the index. | | Facets | `status`, `isForced` | Use facets to separate holder-initiated and forced conversion populations. | | Pagination | `page[limit]`, `page[offset]` | Use pagination for reporting jobs instead of assuming every conversion record fits in one response. | ## Fields to reconcile [#fields-to-reconcile] | Field | Meaning | | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `conversionId` | Unique identifier generated for the conversion. Use it as the reconciliation key across loan-side and target-side records. | | `triggerId` | Conversion trigger that produced the conversion. | | `holder` | Holder whose loan exposure was converted. | | `principalConverted` and `principalConvertedExact` | Converted loan principal in decimal and smallest-unit forms. | | `interestConvertedWad` and `interestConvertedWadExact` | Interest included in the conversion, expressed with WAD precision. | | `targetReceived` and `targetReceivedExact` | Target-token amount calculated for the conversion. | | `effectivePriceUsedWad` and `effectivePriceUsedWadExact` | Effective conversion price used after the configured discount and cap. | | `status` | Conversion lifecycle status. Current records are `Initiated` or `Minted`. | | `initiatedAt` and `finalizedAt` | Indexed timestamps for accepted conversion and completed target mint. `finalizedAt` is `null` until the conversion reaches `Minted`. | | `isForced` and `forcedBy` | Whether the conversion used the mandatory conversion path and, when present, the address that forced it. | | `issuedRecipient`, `amountMinted`, `amountMintedExact`, and `issuedAt` | Target-side issuance details from the Conversion Minter record when DALP has indexed the mint. | ## Replay and provenance model [#replay-and-provenance-model] A conversion is not just an amount change. DALP records a conversion ID and uses that ID across the loan-side Conversion feature and the target-side Conversion Minter. For reconciliation, treat `conversionId` as the join key. The loan-side record shows the trigger, holder, principal, interest, target amount, price, status, and forced-conversion flag. The target-side issuance fields show who received target tokens, how much was minted, and when the mint was indexed. A duplicate target-side mint with the same conversion ID is rejected by the Conversion Minter, so a second appearance of the same ID should be treated as a reconciliation problem, not as a new conversion instruction. ## Behaviour and failure cases [#behaviour-and-failure-cases] * If the source token has no attached Conversion feature, the endpoint returns an empty paginated response. * If the conversion exists but the target-side issuance has not been indexed yet, the issuance fields can be `null` while the loan-side record is still visible. * If `status` is `Initiated`, reconcile the conversion against the transaction and event history before treating target-token issuance as complete. * If `status` is `Minted`, use `ConversionFinalized` and the target-side issuance fields together when building evidence packs. * The endpoint reads indexed records. The read does not make a live contract call, retry a conversion, replay a transaction, or execute a new conversion. ## Related [#related] * [Conversion token feature](/docs/architects/components/token-features/conversion) * [Token lifecycle API](/docs/developers/api-integration/tokens/token-lifecycle) * [Token events](/docs/developers/api-integration/tokens/token-events) * [API reference](/docs/developers/api-integration/reference/api-reference)