# Fixed treasury yield API Source: https://docs.settlemint.com/docs/api-reference/token-features/fixed-treasury-yield Endpoint reference for fixed-treasury-yield, covering creation-time parameters, coverage reads, treasury funding and allowance approval, and submitting holder claims. The fixed-treasury-yield feature accrues periodic payments for token holders and pays claims from a configured denomination asset treasury. Each accrual period computes entitlements from the configured rate; holders claim what has accrued once the treasury holds sufficient denomination-asset balance and the wallet-treasury spending allowance is approved. For operator workflow guidance, see [Fixed treasury yield how-to](/docs/operators/token-features/fixed-treasury-yield). For the architecture model and feature behaviour, see [Fixed Treasury Yield](/docs/architects/components/token-features/fixed-treasury-yield). ## Configuration during token creation [#configuration-during-token-creation] Configure the feature during token creation or through the configurable-token feature deployment flow. ```json { "fixed-treasury-yield": { "denominationAsset": "0x1111111111111111111111111111111111111111", "basisPerUnit": "1000000000000000000", "treasury": "0x2222222222222222222222222222222222222222", "startDate": "2026-01-01T00:00:00Z", "endDate": "2027-12-31T00:00:00Z", "rate": 500, "interval": "MONTHLY" } } ``` | Parameter | Type | Required | Description | | ------------------- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- | | `denominationAsset` | EVM address | Yes | ERC-20 address used for yield payouts. | | `basisPerUnit` | Integer string | Yes | Denomination asset base units per token unit used to size yield accrual. Must be greater than zero and fit within `uint256`. | | `treasury` | EVM address | Yes | Address that funds yield distributions. Must not be the zero address. | | `startDate` | Timestamp | Yes | Future timestamp when accrual begins. | | `endDate` | Timestamp | Yes | Future timestamp when accrual stops. Must be after `startDate`. | | `rate` | Integer | Yes | Per-period rate in basis points. Must be at least `1`. | | `interval` | Enum | Yes | DALP time interval used for accrual periods. | DALP validates the address, integer, date, rate, and interval fields before queuing feature deployment. A configuration that cannot satisfy those checks fails validation instead of entering the transaction queue. ## Feature operations [#feature-operations] Fixed treasury yield exposes token feature operations under `/api/v2/tokens/{tokenAddress}/features/fixed-treasury-yield`. | Operation | Method and path | Use it for | Caller | | -------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------- | | Claim accrued yield | `POST /api/v2/tokens/{tokenAddress}/features/fixed-treasury-yield/claims` | Submit a holder claim for completed-period yield. | Holder wallet | | Update treasury | `PATCH /api/v2/tokens/{tokenAddress}/features/fixed-treasury-yield/treasury` | Change the treasury address used for future payouts. | Governance role | | Top up treasury | `POST /api/v2/tokens/{tokenAddress}/features/fixed-treasury-yield/top-ups` | Transfer denomination asset from the caller's wallet to the configured treasury. | Funding wallet | | Approve treasury allowance | `POST /api/v2/tokens/{tokenAddress}/features/fixed-treasury-yield/treasury-allowance` | Let the schedule contract spend denomination asset from a wallet treasury. | Treasury wallet | Mutation responses use DALP's asynchronous blockchain mutation envelope and return the updated token resource when the queued operation completes. ## Claim behaviour [#claim-behaviour] A holder claim pays yield for completed periods that remain claimable for the effective wallet. DALP runs conservative preflight checks and rejects the claim early in these cases: * Less than one configured interval has completed since the start date. The platform does not queue the claim. * All completed periods have already been claimed. The platform does not queue the claim. * Accrued yield is zero. This can happen when accrual closes after conversion, consumed interest offsets accrual, or the holder had no balance at completed-period boundaries. * Schedule or holder data is temporarily unavailable. DALP lets on-chain execution decide instead of blocking on incomplete off-chain reads. The claim transaction still depends on the treasury payout path. For wallet treasuries, the treasury wallet must approve the schedule contract to spend the denomination asset before any claim can succeed. Contract treasuries handle payouts internally and do not require a separate allowance step. ### Claiming a backlog of completed periods [#claiming-a-backlog-of-completed-periods] A token feature claim submits one claim transaction. Each on-chain claim settles a bounded number of completed periods, so a holder with a large backlog of unclaimed periods may need to claim more than once. This claim returns the updated token resource; it does not report whether the holder is now fully caught up. To confirm progress, read the holder's claimed-through period after the claim settles and claim again while unclaimed periods remain. Wait for the queued operation to settle before re-claiming: a follow-up claim against an already caught-up holder is rejected because no yield is available. When you need a single call to drain a backlog and report whether the holder is caught up, claim through the [yield schedule](/docs/operators/system-addons/yield-schedule#claim-or-withdraw-funds) instead. The schedule claim chains several capped settlements in one request and returns a `complete` flag. ## Treasury allowance approval [#treasury-allowance-approval] Use `POST /api/v2/tokens/{tokenAddress}/features/fixed-treasury-yield/treasury-allowance` when the configured treasury is a wallet and the schedule contract needs ERC-20 allowance to pay holders. The treasury wallet signs this transaction to grant the spend permission. Without a sufficient allowance, the schedule contract cannot execute payouts even when the treasury holds enough balance. ```json { "amount": "1000000000000000000" } ``` | Body field | Type | Description | | ---------- | -------------- | ------------------------------------------- | | `amount` | Integer string | Allowance in denomination asset base units. | Skip this step when your treasury is a contract. Contract treasuries use their own payout logic, and wallet allowance semantics do not apply. ## Top up treasury [#top-up-treasury] Use `POST /api/v2/tokens/{tokenAddress}/features/fixed-treasury-yield/top-ups` to move denomination asset from your wallet to the configured treasury. This transfers funds to the treasury but does not grant the schedule contract permission to spend them. ```json { "amount": "1000000000000000000" } ``` | Body field | Type | Description | | ---------- | -------------- | ---------------------------------------- | | `amount` | Integer string | Denomination asset amount in base units. | Top-up funding and allowance approval are separate controls. A funded wallet treasury can still block holder claims when allowance is too low. ## Coverage monitoring [#coverage-monitoring] Check coverage before you prompt operators or holders to fund or approve. The yield-coverage endpoint returns the indexed state of the schedule, treasury balance, allowance, and outstanding claims in a single read: ```bash curl "https://your-platform.example.com/api/v2/tokens/0xTOKEN/stats/yield-coverage" \ -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx" ``` The coverage response includes: | Field | Use it for | | ------------------------------------ | -------------------------------------------------------------------------- | | `hasYieldSchedule` | Determine whether DALP has indexed a schedule for the token. | | `isRunning` | Show whether the current time falls within the configured schedule window. | | `totalUnclaimedYield` | Display outstanding claimable yield after consumed-interest adjustment. | | `denominationAssetBalance` | Compare available denomination asset balance with outstanding claims. | | `denominationAssetTreasuryAllowance` | Read wallet treasury allowance granted to the schedule contract. | | `requiredAllowance` | Size the allowance prompt for wallet treasuries. | | `allowanceCoveredPercentage` | Display how much of the required allowance is covered. | | `treasuryIsContract` | Decide whether to show wallet allowance prompts. | | `treasuryAddress` | Show the configured treasury address when indexed. | | `scheduleAddress` | Identify the schedule contract address used as the allowance spender. | Prompt for allowance only when `treasuryIsContract` is `false` and `denominationAssetTreasuryAllowance` is lower than `requiredAllowance`. If `treasuryIsContract` is `null`, wait for indexing to classify the treasury before you decide which prompt to show. ## Related [#related] * [Maturity redemption](/docs/api-reference/token-features/maturity-redemption): often paired for coupon-paying bonds. * [Fixed treasury yield how-to](/docs/operators/token-features/fixed-treasury-yield) * [Fixed Treasury Yield](/docs/architects/components/token-features/fixed-treasury-yield) * [Yield coverage statistics](/docs/api-reference/tokens/yield-coverage-statistics) * [Token lifecycle API operations](/docs/api-reference/tokens/token-lifecycle) * [Blockchain monitoring](/docs/developers/operations/blockchain-monitoring)