Fixed Treasury Yield API for periodic holder payouts on DALP tokens

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. For the architecture model and feature behaviour, see Fixed Treasury Yield.

Configuration during token creation

Configure the feature during token creation or through the configurable-token feature deployment flow.

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

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

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

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 instead. The schedule claim chains several capped settlements in one request and returns a complete flag.

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.

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

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.

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

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:

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.

Maturity redemption: often paired for coupon-paying bonds.
Fixed treasury yield how-to
Fixed Treasury Yield
Yield coverage statistics
Token lifecycle API operations
Blockchain monitoring

Fixed treasury yield API