# Elections and rights

Source: https://docs.settlemint.com/docs/api-reference/guides/corporate-action-elections
Let holders choose whether to take part in a supply change, and exercise and close the rights of a tradable rights issue through the API.

This page covers holder choices in corporate actions: opting in or out of a supply change via holder elections, and exercising or closing rights in a tradable rights issue. See [Corporate actions](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions) for create, preview, and confirm.

## Holder elections [#holder-elections]

A single-leg supply change can let each holder choose whether to participate. Pass `election` in the create or quote body (or inside `terms` on commit) with a future `deadline`, at least two `options`, and a `defaultOption`. Exactly one option sets `settlementLeg: "primary"` (takes the allocation), and the remaining options set `settlementLeg: "none"` (takes nothing).

Past deadlines return `409 election-deadline-invalid` (`DALP-12175`). Types without stored allocations, actions with a cash leg (cash partial redemption, cash buyback, or reverse split cash in lieu), and token-sale rights issues return `409 election-shape-invalid` (`DALP-12176`). Invalid option counts, duplicate keys, or invalid defaults fail request validation.

```json
{
  "election": {
    "deadline": "2026-12-01T12:00:00Z",
    "options": [
      { "key": "take-part", "label": "Take part", "settlementLeg": "primary" },
      { "key": "decline", "label": "Decline", "settlementLeg": "none" }
    ],
    "defaultOption": "take-part"
  }
}
```

### Holder and operator election routes [#holder-and-operator-election-routes]

Holders submit choices between preview and `deadline`. Every `election-*` refusal returns HTTP `409`:

| Route | Who calls | Behaviour and refusals |
| --- | --- | --- |
| `GET /api/v2/tokens/{assetId}/corporate-actions/{corporateActionId}/election` | Any eligible reader | Returns `deadline`, `options`, and `defaultOption` (or `election-absent`, `DALP-12179`). |
| `POST /api/v2/tokens/{assetId}/corporate-actions/{corporateActionId}/election` | Holder's own wallet | Records `holder` and `option` with `Idempotency-Key` (and `walletVerification` on session calls). Resending before deadline replaces the choice. Refusals: `election-closed` (`DALP-12171`), `election-option-invalid` (`DALP-12172`), `election-holder-ineligible` (`DALP-12173`), `election-holder-unauthorized` (`DALP-12174`). |
| `GET /api/v2/tokens/{assetId}/corporate-actions/{corporateActionId}/election/choice/{holder}` | Holder's own wallet | Returns the recorded choice or `choice: null` (`election-holder-unauthorized` for another user's wallet). |
| `GET /api/v2/tokens/{assetId}/corporate-actions/{corporateActionId}/election/tally` | Operator (`supplyManagement`) | Counts eligible holders, submissions (`submittedEntries`), and projected totals including defaults (`entries`, with `none` options totalling `0`). |
| `GET /api/v2/tokens/{assetId}/corporate-actions/{corporateActionId}/election/outcome` | Operator or approver | Lists each holder's option, whether default applies, and `remaining` vs `skipped` (`final: false` before deadline). |

Once any holder votes or `deadline` passes, preview returns `409 election-locked` (`DALP-12178`) so the plan stays fixed. If approval lapses on a locked election, abort and create a new action. Confirm returns `409 election-open` (`DALP-12177`) until `deadline` passes, then skips every holder mapped to a `none` option.

## Exercise and close tradable rights [#exercise-and-close-tradable-rights]

Once a tradable rights issue reaches `completed`, holders exercise whole rights during the subscription window via `POST /api/v2/tokens/{assetId}/corporate-actions/{corporateActionId}/rights-exercises` with `rights` (base units representing whole rights, such as `"5000000000000000000"` for 5 rights on an 18-decimal token), `Idempotency-Key`, and `walletVerification` on session calls.

One transaction from the holder's wallet moves the subscription payment and exercised rights to `payee`, returning `rights`, `cashAmount`, `denominationAsset`, and `status` (`submitted`, `settled`, or `failed`). No second approver is required. Replaying the same `Idempotency-Key` returns the original exercise, while mismatched fields return `CORPORATE_ACTION_IDEMPOTENCY_CONFLICT` and failed attempts require a new key.

Exercise refusals all return HTTP `409`:

