Dividend yield API

The dividend-yield feature pays declared cash distributions to the holders of record on a fixed date. Governance declares an amount per token unit, the platform computes the entitlement set at the record date and records it as a Merkle root, and each entitled holder claims their exact amount from the configured treasury in the denomination asset.

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

Configuration

Configure the feature in the token-creation request or by attaching it to an existing configurable token. Both flows take the three values below and both require historical-balances in the same feature set. The one difference: treasury is optional on creation and required on an attach request.

{
  "dividend-yield": {
    "denominationAsset": "0x1111111111111111111111111111111111111111",
    "treasury": "0x2222222222222222222222222222222222222222",
    "defaultClaimDeadlineDays": 90
  }
}

DALP validates the addresses before queuing feature deployment. The positive-value rule on defaultClaimDeadlineDays is enforced by the contract rather than by the attach request, so a zero or negative value on that path is queued and then fails at deployment instead of at request time. Attachment also fails when the token has no historical balances provider.

Feature operations

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

Mutation responses use DALP's asynchronous blockchain mutation envelope and return the updated token resource when the queued operation completes. The snapshot preview is the one exception: it returns a preview body and queues nothing.

Declare a dividend

{
  "amountPerShare": "50000",
  "exDate": "1798761600",
  "recordDate": "1798848000",
  "paymentDate": "1798934400",
  "claimDeadline": "1806710400",
  "countryCode": "US"
}

The timestamps are placeholders. exDate is rejected on chain unless it is later than the block timestamp of the declaration, so derive the four dates from your own payment calendar at submission time rather than copying these values.

Declaration reserves an expected funding liability computed from the total supply at that moment. Recording the snapshot replaces that estimate with the exact total required.

Record the snapshot

Recording is a two-step operation on the same endpoint. Send the body without confirm, or with confirm set to false, to preview:

{
  "stage": "preview",
  "ready": true,
  "rootPreview": "0xabcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
  "totalEntitled": "128",
  "holderCount": 128,
  "totalRequired": "2500000000",
  "denomBalanceAtRecord": "2000000000",
  "shortfall": "500000000"
}

denomBalanceAtRecord is the effective funding read at preview time, not at the record date: for a wallet treasury it is the lower of the treasury balance and the allowance approved to the feature, and for a vault treasury it is the balance. shortfall is what is still missing to cover totalRequired. Fund the treasury, and approve the allowance, before you confirm.

Send confirm set to true with merkleRoot, totalEntitled, and totalRequired copied from the preview to record the snapshot on chain. DALP rejects the confirmation when any echoed value differs from the freshly computed result, so a stale preview can never be recorded.

The preview reports ready as false with notReadyReason set to awaiting_finality while the record-date block has not reached finality. A confirmation sent in that window is rejected instead of queued.

Claim behaviour

The claim endpoint takes no entitlement fields. DALP resolves the leaf index, the amount, and the Merkle proof for the effective wallet from the recorded snapshot and submits the claim with them. When no entitlement row exists for the caller, the claim is rejected before it enters the queue.

The on-chain claim additionally requires that the payment date has passed, that the dividend is neither cancelled nor closed, that the leaf is not already claimed, and that the identity of the claimant is still verified. Identity is applied at both ends: a holder whose identity is already lost when the entitlement set is computed is left out of the Merkle tree, and a holder in the tree whose identity is no longer verified at claim time has the claim refused.

The claim deadline does not close claims. It only lets governance reclaim, and a valid proof stays payable until that reclaim runs, so do not gate claims on the deadline in your own client. Once a reclaim closes the dividend, its remaining entitlements are no longer claimable.

Read a holder's proof and position

GET /api/v2/tokens/{tokenAddress}/features/dividend-yield/dividends/{dividendId}/proofs/me returns the caller's recorded entitlement for one dividend: leafIndex, amountExact, the proof array, and the block the snapshot was computed at. This is the original entitlement and the proof needed to claim it. It is the frozen snapshot leaf and does not change: it reports the same values after the holder has claimed and after governance has reclaimed the dividend.

The Platform API cannot currently tell you whether one holder has claimed one dividend. This read carries no claim flag, the holder-position read carries lifetime totals across all dividends, and the dividend list carries a dividend-wide status. So an entitlement here is not evidence that it is still claimable, and a client cannot derive a remaining per-dividend amount from these reads. Submitting is safe regardless: the contract rejects a claim on a leaf that is already spent.

GET /api/v2/tokens/{tokenAddress}/features/dividend-yield/holder-position returns totalClaimedExact for the caller with the block and time of their last claim. It totals every dividend the holder has claimed, so it is neither a per-dividend figure nor a claimable balance. Do not render it as one.

Read the dividend list and issuer position

GET /api/v2/tokens/{tokenAddress}/features/dividend-yield/dividends lists the dividends of a token with amountPerShareExact, the full date set, status and statusCode, merkleRoot, totalEntitled, totalRequiredExact, and the declaration and recording times. It sorts by payment date, most recent first, and accepts filters on dividendId, paymentDate, and status.

GET /api/v2/tokens/{tokenAddress}/features/dividend-yield/issuer-stats returns stillClaimableExact and expiredReclaimableExact, split on whether the claim deadline has passed. Both count only entitlements that are unclaimed and already payable, on a dividend whose payment date has arrived.

Two things follow. Fund against the sum of the two, because the deadline split is not a payability boundary: an entitlement in expiredReclaimableExact stays payable until governance reclaims, so funding only stillClaimableExact underfunds every post-deadline claim. And treat that sum as the payable-now total rather than the full obligation: a dividend that is recorded but not yet payable has a fixed totalRequired and appears in neither field, so take upcoming payment dates from the dividend list and fund those separately.

Use expiredReclaimableExact to drive the reclaim decision, and treat it as a live obligation until that reclaim settles.

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.

{
  "amount": "2500000000"
}

When the treasury is a wallet, it must also approve the feature to spend the denomination asset before any claim can succeed. A treasury contract that implements the vault payout interface handles payouts internally and needs no approval step.

Related

• Dividend Yield architecture
• Dividend yield how-to
• Historical balances API, the required dependency
• Interest yield API
• Token lifecycle API operations