# Maturity redemption API Source: https://docs.settlemint.com/docs/api-reference/token-features/maturity-redemption Reference the public API routes for maturity-redemption feature attachment, maturity actions, treasury funding, allowance approval, holder redemption, and redemption-event reads. Use the `maturity-redemption` API when a fixed-income token needs a controlled redemption state. The API attaches the feature, moves the token into maturity, funds the configured treasury, approves wallet-treasury allowance, redeems holder positions, and lists redemption events. This page is the API reference for endpoint paths, request fields, and response shape. For the canonical lifecycle model, roles, events, and treasury-readiness signals, see [Maturity redemption architecture](/docs/architects/components/token-features/maturity-redemption). For dapp steps, see [Maturity redemption operator guide](/docs/operators/token-features/maturity-redemption). ## Configuration during token creation [#configuration-during-token-creation] Include `maturity-redemption` in the `featureConfigs` map of `POST /api/v2/tokens` when the token should be created with maturity-redemption already attached. ```json { "featureConfigs": { "maturity-redemption": { "maturityDate": "1893456000", "denominationAsset": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F", "faceValue": "1000000000000000000" } } } ``` For token creation, omit `treasury` unless the token must use a specific treasury address from the start. When `treasury` is omitted, DALP uses the selected executor as the initial treasury. To attach the feature to an existing configurable token, call `POST /api/v2/tokens/{tokenAddress}/features` with `name: "maturity-redemption"` plus the same configuration fields. The attach route requires an explicit `treasury`. | Parameter | Type | Required | Description | | ------------------- | ----------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------- | | `name` | String literal | Attach only | Must be `maturity-redemption` when using `POST /api/v2/tokens/{tokenAddress}/features`. | | `maturityDate` | Unix-seconds timestamp string | Yes | Future timestamp when scheduled maturity becomes available. | | `denominationAsset` | EVM address | Yes | ERC-20 token paid to holders at redemption. It cannot be the zero address. | | `treasury` | EVM address | Attach only | Wallet or contract address that funds redemption payouts. For token creation, omit it to use the selected executor. | | `faceValue` | Integer string | Yes | Payout amount, in denomination-asset base units, per one redeemed token. It must be greater than zero and fit in `uint256`. | Amounts use base units. For an 18-decimal denomination asset, `"1000000000000000000"` represents one full token unit. ## Operation endpoints [#operation-endpoints] All operation endpoints return DALP's standard blockchain mutation response. Depending on the execution path, the response can contain a synchronous result or an accepted queued transaction state. Read the returned transaction or action state before treating the operation as final. | Operation | Method and path | Required role or signer | Body fields | Result | | --------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Attach maturity redemption | `POST /api/v2/tokens/{tokenAddress}/features` | Governance or template-specific feature-configuration authority | `name`, `maturityDate`, `denominationAsset`, `treasury`, `faceValue` | Attaches the maturity-redemption feature to an existing token. | | Trigger scheduled maturity | `POST /api/v2/tokens/{tokenAddress}/features/maturity-redemption/maturations` | `governance` | Wallet verification when required by the session | Queues the on-chain `mature()` call after the configured maturity date. | | Trigger early maturity | `POST /api/v2/tokens/{tokenAddress}/features/maturity-redemption/early-maturations` | `emergency` | Wallet verification when required by the session | Queues the emergency `matureEarly()` call before the scheduled date. | | Set maturity treasury | `PATCH /api/v2/tokens/{tokenAddress}/features/maturity-redemption/treasury` | `governance` | `treasury` | Updates the treasury address used for future redemption payouts. | | Top up maturity treasury | `POST /api/v2/tokens/{tokenAddress}/features/maturity-redemption/top-ups` | Caller funds the transfer from their own wallet; no token role required | `amount` in denomination-asset base units | Transfers denomination asset from the caller to the maturity-redemption feature treasury. | | Approve wallet-treasury allowance | `POST /api/v2/tokens/{tokenAddress}/features/maturity-redemption/treasury-allowance` | Treasury wallet signs; wallet treasuries only | `amount` in denomination-asset base units | Approves the feature to spend denomination asset from a wallet treasury. | | Redeem holder tokens | `POST /api/v2/tokens/{tokenAddress}/features/maturity-redemption/redemptions` | Wallet-verified caller; holder balance and matured state are checked | `amount` in bond-token base units | Burns the holder's tokens and pays denomination asset from the configured treasury. | The scheduled maturity route is not `.../trigger`. Use `/maturations` for the scheduled state transition and `/early-maturations` for the emergency state transition. ## Request bodies [#request-bodies] ### Attach feature [#attach-feature] ```json { "name": "maturity-redemption", "maturityDate": "1893456000", "denominationAsset": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F", "treasury": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F", "faceValue": "1000000000000000000" } ``` ### Set treasury [#set-treasury] ```json { "treasury": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F" } ``` ### Top up treasury or approve treasury allowance [#top-up-treasury-or-approve-treasury-allowance] ```json { "amount": "1000000000000000000" } ``` `amount` is the denomination-asset amount in base units. For allowance approval, the caller must be the configured treasury wallet. ### Redeem holder tokens [#redeem-holder-tokens] ```json { "amount": "1000000" } ``` `amount` is the token amount to redeem. The payout uses the feature's configured face value and denomination asset. The route rejects requests that cannot be paid from the current treasury balance and, for wallet treasuries, the current allowance. ## Treasury and redemption checks [#treasury-and-redemption-checks] Redemption uses the configured face value and denomination asset, not market price. For a wallet treasury, the redemption route checks the indexed treasury state and verifies allowance against the requested payout before queuing the redemption transaction. A smaller redemption can pass while a larger redemption fails when allowance only covers part of the outstanding supply. | Condition | API behaviour | Operator action | | ---------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Treasury balance is too low | The redemption transaction can fail because the treasury cannot pay the requested payout. | Top up the treasury before holders redeem. | | Wallet treasury allowance is too low | The redemption request is rejected when allowance is below the calculated payout. | Have the treasury wallet approve enough allowance for expected redemptions. | | Treasury classification is still pending | Treasury-dependent routes reject until the indexer classifies the treasury. | Wait for indexing to catch up, then retry. | | Maturity has not been triggered | Redemption is rejected while the feature is still pre-maturity. | Trigger scheduled maturity after the maturity date, or use the emergency path only when that role and procedure apply. | ## Redemption events [#redemption-events] Use the redemption-events collection to reconcile holder redemptions after maturity. ```http GET /api/v2/tokens/{tokenAddress}/maturity-redemption/redemption-events ``` The collection supports pagination, sorting by `redeemedAt` by default, and filters on `redeemedAt`, `blockNumber`, `holder`, `redeemedAmount`, and `payoutAmount`. Each item includes: | Field | Description | | ----------------------------------------------------- | ----------------------------------------------------------------------- | | `holder` | Holder address that redeemed tokens. | | `featureAddress` | Maturity-redemption feature contract address. | | `redeemedAmount` / `redeemedAmountExact` | Redeemed token amount as display decimal and exact base-unit value. | | `payoutAmount` / `payoutAmountExact` | Denomination-asset payout as display decimal and exact base-unit value. | | `blockNumber`, `blockTimestamp`, `txHash`, `logIndex` | Chain evidence for the redemption event. | ## API boundaries [#api-boundaries] * The maturity date does not automatically mature the token. An authorised maturity mutation must move the token into the post-maturity state. * Pre-maturity transfers still run through the token's configured compliance, role, freeze, approval, and feature stack. * After maturity, ordinary transfers are blocked and holders use the redemption route. * Treasury balance and wallet-treasury allowance are separate checks. Balance without allowance can still block redemptions when the treasury is a wallet. * DALP records the token-state transition and redemption events. The issuer still owns external cash, notices, legal-register, accounting, and investor-service processes. ## Related [#related] * [Maturity redemption architecture](/docs/architects/components/token-features/maturity-redemption) * [Maturity redemption operator guide](/docs/operators/token-features/maturity-redemption) * [Fixed treasury yield](/docs/api-reference/token-features/fixed-treasury-yield) — often paired for coupon-paying bonds. * [Token lifecycle](/docs/api-reference/tokens/token-lifecycle)