# Cash dividend
Source: https://docs.settlemint.com/docs/developers/corporate-actions/cash-dividend
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.
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 [#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 [#recurring-dividend-program]
### Attach the fixed-treasury-yield feature [#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.
```bash
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 [#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 [#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.
```bash
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](/docs/api-reference/reference/actions).
### Monitor the program [#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 [#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 [#snapshot-holders-at-the-record-date]
Read every holder balance at the record-date timepoint, paginating until you have the full set.
```bash
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 [#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.
```bash
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](/docs/api-reference/tokens/token-holders-transfers#standard-transfer-batching).
### Reconcile [#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 [#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](/docs/api-reference/reference/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.
## Related guides [#related-guides]
* [Bond coupon](/docs/developers/corporate-actions/bond-coupon) uses the same feature on fixed-income assets.
* [Bonus issue](/docs/developers/corporate-actions/bonus-issue) pays the dividend in shares instead of cash.
* [Fixed treasury yield API reference](/docs/api-reference/token-features/fixed-treasury-yield) documents every endpoint and parameter of the feature.