# Cancel

Source: https://docs.settlemint.com/docs/user-guides/system-addons/xvp-settlement/actions/cancel
Stop an open XvP settlement and return locked assets to their original senders.
Learn when cancellation is unilateral, when unanimous cancel votes are required,
and when to use expired-withdrawal instead.




Cancelling a settlement stops an open exchange and returns locked assets to the
original senders. Use cancellation before execution or expiry when the exchange
should no longer proceed. The contract either cancels immediately or records a
cancel vote, depending on whether the settlement is armed for external flows.

## What cancellation does [#what-cancellation-does]

Cancellation is final. Once a settlement is cancelled, it cannot execute and the
locked assets are refunded from escrow to the senders that provided them.

The cancellation rule depends on settlement state:

| Settlement state         | Cancellation behavior                                                                                                  | What you should do                                                                                                        |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Pending local settlement | A local participant can cancel unilaterally.                                                                           | Call the cancel endpoint.                                                                                                 |
| Pending HTLC settlement  | A local participant can cancel unilaterally before every local sender has approved.                                    | Call the cancel endpoint.                                                                                                 |
| Armed HTLC settlement    | Each local participant must cast a cancel vote. The settlement cancels only after all local cancel votes are recorded. | Call the cancel endpoint from each required participant.                                                                  |
| Secret revealed          | Cancellation is no longer allowed.                                                                                     | Continue the execution flow.                                                                                              |
| Executed                 | Cancellation is no longer allowed.                                                                                     | Treat the settlement as complete.                                                                                         |
| Expired                  | Cancellation is no longer allowed.                                                                                     | Use [Withdraw expired](/docs/user-guides/system-addons/xvp-settlement/actions/withdraw-expired) to release locked assets. |

## Where to go next [#where-to-go-next]

Different readers need different next steps from the cancellation model:

| Reader                 | Use this page to decide                                        | Next step                                                                                                                                       |
| ---------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Buyer or business user | Whether the exchange can still be stopped and assets returned. | Read [Cancel a local settlement](/docs/user-guides/system-addons/xvp-settlement/actions/cancel/local-settlements) for same-chain exchanges.     |
| Operator               | Which participant action is available for the current state.   | Read [Cancel an HTLC settlement](/docs/user-guides/system-addons/xvp-settlement/actions/cancel/htlc-settlements) before coordinating proposals. |
| Security reviewer      | When cancellation is blocked by execution or secret reveal.    | Read [HTLC explained](/docs/user-guides/system-addons/xvp-settlement/htlc/htlc-explained) for the hashlock and timelock model.                  |

## How to cancel [#how-to-cancel]

Call the cancel endpoint with the settlement contract address. The API queues a
transaction that calls the settlement contract's `proposeCancel` function.

```http
PUT /xvp/cancel
Content-Type: application/json

{
  "settlementAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
  "walletVerification": {
    "secretVerificationCode": "YOUR_PINCODE"
  }
}
```

For local settlements and HTLC settlements that are not fully approved, the call
cancels the settlement immediately. No other participant approval is required.

For armed HTLC settlements, the same endpoint records the caller's cancel vote.
The settlement remains open until every local participant has voted to cancel.
The final required vote cancels the settlement and refunds the locked assets.

## Production checks [#production-checks]

Before you cancel, check the settlement state and choose the correct action:

* If the settlement has not executed, has not expired, and has no revealed secret, use cancellation.
* If the settlement has external flows and every local sender has approved, treat
  cancellation as a unanimous vote.
* If the settlement has expired, do not retry cancellation. The contract rejects
  cancel attempts after the cutoff with `XvPSettlementExpired`; use
  [Withdraw expired](/docs/user-guides/system-addons/xvp-settlement/actions/withdraw-expired)
  instead.
* If a participant has voted to cancel an armed HTLC settlement and the secret has
  not been revealed, they can retract their vote with the withdraw-cancel
  endpoint.
* If the secret has been revealed, cancellation and cancel-vote withdrawal are no
  longer available.

For step-by-step procedures, use the settlement-specific guides:

<Card title="Cancel a local settlement" href="/docs/user-guides/system-addons/xvp-settlement/actions/cancel/local-settlements">
  Cancel a non-HTLC settlement before execution and refund locked assets.
</Card>

<Card title="Cancel an HTLC settlement" href="/docs/user-guides/system-addons/xvp-settlement/actions/cancel/htlc-settlements">
  Cancel before the HTLC is armed, or coordinate unanimous cancel votes after it is armed.
</Card>

## Audit notes [#audit-notes]

Cancellation is constrained on-chain:

* The caller must be a local participant.
* The settlement must be open: not executed, not cancelled, and before the cutoff.
* The contract rejects cancellation after the HTLC secret is revealed.
* Armed HTLC cancellation votes are tracked on-chain with cancel-vote cast and
  withdrawal events.
* A cancel vote can be withdrawn only for an armed external-flow settlement that
  is fully approved, still open, and has no revealed secret.