Maturity redemption API

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. For Console steps, see Maturity redemption operator guide.

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.

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

Amounts use base units. For an 18-decimal denomination asset, "1000000000000000000" represents one full token unit.

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.

The scheduled maturity route is not .../trigger. Use /maturations to trigger the scheduled state change and /early-maturations for the emergency path.

Request bodies

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.

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

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.

{
  "treasury": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
}

Top up treasury or approve spending limit

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

{
  "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

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

{
  "amount": "1000000"
}

The payout uses the feature's configured face value and denomination asset. For a wallet treasury, the route rejects the request when the approved spending limit does not cover the calculated payout. It does not preflight the treasury balance, so a treasury that cannot cover the payout fails later in the transaction queue rather than at request time.

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.

Error codes

When a maturity-redemption call fails, the API returns a stable DALP-NNNN error code. The platform checks the indexed feature state, maturity, treasury classification, and the wallet treasury's approved spending limit before it touches the chain, so those rejections arrive as a typed error rather than an on-chain revert. It does not preflight the treasury balance, so an underfunded treasury surfaces later in the transaction queue. Read the code to decide whether the caller corrects the request and resends, retries the same call once the platform catches up, or escalates to operator follow-up. Each code below maps to a canonical entry in the platform API error reference.

DALP-0467 and DALP-0479 are correctable from the caller side: sign in as the treasury wallet or wait for maturity, then resend. DALP-0478 rejects before the redemption is written, so raise the treasury wallet's approved spending limit and retry. DALP-0466, DALP-0331, and DALP-0468 clear once the platform finishes indexing the feature, so retry after a short delay. A request that passes every check here can still revert at the feature contract on a condition the platform cannot see ahead of time, such as a treasury balance that drops below the payout between preflight and execution. Track the transaction queue to a terminal state before you treat a redemption as settled.

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.

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

Each event record includes the following fields:

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

• Maturity redemption architecture
• Maturity redemption operator guide
• Fixed treasury yield: often paired for coupon-paying bonds.
• Token lifecycle
• Platform API error reference: canonical entries for every DALP-NNNN code.