Interest yield API

The interest-yield feature accrues interest continuously on each holder balance at an annual rate. There is no period calendar and no declaration step. Holders claim the accrued amount from the configured treasury in the denomination asset, and a paired conversion can consume that accrued interest instead of paying it in cash.

For operator workflow guidance, see Interest yield how-to. For the architecture model and feature behaviour, see Interest Yield.

Configuration

The feature is configured either in the token-creation request or by attaching it to an existing configurable token. The two flows take the same values but not the same contract, so they are documented separately. Both require historical-balances in the same feature set.

In the token-creation request

{
  "interest-yield": {
    "denominationAsset": "0x1111111111111111111111111111111111111111",
    "treasury": "0x2222222222222222222222222222222222222222",
    "annualRateBps": 500,
    "startDate": "1735689600"
  }
}

When attaching to an existing token

The attach request carries the same four values, with two differences. treasury is required. startDate is optional, and on an existing token you should omit it so accrual starts at attachment time.

Omitting it is also the reliable choice. Accrual begins when the feature is attached, which is the only start a token that already has holders should use: the feature keeps no record of how long each balance was held, so a backdated start pays the whole elapsed accrual on whatever balance a holder has at their first settlement.

DALP validates these fields before queuing feature deployment. The denomination asset, the treasury, and the start date are fixed once the feature is configured. Only the rate changes afterwards.

Feature operations

Interest yield exposes token feature operations under /api/v2/tokens/{tokenAddress}/features/interest-yield.

Mutation responses use DALP's asynchronous blockchain mutation envelope and return the updated token resource when the queued operation completes.

Rate changes

Both rate endpoints take the same body:

{
  "annualRateBps": "450"
}

annualRateBps must be at least 1 and not more than 20000 basis points. The change is forward-looking: interest earned under the old rate is committed before the new rate applies, so a rate update never rewrites what a holder has already earned. A rate change is rejected while the feature is paused.

Claim behaviour

The claim endpoint takes no amount. The feature settles the caller, then pays the whole accrued balance from the treasury.

A claim is rejected when the accrued amount is zero, when the feature is paused, or when the schedule is not configured. A holder whose accrued interest was consumed by a conversion has nothing left to claim in cash.

The claim depends on the treasury payout path. When the treasury is a wallet, it must approve the feature to spend the denomination asset, and the approved allowance must keep up as the liability grows. A treasury contract that implements the vault payout interface handles payouts internally and needs no approval step.

Read a holder's position

GET /api/v2/tokens/{tokenAddress}/features/interest-yield/holder-position returns the caller's accruedExact, userIndexExact, and totalClaimedExact, with the block and time of their last claim. Use accruedExact to show a holder what they can claim before they submit.

accruedExact combines the amount settled on chain with a live projection of what has accrued since. The projection does not reconcile a difference in decimals between the asset token and the denomination asset, and the error runs in either direction. When the asset token carries more decimals than the denomination asset the projection is too large; when the denomination asset carries more, it is too small. Do not treat it as a conservative figure in either case. Treat accruedExact as indicative on a mixed-decimal asset and take the settled amount from the claim itself. The payout is unaffected: the contract does reconcile the precision.

Read the rate history and issuer position

GET /api/v2/tokens/{tokenAddress}/features/interest-yield/rate-history lists each rate change with oldRateBps, newRateBps, globalIndexExact, daycountConvention, the update block and time, and the transaction hash and log index. It records rate changes only, so it does not carry the rate the feature started with. To reconstruct a window that begins before the first change, take the configured starting rate from the feature configuration and use this list for everything after it. It sorts by update time and accepts filters on updatedAt and newRateBps.

GET /api/v2/tokens/{tokenAddress}/features/interest-yield/issuer-stats returns pendingExact as of a stated asOf moment, together with the paused flag. Compare pendingExact against the treasury denomination balance to monitor funding. Because accrual is continuous, monitor it continuously rather than on a coupon calendar. pendingExact carries the same mixed-decimal caveat as accruedExact above. It can understate the liability as easily as overstate it, so do not size a treasury top-up from it when the asset token and the denomination asset use different decimals.

Top up treasury

The top-up operation transfers the requested denomination-asset amount from the caller's wallet to the configured treasury. It is a plain ERC-20 transfer; the feature itself never holds the denomination asset. The amount must be greater than zero.

{
  "amount": "2500000000"
}

Conversion integration

When the asset also uses conversion, interest yield acts as the interest provider for it. The conversion configuration must opt in: includeInterestInConversion is false by default, and while it is false a conversion ignores accrued interest and leaves it as a cash claim. Set that flag in the creation request.

Leave conversion.interestProvider unset when the two features are created together. The interest feature has no address yet at that point, and the conversion discovers the single attached provider on its own. Set it only to an already-deployed provider, and only when the token carries more than one, because the value is part of the immutable conversion configuration: a wrong or unrelated address binds permanently.

Token creation wires the rest: it authorises the conversion feature as the consumer and, for a conversion that locks principal in an escrow account, excludes that escrow from accrual. Neither write has a public route, and the authorisation cannot be changed once set, so supply the conversion configuration correctly in the creation request. Attaching interest yield to a token that already carries conversion does not run this wiring.

Once wired, the conversion can consume a holder's accrued interest with a stated reason, or close accrual for a holder whose position is fully converted. Consumed interest is permanently unavailable as cash, and closing accrual leaves the already earned amount claimable.

Related

• Interest Yield architecture
• Interest yield how-to
• Conversion API
• Dividend yield API
• Token lifecycle API operations