# Corporate actions

Source: https://docs.settlemint.com/docs/developers/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 [#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](/docs/developers/corporate-actions/cash-dividend)               |
| 1 | Dividend            | Bonus issue (share dividend)        | Record-date snapshot plus batch mint.                                                                        | [Bonus issue](/docs/developers/corporate-actions/bonus-issue)                   |
| 2 | Bond coupon         | Bond coupon                         | Fixed-treasury-yield feature on the bond, holder claims per period.                                          | [Bond coupon](/docs/developers/corporate-actions/bond-coupon)                   |
| 3 | Split               | Stock split                         | Record-date snapshot plus per-holder batch mint of the delta.                                                | [Stock split and reverse split](/docs/developers/corporate-actions/stock-split) |
| 3 | Split               | Reverse stock split (consolidation) | Record-date snapshot plus per-holder batch burn of the delta.                                                | [Stock split and reverse split](/docs/developers/corporate-actions/stock-split) |
| 4 | Rights issue        | Rights issue                        | Token sale offering restricted to entitled holders, or a direct allotment mint.                              | [Rights issue](/docs/developers/corporate-actions/rights-issue)                 |
| 5 | Spin-off            | Spin-off                            | New asset creation plus a pro-rata batch mint to parent holders.                                             | [Spin-off](/docs/developers/corporate-actions/spin-off)                         |
| 6 | Decrease of capital | Decrease of capital                 | Batch burn, optional supply-cap reduction, optional cash return.                                             | [Decrease of capital](/docs/developers/corporate-actions/capital-decrease)      |

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.

<Mermaid
  chart="flowchart LR
  Terms[&#x22;Define terms<br/>(ratio, rate, record date)&#x22;] --> Snapshot[&#x22;Snapshot entitled holders<br/>at the record date&#x22;]
  Snapshot --> Compute[&#x22;Compute per-holder amounts&#x22;]
  Compute --> Execute[&#x22;Execute the primitives<br/>(mint, burn, transfer, claim)&#x22;]
  Execute --> Track[&#x22;Track transactions<br/>to finality&#x22;]
  Track --> Reconcile[&#x22;Reconcile balances<br/>and report&#x22;]"
/>

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 [#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](/docs/api-reference/token-features/historical-balances) for checkpoint semantics.

## Batch limits [#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](/docs/api-reference/reference/asset-decimals).

## Reliable execution [#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](/docs/api-reference/reference/request-headers) 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](/docs/api-reference/reference/actions).

## Roles [#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 [#related-guides]

* [Cash dividend](/docs/developers/corporate-actions/cash-dividend) pays holders in a cash token.
* [Token holders and transfers API reference](/docs/api-reference/tokens/token-holders-transfers) documents the holder reads and transfer mutations in depth.
* [Token lifecycle API reference](/docs/api-reference/tokens/token-lifecycle) covers asset creation and the feature operations runbook.