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 | Fixed-treasury-yield feature (recurring) or a record-date snapshot plus a cash-token distribution (one-off). | 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 | Batch burn, optional supply-cap reduction, optional cash return. | Decrease of capital |
Cash dividends and bond coupons run on a purpose-built feature with its own endpoints. The rest are compositions: you drive the generic supply and transfer primitives from a holder snapshot. The flow is the same for all of them.
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 |
For holder sets larger than one batch, split the run into multiple requests and give each request its own Idempotency-Key. 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.