# Bonus issue

Source: https://docs.settlemint.com/docs/developers/corporate-actions/bonus-issue
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.

<Mermaid
  chart="flowchart TD
  Announce[&#x22;Announce terms<br/>(ratio, record date)&#x22;] --> Snapshot[&#x22;Snapshot holders at record date<br/>GET .../historical-balances/holders-at-block&#x22;]
  Snapshot --> Compute[&#x22;Compute bonus per holder<br/>balance x ratio, round down&#x22;]
  Compute --> Mint[&#x22;Batch mint the bonus shares<br/>POST /tokens/{token}/mints&#x22;]
  Mint --> Compliance[&#x22;Token compliance checks<br/>run per recipient on-chain&#x22;]
  Compliance --> Verify[&#x22;Verify total supply<br/>and holder balances&#x22;]"
/>

## Prerequisites [#prerequisites]

* API key for a wallet with the Supply Management role on the equity (see [Getting started](/docs/api-reference/reference/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 [#running-the-bonus-issue]

<Steps>
  <Step>
    ### Snapshot holders at the record date [#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.

    ```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"
    ```

    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.
  </Step>

  <Step>
    ### Compute the bonus per holder [#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.
  </Step>

  <Step>
    ### Batch mint the new shares [#batch-mint-the-new-shares]

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

    ```bash
    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.
  </Step>

  <Step>
    ### Verify the result [#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.
  </Step>
</Steps>

## Operational notes [#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.

## Related guides [#related-guides]

* [Cash dividend](/docs/developers/corporate-actions/cash-dividend) pays the dividend in cash instead of shares.
* [Stock split and reverse split](/docs/developers/corporate-actions/stock-split) uses the same snapshot-and-mint mechanics with a ratio applied to every holder.
* [Mint assets with the API](/docs/developers/asset-servicing/mint-assets) covers mint roles, controls, and failure modes in depth.