Skip to main content

Holder elections and tradable rights

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 for create, preview, and confirm.

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.

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

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

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

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

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

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:

{
  "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, 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

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).

  • 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.