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/ 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,remainderanddenominationShortfall.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 thecurrencyand the pricebeforeandafterthe 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 withprice-unadjustable(HTTP 409,CORPORATE_, DALP-184653). Confirm needs the tokenACTION_ PRICE_ UNADJUSTABLE adminrole on top of the supply role, refuses withpreview-mismatchwhen 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'ssnapshot.priceStepcarriesstate(pending,submitted,settledorfailed),attempt,transactionRequestIdand, when the step failed, afailurethat names why and afailureCode(drifted,refused,queue-failedorstored-unreadable). The action staysexecutinguntil the price settles. Confirming afailedstep sends the price again once the share's price is back at the approvedbefore, or already at the approvedafter. While the price is anywhere else, confirm refuses withprice-drifted(HTTP 409,CORPORATE_, DALP-184654), and the message names the price to set. Once every chunk of holder units has landed, abort refuses withACTION_ PRICE_ DRIFTED run-completed, because only the price update remains. If an abort raced the last chunk and that chunk landed anyway, the action staysabortedwhile the price update is sent, and afailedstep on it is confirmed again the same way: the step moves on and the status staysaborted. On anabortedaction, confirm does nothing but that retry: unless the step isfailedand every holder update landed, it answers with the record unchanged. A split whose ratio leaves the price unchanged at 8 fraction digits is refused withprice-unadjustable. The price history stays as it is. The venue keeps its own price-band anchors.data, a page of holder rows withholder,balance,amountandstate. Page it withpage[offset]andpage[limit], up to 200.acknowledgements, the consequences the commit has to acknowledge.approval, withrequirementset torequired,not-neededorwaived.waivedcomes with the reason.quoteFingerprint, which equals theplanDigestthe stored preview of the same plan gets.coordinated, only for a coordinated distribution: every class dividend the commit will declare. It names thewaterfallFeature, thedenominationAssetof the pool, theappliedDeterminationKind(null for the ordinary split), thepoolAmountit moves, and one entry per class withclassToken,role,rank,allocation(the slice the waterfall split gives it),amountPerShare(what its class dividend pays),included,holderCounton the record date and anotDeclaredreason when it pays nothing.totalAmountis thepoolAmount, and each holder row carries theclassTokenthat pays it, so one holder appears once per class.
GET .../ 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_ (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_ (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_ (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_, 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_ 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
202while the record isexecuting, as a confirm does. Read the record atLocationuntil 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. ThenPOST .../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 answerscorporate- actions/ {corporate Action Id}/ commit quote-stalewhen it differs from the stored plan. - A cash dividend or distribution stops after it is recorded and answers
draftedwithpreviewAvailableAt, set to its record date. While its dividend declaration is still queued, the answer is202anddividendIdisnull. Read the record untildividendIdis set before you quote it. Send noquoteFingerprinton that first commit, because the plan cannot be quoted before the record exists. When the record date has passed,previewAvailableAtis in the past and you can quote and commit the record now. If the snapshot is not final yet, the preview answerssnapshot-not-readyand the record staysdrafted.