Pay a cash dividend on a tokenized equity with the Platform API

Pay holders a cash dividend with the fixed-treasury-yield feature or a one-off record-date distribution.

A cash dividend pays each holder an amount of a cash token in proportion to their equity position. You have two execution models today. A recurring program runs on the fixed-treasury-yield feature, which accrues per period and lets holders claim. A one-off distribution snapshots holders at the record date and pushes the cash token to each of them.

Rendering diagram...

Choose the recurring model when the dividend repeats on a fixed calendar, because accrual, entitlement, and payout tracking then run on-chain without per-run snapshot math. Choose the one-off model for a special dividend, or when holders should receive cash without taking a claim step.

Prerequisites

Recurring model: API key for a wallet with the governance role on the equity.
One-off model: read access to the equity and a funded distribution wallet holding the cash token.
A cash token on the platform (stablecoin or deposit) to pay the dividend in.
For the one-off model with a past record date: the equity carries the historical-balances feature.
Holders pass the cash token's compliance checks, since a dividend payment is a transfer of that token.

Recurring dividend program

Attach the fixed-treasury-yield feature

One call deploys the schedule and attaches it to the equity. The rate is in basis points per period against basisPerUnit, the cash value backing one token unit.

curl -X POST "https://your-platform.example.com/api/v2/tokens/0x9459D52E60edBD3178f00F9055f6C117a21b4220/features" \
  -H "X-Api-Key: sm_dalp_test_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "fixed-treasury-yield",
    "denominationAsset": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "basisPerUnit": "1000000",
    "treasury": "0x3f5CE5FBFe3E9af3971dD833D26bA9b5C936f0bE",
    "startDate": "2026-09-01T00:00:00Z",
    "endDate": "2027-09-01T00:00:00Z",
    "rate": 125,
    "interval": "QUARTERLY"
  }'

interval accepts HOURLY, DAILY, WEEKLY, MONTHLY, QUARTERLY, SEMI_ANNUAL, and YEARLY. With basisPerUnit of 1,000,000 (one unit of a six-decimal cash token) and a rate of 125, each token accrues 1.25 percent of that basis per quarter.

Fund the treasury and approve the allowance

Claims pull from the treasury wallet, so it needs both balance and allowance before the first period completes.

POST /api/v2/tokens/{tokenAddress}/features/fixed-treasury-yield/top-ups transfers cash from the caller's wallet into the treasury.
POST /api/v2/tokens/{tokenAddress}/features/fixed-treasury-yield/treasury-allowance has the treasury wallet approve the schedule to pay claims. The treasury wallet signs this call.

Size the funding from GET /api/v2/tokens/{tokenAddress}/stats/yield-coverage, which reports how much of the accrued, unclaimed dividend the current treasury balance and allowance cover.

Holders claim after each period

Entitlement per period comes from on-chain balance history, so a holder who sells before a period completes accrues nothing for it. Each holder, or your integration acting for them, claims all completed periods in one call.

curl -X POST "https://your-platform.example.com/api/v2/tokens/0x9459D52E60edBD3178f00F9055f6C117a21b4220/features/fixed-treasury-yield/claims" \
  -H "X-Api-Key: sm_dalp_test_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{}'

Pending claims also surface to each holder in the actions feed.

Monitor the program

Three reads keep the program observable: GET .../stats/yield-coverage for funding health, GET .../stats/yield-distribution for accrued versus claimed over time, and GET .../yield/holder-periods/{holderAddress} for one holder's claim history. GET .../treasury/health rolls treasury balance and allowance into one status.

One-off special dividend

The one-off model fits a special dividend that repeats on no calendar, and it pays holders without a claim step because you push the cash to them.

Snapshot holders at the record date

Read every holder balance at the record-date timepoint, paginating until you have the full set.

curl "https://your-platform.example.com/api/v2/tokens/0x9459D52E60edBD3178f00F9055f6C117a21b4220/historical-balances/holders-at-block?timepoint=1772323200&limit=200" \
  -H "X-Api-Key: sm_dalp_test_xxxxxxxxxxxxxxxx"

If the record date is now, pause the equity or pick a quiet window and read GET .../holders instead.

Compute and pay per holder

Multiply each snapshot balance by the dividend per unit, round down to the cash token's base units, and record the rounding remainder. Then push the cash token from your distribution wallet in groups of up to 10,000 transfers.

curl -X POST "https://your-platform.example.com/api/v2/tokens/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/transfers" \
  -H "X-Api-Key: sm_dalp_test_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: dividend-nwih-2026-q3-batch-001" \
  -H "Content-Type: application/json" \
  -d '{
    "transferType": "standard",
    "transfers": [
      { "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "amount": "1250000" },
      { "recipient": "0x8ba1f109551bD432803012645Ac136ddd64DBA72", "amount": "312500" }
    ]
  }'

Batches above 10 items run as chunked durable execution, so reconcile every returned transaction hash; see standard transfer batching.

Reconcile

Confirm each transaction through GET /api/v2/transaction-requests/{transactionId} or the returned hashes, then check that the sum of paid amounts plus the recorded rounding remainder equals the declared dividend pool. A recipient who fails the cash token's compliance checks reverts the batch transaction that contains them, while chunks already settled in a large run stay on-chain. Remove the failing holder, rerun the remainder under a fresh Idempotency-Key, and resolve that holder's eligibility separately.

Operational notes

The recurring model is pull-based: unclaimed dividends stay in the treasury and remain claimable while the schedule allows, so track outstanding claims with the distribution stats instead of assuming payout on period end.
Amounts are integer strings in the cash token's base units; see asset decimals.
State your rounding policy in the dividend announcement. Rounding down per holder is the common choice and leaves a small remainder in the distribution wallet.

Bond coupon uses the same feature on fixed-income assets.
Bonus issue pays the dividend in shares instead of cash.
Fixed treasury yield API reference documents every endpoint and parameter of the feature.

Cash dividend