Maturity redemption API

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

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.

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

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

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.

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

Request bodies

Attach feature

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

Set treasury

{
  "treasury": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
}

Top up treasury or approve treasury allowance

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

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

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.

Redemption events

Use the redemption-events collection to reconcile holder redemptions after maturity.

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:

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

• Maturity redemption architecture
• Maturity redemption operator guide
• Fixed treasury yield — often paired for coupon-paying bonds.
• Token lifecycle