# Quote and commit

Source: https://docs.settlemint.com/docs/api-reference/guides/corporate-action-quote
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](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions) covers the create, preview and confirm calls that a commit runs for you.

## Quote, then commit in one call [#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.

```bash
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](https://docs.settlemint.com/docs/api-reference/guides/corporate-action-approval#approve-or-reject-a-partial-redemption) 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`.