- `rights-window-closed` (`DALP-184671`): outside the subscription window.
- `rights-exercise-invalid` (`DALP-184672`): insufficient rights or subscription asset, fractional right, non-completed issue, missing payee, or payee exercising itself.
- `rights-exercise-ineligible` (`DALP-184673`): holder cannot receive new shares.
- `rights-payee-invalid` (`DALP-184675`): payee no longer qualifies to receive payment.

`GET /api/v2/tokens/{assetId}/corporate-actions/{corporateActionId}/rights-exercises/{holder}` (caller's own wallet only, otherwise `404`) returns `rights`, `cashAmount`, `denominationAsset`, `shares`, `sharesIssued`, `excessShares`, `excessCashAmount`, and (after close) `excessAllocated` and `excessRefund`.

### Apply for excess shares [#apply-for-excess-shares]

A holder who exercised every right they hold can apply for additional shares during the subscription window via `POST /api/v2/tokens/{assetId}/corporate-actions/{corporateActionId}/rights-excess-applications` with whole-share `shares` (share-token base units), `Idempotency-Key`, and `walletVerification` on session calls.

Payment moves into escrow held by the organisation's operations signer (not `payee`), returning the exercise shape with `kind: "excess"` and applied shares in `rights`. Multiple applications sum together. In the Investor portal, eligible holders select **Apply for excess shares** on the holding page's rights issue card and confirm with their wallet PIN.

Refusals match exercise rules (`rights-exercise-invalid` if rights remain unexercised or none were exercised, `rights-window-closed`, and `rights-exercise-ineligible`).

#### How excess shares allot and settle [#how-excess-shares-allot-and-settle]

Excess allotments draw solely from lapsed rights (rights still held at close preview minus exercised rights held by `payee`):

- If lapsed rights cover all applications, every applicant receives their full request.
- Otherwise, each applicant receives `floor(lapsedRights * applicantDemand / totalExcessDemand)` whole shares, and rounding remainders are not issued.
- Quote lists every applicant in `rightsExcess` (`applied`, `allocated`, `paid`, `refund`), covered by the same maker-checker approval as the rest of the close.

Confirm mints exercised and allotted excess shares together, burns all rights, pays `payee` from escrow for allotted shares, and refunds remaining escrow balances to applicants (`snapshot.rightsExcess` moves from `remaining` to `applied`). If an escrow transfer stalls or fails, the close stays `executing` (cannot be aborted while transfers are queued) and another confirm retries remaining transfers. Changed applications or lapsed rights after preview fail confirm with `snapshot-drift`.

#### Frozen applicants and withheld refunds [#frozen-applicants-and-withheld-refunds]

If an applicant's address is frozen on the subscription asset when refunds run, the close withholds their refund in escrow so the payee and other applicants still settle:

```json
{
  "holder": "0x2546bcd3c84621e976d8185a91a922ae77ecec30",
  "applied": "3000000000000000000",
  "allocated": "1000000000000000000",
  "paid": "3000",
  "refund": "2000",
  "state": "applied",
  "cashOwed": { "amount": "2000", "reason": "frozen" }
}
```

`cashOwed.reason` is `"restricted"` if the wallet also carries an active [wallet restriction](https://docs.settlemint.com/docs/console/participants/restrict-a-wallet), and `"frozen"` otherwise. After unfreezing, raise a close follow-up with `followsUpOn` to send withheld refunds without repaying the payee or duplicating prior mints and burns, stamping `cashOwed.paidBy` once settled.

#### Closing the rights issue [#closing-the-rights-issue]

After `subscriptionEnd`, raise a `rightsIssue` on the share token with `path: "close"` and `rightsIssueId`. Confirm mints new shares, then burns exercised and lapsed rights (except skipped restricted holders, see [Restricted holders](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions#restricted-holders)).

- **Not ready (`rights-close-not-ready`, `DALP-184674`):** Returned before `subscriptionEnd`, while an exercise is settling, when another close is open or completed, or when following up on a close that left nothing unsettled.
- **Follow-ups:** Follow up on an aborted close (skipping already minted holders) or a completed close with skipped share mints, unburned lapsed rights, or unpaid `cashOwed` refunds using `followsUpOn`. Duplicate or mismatched follow-ups return `follow-up-unknown`. Balance or exercise changes after preview return `snapshot-drift`.