Corporate actions
Run dividends, coupons, bonus issues, splits, rights issues, spin-offs, and capital decreases with the Platform API primitives available today.
A corporate action changes what a security pays, how many units exist, or what instrument a holder owns. You execute every standard one today through a small set of composable primitives: yield schedules, mint, burn, transfer, supply cap, and record-date snapshots. This page maps each to its primitives and links to a step-by-step guide with the exact endpoints.
What runs each flow today
Each guide below documents one flow end to end, with a flowchart and the API calls in execution order.
| # | Corporate action | Sub action | How you run it today | Guide |
|---|---|---|---|---|
| 1 | Dividend | Cash dividend | Corporate Actions catalog cashDividend, which declares and snapshots dividend-yield. Holders claim on dividend-yield. | Cash dividend |
| 1 | Dividend | Bonus issue (share dividend) | Record-date snapshot plus batch mint. | Bonus issue |
| 2 | Bond coupon | Bond coupon | Fixed-treasury-yield feature on the bond, holder claims per period. | Bond coupon |
| 3 | Split | Stock split | Record-date snapshot plus per-holder batch mint of the delta. | Stock split and reverse split |
| 3 | Split | Reverse stock split (consolidation) | Record-date snapshot plus per-holder batch burn of the delta. | Stock split and reverse split |
| 4 | Rights issue | Rights issue | Token sale offering restricted to entitled holders, or a direct allotment mint. | Rights issue |
| 5 | Spin-off | Spin-off | New asset creation plus a pro-rata batch mint to parent holders. | Spin-off |
| 6 | Decrease of capital | Decrease of capital | Corporate Actions catalog capitalDecrease (batch burn). | Decrease of capital |
| 7 | Maturity | Final redemption | Corporate Actions catalog maturityRedemption names maturity-redemption. Mature and redeem stay on the feature. | — |
| 8 | Distribution | Fund / real-estate distribution | Corporate Actions catalog distribution over dividend-yield (same declare path as cash dividend). | Cash dividend |
| 9 | Partial redemption | Amortisation | Corporate Actions catalog partialRedemption (announced batch burn). | — |
| 10 | Conversion | Conversion confirm | Corporate Actions catalog conversion names the conversion program. Triggers and convert stay on the feature. | — |
| 11 | Buyback | Issuer tender | Corporate Actions catalog buyback (announced batch burn). | — |
Use POST /api/v2/tokens/{tokenAddress}/corporate-actions to declare a named action. Cash dividends and distributions declare dividend-yield. Bond coupons, maturity redemption, and conversion complete on link to the attached feature. Composition types persist a run and apply stored allocations through chunked mint or burn. First pass has no atomic rebase, market halt, rights instrument, capital-account ledger, or cash remainder. Abort does not roll back applied holders. Yield claims stay on the existing dividend and yield operations. See the Corporate Actions API.
Every guide follows this shape. The sections below cover the building blocks the guides share, so each guide can stay focused on its own sequence.
Record-date snapshot
Entitlement math starts from who held what at the record date. Two reads cover it:
| Read | Endpoint | Use when |
|---|---|---|
| Current holders | GET /api/v2/tokens/{tokenAddress}/holders | The record date is now and transfers are paused. |
| Holders at a past timepoint | GET /api/v2/tokens/{tokenAddress}/historical-balances/holders-at-block?timepoint={unixSeconds} | The record date already passed. |
The historical read requires the token to carry the historical-balances feature, so attach it before you announce a record date, not after. Both reads paginate with a maximum of 200 rows per page; walk every page before you compute allocations. See the historical balances feature reference for checkpoint semantics.
Batch limits
Mutations accept batches, with different ceilings per primitive. Size your runs to these ceilings before you generate the payloads.
| Primitive | Endpoint | Items per request |
|---|---|---|
| Mint | POST /api/v2/tokens/{tokenAddress}/mints | 100 |
| Burn | POST /api/v2/tokens/{tokenAddress}/burns | 100 |
| Standard transfer | POST /api/v2/tokens/{tokenAddress}/transfers | 10,000 |
| Forced transfer | POST /api/v2/tokens/{tokenAddress}/forced-transfers | 10,000 |
Catalog confirm of a composition action (POST /api/v2/tokens/{tokenAddress}/corporate-actions/{id}/confirm) applies stored allocations under one Idempotency-Key even when the holder book needs more than one mint or burn batch. Primitive mint and burn stay available after that run completes or aborts. All amounts are integer strings in the token's base units; see asset decimals.
Reliable execution
Every mutation in these guides returns the standard blockchain mutation envelope: a synchronous result with transaction hashes, or a 202 Accepted with a transactionId and statusUrl when you request asynchronous processing through the Prefer header. Poll GET /api/v2/transaction-requests/{transactionId} or subscribe to its event stream until the transaction confirms. Send one Idempotency-Key per business instruction so a retry reattaches to the accepted request instead of executing twice. The request headers reference documents both headers.
These runs move real value, so treat each one as a ledgered operation: record the announced terms, the snapshot you computed from, every request payload, and every resulting transaction hash. Holder-facing follow-ups such as pending yield claims surface in the actions feed.
Roles
Each primitive checks an asset-level role before it executes. Mint and burn require Supply Management. Feature configuration such as attaching a yield schedule requires the governance role. Forced transfers require the custodian role. Grant the operating wallet only the roles the planned run needs.
Related guides
- Cash dividend pays holders in a cash token.
- Token holders and transfers API reference documents the holder reads and transfer mutations in depth.
- Token lifecycle API reference covers asset creation and the feature operations runbook.