Run a bonus issue on a tokenized equity with the Platform API

Distribute free shares pro-rata to existing holders with a record-date snapshot and a batch mint.

A bonus issue (share dividend or scrip issue) gives every holder new shares in proportion to their existing position, at no cost to them. You run it as a snapshot plus a batch mint: read who held what at the record date, multiply by the announced ratio, and mint the result to each entitled wallet.

Rendering diagram...

Prerequisites

API key for a wallet with the Supply Management role on the equity (see Getting started).
The equity carries the historical-balances feature if the record date lies in the past.
Headroom under the supply cap when the token is capped, or a cap raise through PATCH /api/v2/tokens/{tokenAddress}/supply-cap first.
The equity is unpaused, since mint requests against a paused asset are rejected.

Running the bonus issue

Snapshot holders at the record date

Read the full holder set at the record-date timepoint, paginating with limit=200 until every page is consumed.

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"

For a record date of "now", pause transfers or pick a quiet window and read GET .../holders instead, so no transfer lands between your snapshot and your mint.

Compute the bonus per holder

Multiply each snapshot balance by the bonus ratio and round down to a whole number of base units. For a 1-for-10 bonus, a holder with 1000000000000000000000 base units (1,000 shares at 18 decimals) receives 100000000000000000000. Record the rounding remainders, and state in your announced terms that fractions round down.

Batch mint the new shares

Mint in groups of up to 100 recipients, one Idempotency-Key per request.

curl -X POST "https://your-platform.example.com/api/v2/tokens/0x9459D52E60edBD3178f00F9055f6C117a21b4220/mints" \
  -H "X-Api-Key: sm_dalp_test_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: bonus-nwih-2026-batch-001" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
    ],
    "amounts": [
      "100000000000000000000",
      "25000000000000000000"
    ]
  }'

The token contract enforces compliance per recipient during execution, so a holder who lost eligibility since the record date reverts the batch that contains them. If a batch reverts, remove the failing holder, rerun the batch with a fresh Idempotency-Key, and handle the excluded holder as its own case.

Verify the result

Confirm every transaction, then check GET /api/v2/tokens/{tokenAddress}/stats/total-supply against the expected post-issue supply and spot-check holder balances through GET .../holders. The sum of minted amounts must equal the expected bonus pool minus recorded rounding remainders.

Operational notes

A bonus issue increases share count without new consideration, so pair the mint with an updated price feed if the asset carries one; the per-share reference price falls by the bonus ratio.
Mint batches are atomic: all recipients in a request succeed or the request fails. Smaller batches localize failures at the cost of more requests.
Keep your snapshot export, your computed allocation table, and every transaction hash as the audit record of the issue.

Cash dividend pays the dividend in cash instead of shares.
Stock split and reverse split uses the same snapshot-and-mint mechanics with a ratio applied to every holder.
Mint assets with the API covers mint roles, controls, and failure modes in depth.

Bonus issue