# Spin-off

Source: https://docs.settlemint.com/docs/developers/corporate-actions/spin-off
Distribute a new instrument pro-rata to the holders of an existing one by creating the new asset and batch minting against a record-date snapshot.



A spin-off distributes units of a new, separate instrument to the holders of an existing one, in proportion to their holdings. The platform has no single spin-off primitive today, so you compose three steps: create the new asset, snapshot the parent's holders at the record date, and batch mint the new instrument to those holders at the distribution ratio.

<Mermaid
  chart="flowchart TD
  Create[&#x22;Create the spin-off asset<br/>POST /tokens&#x22;] --> Eligibility[&#x22;Verify holder eligibility<br/>on the new asset's compliance rules&#x22;]
  Eligibility --> Snapshot[&#x22;Snapshot parent holders at record date<br/>GET /tokens/{parent}/historical-balances/holders-at-block&#x22;]
  Snapshot --> Compute[&#x22;Compute allocation per holder<br/>parent balance x ratio, round down&#x22;]
  Compute --> Mint[&#x22;Batch mint the new asset<br/>POST /tokens/{spinoff}/mints&#x22;]
  Mint --> Verify[&#x22;Verify supply and balances<br/>on the new asset&#x22;]"
/>

## Prerequisites [#prerequisites]

* API key for a wallet authorized to create assets, plus the Supply Management role on the new asset once created.
* The parent asset carries the historical-balances feature if the record date lies in the past.
* The new asset's compliance configuration admits the parent's holder base, since each mint enforces recipient eligibility on-chain.

## Running the spin-off [#running-the-spin-off]

<Steps>
  <Step>
    ### Create the spin-off asset [#create-the-spin-off-asset]

    `POST /api/v2/tokens` deploys the new instrument with its own type, compliance modules, and roles. Model the spun-off business with the asset class that fits it (equity, fund, or another class); the distribution mechanics below are the same for all classes. The [token lifecycle reference](/docs/api-reference/tokens/token-lifecycle) documents the create call and its per-class fields. Leave the new asset paused until the distribution completes if you want no secondary transfers before all holders are served.
  </Step>

  <Step>
    ### Verify holder eligibility on the new asset [#verify-holder-eligibility-on-the-new-asset]

    Every recipient must pass the new asset's compliance checks at mint time. Before you distribute, confirm the parent's holders carry the claims the new asset requires; where the new asset reuses the parent's compliance configuration this is already given. Handle the exceptions (holders who fail the new asset's rules) as separate cases before your mint run, not during it.
  </Step>

  <Step>
    ### Snapshot the parent's holders [#snapshot-the-parents-holders]

    Read the parent's full holder set at the record date, walking every page of the result.

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

    Compute each allocation as `floor(parent balance x distribution ratio)`. Record the rounding remainders your policy leaves behind, because the verification step reconciles against them.
  </Step>

  <Step>
    ### Batch mint the new asset to parent holders [#batch-mint-the-new-asset-to-parent-holders]

    Mint on the new asset's address, in groups of up to 100 recipients. Give each request its own `Idempotency-Key` so a timed-out call retries safely instead of minting twice.

    ```bash
    curl -X POST "https://your-platform.example.com/api/v2/tokens/0x5bE39c3D8beD22B6ff8Eb0BEEEfD32Fa50e14D63/mints" \
      -H "X-Api-Key: sm_dalp_test_xxxxxxxxxxxxxxxx" \
      -H "Idempotency-Key: spinoff-nwlog-2026-batch-001" \
      -H "Content-Type: application/json" \
      -d '{
        "recipients": [
          "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
          "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
        ],
        "amounts": [
          "500000000000000000000",
          "125000000000000000000"
        ]
      }'
    ```

    A batch fails whole if one recipient fails compliance, so the eligibility pass in the previous step is what keeps the run smooth. Remove a failing holder, rerun the batch under a fresh `Idempotency-Key`, and resolve that holder separately.
  </Step>

  <Step>
    ### Verify and open the new asset [#verify-and-open-the-new-asset]

    Confirm every transaction, check the new asset's total supply against your allocation table, and spot-check holder balances. If you created the asset paused, unpause it with `DELETE /api/v2/tokens/{tokenAddress}/pause-state` once the distribution reconciles.
  </Step>
</Steps>

## Operational notes [#operational-notes]

* The parent asset is untouched: a spin-off distributes a new instrument, it does not reduce parent balances. Pair it with a [decrease of capital](/docs/developers/corporate-actions/capital-decrease) on the parent when the transaction's terms require one.
* The distribution is a series of mints, so the new asset's supply history starts with the distribution itself; keep the parent snapshot and allocation table as the provenance record linking the two instruments.
* Fractional entitlements round down per holder; announce the rounding policy and settle remainders in cash if the terms require it, following the one-off path in the [cash dividend guide](/docs/developers/corporate-actions/cash-dividend).

## Related guides [#related-guides]

* [Rights issue](/docs/developers/corporate-actions/rights-issue) offers a new instrument for consideration instead of distributing it free.
* [Token lifecycle API reference](/docs/api-reference/tokens/token-lifecycle) documents asset creation and initial configuration.
* [Mint assets with the API](/docs/developers/asset-servicing/mint-assets) covers mint controls and failure handling in depth.