# Maturity redemption API

Source: https://docs.settlemint.com/docs/api-reference/token-features/maturity-redemption
Reference the endpoints that manage a fixed-income token's full payout lifecycle: attach the feature, mature the token, fund the treasury, and redeem holder positions.



The `maturity-redemption` feature gates principal return behind an explicit maturity event. Once a token reaches maturity, holders call the redemption endpoint to claim face value in the denomination asset, with the platform verifying treasury funding and allowances before settling each position.

This page covers endpoint paths, request fields, and response shape. For the canonical lifecycle model, roles, events, and the signals that indicate treasury readiness, see [Maturity redemption architecture](/docs/architects/components/token-features/maturity-redemption). For Console steps, see [Maturity redemption operator guide](/docs/operators/token-features/maturity-redemption).

## Attach during token creation [#attach-during-token-creation]

Include `maturity-redemption` in the `featureConfigs` map of `POST /api/v2/tokens` to create the token with this feature already attached.

```json
{
  "featureConfigs": {
    "maturity-redemption": {
      "maturityDate": "1893456000",
      "denominationAsset": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "faceValue": "1000000000000000000"
    }
  }
}
```

Omit `treasury` when creating the token unless you need 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 fields. You must supply an explicit `treasury` on the attach route.

| 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.

## Endpoints [#endpoints]

Each endpoint below returns the standard async blockchain response. Depending on the execution path, the response contains a synchronous result or a queued state. Read the returned state before treating the call as complete.

| 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` to trigger the scheduled state change and `/early-maturations` for the emergency path.

## Request bodies [#request-bodies]

### Attach feature [#attach-feature]

Send this body to `POST /api/v2/tokens/{tokenAddress}/features` to add the feature to an existing token. All five fields are required on this route.

```json
{
  "name": "maturity-redemption",
  "maturityDate": "1893456000",
  "denominationAsset": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
  "treasury": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
  "faceValue": "1000000000000000000"
}
```

### Set treasury [#set-treasury]

Send `treasury` as the only field to `PATCH /api/v2/tokens/{tokenAddress}/features/maturity-redemption/treasury`. The platform stores the new address and uses it for all subsequent payouts.

```json
{
  "treasury": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
}
```

### Top up treasury or approve spending limit [#top-up-treasury-or-approve-spending-limit]

Both the top-up and the spending-limit approval endpoints accept a single `amount` field.

```json
{
  "amount": "1000000000000000000"
}
```

`amount` is the denomination-asset amount in base units. For the spending-limit approval, the caller must be the configured treasury wallet.

### Redeem holder tokens [#redeem-holder-tokens]

`amount` is the bond-token count to redeem, in base units.

```json
{
  "amount": "1000000"
}
```

The payout uses the feature's configured face value and denomination asset. The route rejects requests the current treasury balance cannot cover and, for wallet treasuries, requests the current approved allowance does not cover.

## Treasury and payout checks [#treasury-and-payout-checks]

The platform pays holders at the configured face value using the denomination asset, not market price. For a wallet treasury, the payout route checks the indexed treasury state and verifies the granted spending limit against the requested payout before queuing. A smaller request can pass while a larger one fails when the spending limit covers only part of the outstanding supply.

| Condition                                 | API behaviour                                                                             | Operator step                                                                                                          |
| ----------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Treasury balance is too low               | The on-chain payout call can fail because the treasury cannot cover the requested amount. | Top up the treasury before holders redeem.                                                                             |
| Wallet treasury spending limit is too low | The platform rejects the request when the spending limit is below the calculated payout.  | Have the treasury wallet approve a spending limit that covers expected payouts.                                        |
| Treasury type is still pending            | Treasury-dependent routes reject until the indexer classifies the treasury.               | Wait for indexing to catch up, then retry.                                                                             |
| The token has not matured yet             | The platform rejects redemption while the feature is still in the pre-maturity state.     | Trigger scheduled maturity after the maturity date, or use the emergency path only when that role and procedure apply. |

## Payout events [#payout-events]

Query the redemption-events endpoint to reconcile holder payouts after the token matures. You can filter on `redeemedAt`, `blockNumber`, `holder`, `redeemedAmount`, and `payoutAmount`. Results sort by `redeemedAt` by default.

```http
GET /api/v2/tokens/{tokenAddress}/maturity-redemption/redemption-events
```

Each event record includes the following fields:

| 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. You must call an authorised maturity endpoint to move the token into the post-maturity state.
* Transfers before the token matures still run through the token's configured compliance, role, freeze, approval, and feature stack.
* After the token matures, ordinary transfers are blocked and holders use the redemption route.
* Treasury balance and wallet-treasury spending limit are separate checks. Balance without a spending limit can still block payouts when the treasury is a wallet.
* DALP records the token-state change and payout events. You, as the issuer, still own the 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)