Skip to main content

Quote and commit a corporate action in one call

Read the plan of a corporate action before you record it, then record, preview and confirm it in one call with one wallet verification.

These calls let you review a corporate action before you record it, then run it with one wallet verification. Corporate actions covers the create, preview and confirm calls that a commit runs for you.

Quote, then commit in one call

A quote shows what an action would do before you record it. A commit then records, previews and confirms it in one call, with one wallet verification instead of one per step.

POST /api/v2/tokens/{assetId}/corporate-actions/quote takes the same body as create and stores nothing. It needs no wallet verification and no Idempotency-Key, and it asks for the same token role as create. The answer lists the plan:

  • holderCount, totalAmount, remainder and denominationShortfall.
  • treasuryUnitsExcluded, the units the treasury held at the record date that a cash dividend or distribution leaves out, or null.
  • rightsBurn, only on the first page of a rights close: the rights the close burns once it has minted the new shares.
  • priceAdjustment, which is null except for a stock split of a share that has a reference price. It carries the currency and the price before and after the split. The split multiplies the price by the denominator and divides it by the numerator, rounded half away from zero at 8 fraction digits, the precision of the price feeds, so an 18:1 reverse split moves 6.00 AED to 108.00 AED and a 3:1 split of 10 AED plans 3.33333333 AED. Quote and preview need only the role the split needs, and refuse a feed that cannot be re-priced with price-unadjustable (HTTP 409, CORPORATE_ACTION_PRICE_UNADJUSTABLE, DALP-184653). Confirm needs the token admin role on top of the supply role, refuses with preview-mismatch when the share's price moved since the preview (abort the split and raise it again), and sets exactly this price once every chunk of holder units has landed. The record's snapshot.priceStep carries state (pending, submitted, settled or failed), attempt, transactionRequestId and, when the step failed, a failure that names why and a failureCode (drifted, refused, queue-failed or stored-unreadable). The action stays executing until the price settles. Confirming a failed step sends the price again once the share's price is back at the approved before, or already at the approved after. While the price is anywhere else, confirm refuses with price-drifted (HTTP 409, CORPORATE_ACTION_PRICE_DRIFTED, DALP-184654), and the message names the price to set. Once every chunk of holder units has landed, abort refuses with run-completed, because only the price update remains. If an abort raced the last chunk and that chunk landed anyway, the action stays aborted while the price update is sent, and a failed step on it is confirmed again the same way: the step moves on and the status stays aborted. On an aborted action, confirm does nothing but that retry: unless the step is failed and every holder update landed, it answers with the record unchanged. A split whose ratio leaves the price unchanged at 8 fraction digits is refused with price-unadjustable. The price history stays as it is. The venue keeps its own price-band anchors.
  • data, a page of holder rows with holder, balance, amount and state. Page it with page[offset] and page[limit], up to 200.
  • acknowledgements, the consequences the commit has to acknowledge.
  • approval, with requirement set to required, not-needed or waived. waived comes with the reason.
  • quoteFingerprint, which equals the planDigest the stored preview of the same plan gets.
  • coordinated, only for a coordinated distribution: every class dividend the commit will declare. It names the waterfallFeature, the denominationAsset of the pool, the appliedDeterminationKind (null for the ordinary split), the poolAmount it moves, and one entry per class with classToken, role, rank, allocation (the slice the waterfall split gives it), amountPerShare (what its class dividend pays), included, holderCount on the record date and a notDeclared reason when it pays nothing. totalAmount is the poolAmount, and each holder row carries the classToken that pays it, so one holder appears once per class.

GET .../corporate-actions/{corporateActionId}/quote reads a record that exists. An approved record answers its stored plan, with the balance the preview kept for each holder, or null for a plan stored before it did and for a cash dividend or distribution. A drafted or previewed record answers a fresh computation. A cash dividend or distribution can only be quoted this way, once its record date has passed. The terms of a bond coupon, a maturity redemption, a conversion, or a cash dividend or distribution have no quote before the record exists. A quote of them is refused with CORPORATE_ACTION_QUOTE_NOT_APPLICABLE (HTTP 409, DALP-14427). A coordinated distribution is quoted before it is recorded, once its record date has passed. Before that it keeps the preview's refusal, CORPORATE_ACTION_SNAPSHOT_NOT_READY (HTTP 409, DALP-12051), with the recordDate it waits for. Its fingerprint covers the split every class dividend will run and the pool it moves, not the per-holder amounts, which each class dividend recomputes from the record-date book when it is declared.

curl -X POST "https://your-instance.example.com/api/v2/tokens/0x8a791620dd6260079bf849dc5567adc3f2fdc318/corporate-actions/commit" \
  -H "X-Api-Key: $DALP_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "terms": { "type": "bonusIssue", "numerator": 1, "denominator": 10 },
    "quoteFingerprint": "3b8f1d2c4a5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8",
    "acknowledgements": ["excluded-holders"]
  }'

Commit takes terms, the quoteFingerprint from the quote, the acknowledgements, the walletVerification and an Idempotency-Key. It checks the wallet verification once and runs each step as the verified caller. If the plan it computes no longer has the fingerprint you sent, it stops before anything moves on chain and answers CORPORATE_ACTION_QUOTE_STALE (HTTP 409, DALP-14426). The error carries the current quoteFingerprint in data. Read the quote again, review the new plan, and commit with that value.

If the holders move after the commit has saved its record, the platform aborts the record before it answers CORPORATE_ACTION_QUOTE_STALE, so the supply is free again. Send your next attempt with a new Idempotency-Key. The old key finds the aborted record and answers CORPORATE_ACTION_WRONG_STATUS with HTTP 409. A commit of any aborted record answers the same way, including a cash dividend or distribution that an operator cancelled.

What the commit does next depends on the quote's approval:

  • With no approval needed, it confirms. It answers 202 while the record is executing, as a confirm does. Read the record at Location until it settles.
  • With approval needed, it stops at previewed, opens the approval and notifies the checkers. A second operator approves it, as Approve or reject a plan describes. Then POST .../corporate-actions/{corporateActionId}/commit confirms the approved plan without previewing again, after the same fingerprint check. A commit sent again while the record still waits for approval checks the fingerprint too, and answers quote-stale when it differs from the stored plan.
  • A cash dividend or distribution stops after it is recorded and answers drafted with previewAvailableAt, set to its record date. While its dividend declaration is still queued, the answer is 202 and dividendId is null. Read the record until dividendId is set before you quote it. Send no quoteFingerprint on that first commit, because the plan cannot be quoted before the record exists. When the record date has passed, previewAvailableAt is in the past and you can quote and commit the record now. If the snapshot is not final yet, the preview answers snapshot-not-ready and the record stays drafted.

Was this page helpful?