# Rights issue

Source: https://docs.settlemint.com/docs/developers/corporate-actions/rights-issue
Offer new shares to existing holders pro-rata, either as a subscription offering through a token sale or as a direct allotment mint.



A rights issue offers existing holders the chance to buy new shares pro-rata at a set price before the offer opens to anyone else. You run it today in one of two ways: a subscription offering through the token sale addon, whitelisted to entitled holders, or a direct allotment mint when every subscription is already agreed off-platform.

<Mermaid
  chart="flowchart TD
  Announce[&#x22;Announce terms<br/>(ratio, price, window)&#x22;] --> Snapshot[&#x22;Snapshot entitled holders<br/>GET .../historical-balances/holders-at-block&#x22;]
  Snapshot --> Path{&#x22;Subscription window<br/>or pre-agreed allotment?&#x22;}
  Path -->|Subscription| Sale[&#x22;Deploy the offering<br/>POST /addons/token-sales&#x22;]
  Sale --> Whitelist[&#x22;Whitelist entitled holders<br/>POST /addons/token-sale-presale-whitelist-entries&#x22;]
  Whitelist --> Activate[&#x22;Open the window<br/>POST /addons/token-sale-activations&#x22;]
  Activate --> Subscribe[&#x22;Holders subscribe and pay<br/>POST /addons/token-sale-purchases&#x22;]
  Subscribe --> Close[&#x22;Close and finalize<br/>POST /addons/token-sale-closures, .../token-sale-finalizations&#x22;]
  Close --> Settle[&#x22;Withdraw proceeds and unsold shares<br/>POST .../token-sale-fund-withdrawals&#x22;]
  Path -->|Allotment| Mint[&#x22;Batch mint subscribed shares<br/>POST /tokens/{token}/mints&#x22;]
  Mint --> Reconcile[&#x22;Reconcile against subscriptions&#x22;]
  Settle --> Reconcile"
/>

Choose the subscription path when holders decide during a live window and pay on-platform. Choose the allotment path when subscription and payment settle off-platform and the on-chain step is only the share delivery.

## Prerequisites [#prerequisites]

* Subscription path: API key for a wallet authorized to deploy and manage token sale offerings, and a payment currency configured for the sale.
* Allotment path: API key for a wallet with the Supply Management role on the equity.
* The equity carries the historical-balances feature if the record date lies in the past.
* Cap headroom for the new shares on a capped token, or a cap raise first.

## Subscription offering [#subscription-offering]

<Steps>
  <Step>
    ### Snapshot entitlement [#snapshot-entitlement]

    Read holders at the record date with `GET /api/v2/tokens/{tokenAddress}/historical-balances/holders-at-block?timepoint={unixSeconds}&limit=200`, paginating to the full set, and compute each holder's entitlement as `floor(balance x ratio)` new shares at the subscription price. Publish the entitlement table to your subscription ledger before the window opens, because it is the basis for the whitelist and for the post-close reconciliation.
  </Step>

  <Step>
    ### Deploy and gate the sale [#deploy-and-gate-the-sale]

    Create the offering with `POST /api/v2/addons/token-sales`, supplying the sale token, price, window, and hard cap equal to the offer size. Then load the entitled holders into the presale whitelist with `POST /api/v2/addons/token-sale-presale-whitelist-entries`, so only rights holders can subscribe during the window. The [token sale offering flows reference](/docs/api-reference/offerings/token-sale-offering-flows) documents every field of these calls.
  </Step>

  <Step>
    ### Open the window and take subscriptions [#open-the-window-and-take-subscriptions]

    Activate with `POST /api/v2/addons/token-sale-activations`, which opens the subscription window. During the window each holder subscribes with `POST /api/v2/addons/token-sale-purchases`, paying in the configured currency, and the sale enforces the whitelist and per-buyer limits on-chain. Track take-up as you go by reading the sale state at `GET /api/v2/addons/token-sales/{saleAddress}`.
  </Step>

  <Step>
    ### Close, finalize, settle [#close-finalize-settle]

    At the end of the window, close with `POST /api/v2/addons/token-sale-closures` and finalize with `POST /api/v2/addons/token-sale-finalizations`. Withdraw the subscription proceeds with `POST /api/v2/addons/token-sale-fund-withdrawals` and reclaim unsold shares with `POST /api/v2/addons/token-sale-unsold-token-withdrawals`. Unsubscribed rights lapse when the window closes.
  </Step>
</Steps>

## Direct allotment [#direct-allotment]

When subscriptions and payment settle off-platform, deliver the shares as a batch mint to the subscribing holders. Send up to 100 recipients per request, with one `Idempotency-Key` each.

```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: rights-nwih-2026-allotment-001" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"],
    "amounts": ["50000000000000000000"]
  }'
```

Reconcile the minted amounts against the subscription ledger, and record the off-platform payment references with the transaction hashes.

## Operational notes [#operational-notes]

* The platform does not model tradeable nil-paid rights today. The right exists as a whitelist entry plus an entitlement in your subscription ledger, not as a transferable instrument.
* Compliance runs on the share delivery: a subscriber must pass the equity's compliance checks at purchase or mint time, so verify eligibility before the window opens rather than during settlement.
* For partial take-up, decide before the window opens whether unsold shares lapse or move to a second round, and size the sale's hard cap to the full offer either way.

## Related guides [#related-guides]

* [Bonus issue](/docs/developers/corporate-actions/bonus-issue) distributes new shares without consideration.
* [Spin-off](/docs/developers/corporate-actions/spin-off) delivers a different instrument to the same entitled holder base.
* [Token sale offering flows reference](/docs/api-reference/offerings/token-sale-offering-flows) documents the full offering lifecycle, including refunds and vesting.