# HTLC settlements
Source: https://docs.settlemint.com/docs/operators/user-guides/system-addons/xvp-settlement/actions/cancel/htlc-settlements
Cancel an HTLC settlement before it is armed, or coordinate the local participants
who must vote when the settlement already has all local approvals.
Cancelling an HTLC settlement stops the exchange and refunds escrowed local
assets to the senders that locked them. Before the settlement is armed, one local
participant can cancel it. After every local sender has approved, each local
participant must cast a cancel vote.
Use this page when you need to stop an HTLC settlement before execution. If the
cutoff date has already passed, use
[Withdraw expired](/docs/operators/user-guides/system-addons/xvp-settlement/actions/withdraw-expired)
instead.
## Before you cancel [#before-you-cancel]
Check the settlement state before you choose what to do:
| Settlement state | What cancel does | What you should do |
| --------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Pending, not all local senders approved | Cancels immediately. | Use **Cancel** from the settlement detail page. |
| Armed, all local senders approved | Records the caller's vote. The settlement cancels only after every local participant has voted. | Use **Propose Cancel** and coordinate the remaining local participants. |
| Secret revealed | Cancellation is blocked. | Continue the execution flow. |
| Executed | Cancellation is blocked. | Treat the settlement as complete. |
| Expired | Cancellation is blocked. | Use [Withdraw expired](/docs/operators/user-guides/system-addons/xvp-settlement/actions/withdraw-expired). |
The contract treats local participants as the unique local sender and recipient
addresses in the settlement flows. A sender who is also a recipient counts once.
Users outside the local flows cannot cancel the settlement or vote to cancel it.
## Cancel before the settlement is armed [#cancel-before-the-settlement-is-armed]
When an HTLC settlement does not yet have every local sender approval, any local
participant can stop it without collecting votes from the other participants.
### Open the settlement [#open-the-settlement]
Navigate to **Settlements** and open the HTLC settlement you want to stop.
### Cancel the settlement [#cancel-the-settlement]
Click **Cancel** on the settlement detail page, review the confirmation, and
submit the wallet verification.
### Verify the refund [#verify-the-refund]
The status changes to **Cancelled**. DALP refunds the escrowed local assets to
the addresses that locked them.
## Propose cancellation after the settlement is armed [#propose-cancellation-after-the-settlement-is-armed]
An armed HTLC settlement has every required local sender approval. At that point,
DALP requires unanimous votes from the local participants before it refunds
escrow. This prevents one participant from cancelling after the other side has
already coordinated external chain commitments.
DALP records one active cancel vote per local participant. The final required vote cancels the settlement and refunds
escrow automatically. Do not treat the first cancel vote as a completed cancellation.
### Open the armed settlement [#open-the-armed-settlement]
Navigate to **Settlements** and open the armed HTLC settlement.
### Propose cancellation [#propose-cancellation]
Click **Propose Cancel** and submit the wallet verification. DALP records your
cancel vote on chain.
### Coordinate the remaining votes [#coordinate-the-remaining-votes]
Use the settlement warning banner or detail view to check the current cancel vote
count. Ask each remaining local participant to propose cancellation from their
wallet.
### Confirm final cancellation [#confirm-final-cancellation]
When the last required participant proposes cancellation, the status changes to
**Cancelled** and DALP refunds the escrowed local assets.
## Withdraw your cancel vote [#withdraw-your-cancel-vote]
A local participant can withdraw their own cancel vote while the armed settlement
is still open and before the final required vote is cast. Use this only when the
settlement should remain armed.
1. Open the armed settlement.
2. Click **Withdraw Cancel Proposal**.
3. Submit the wallet verification.
The vote is removed. The settlement remains armed and cannot cancel until the
participant proposes cancellation again.
You cannot withdraw a cancel vote after the settlement has already cancelled,
executed, expired, or had its HTLC secret revealed.
## What cancellation changes [#what-cancellation-changes]
* DALP clears active cancel votes when the settlement cancels.
* DALP returns escrowed local assets to the sender addresses that locked them.
* DALP marks the settlement as **Cancelled**. The settlement cannot execute after that.
* DALP blocks cancel and withdraw-cancel requests after the HTLC secret is revealed.
## API behavior [#api-behavior]
The public cancel endpoint queues a transaction against the settlement contract:
```http
POST /api/v2/addons/xvp-cancellation-requests
Content-Type: application/json
```
```json
{
"settlementAddress": "0x...",
"walletVerification": {
"secretVerificationCode": "123456",
"verificationType": "PINCODE"
}
}
```
When the platform processes the transaction synchronously, the response wraps the
contract output in the standard blockchain mutation envelope:
```json
{
"data": {
"transactionHash": "0x..."
},
"meta": {
"txHashes": ["0x..."]
},
"links": {
"self": "/v2/addons/xvp-cancellation-requests"
}
}
```
If you send `Prefer: respond-async` and the transaction is accepted for
asynchronous processing, the response gives you a transaction status URL instead:
```json
{
"transactionId": "018f2f6e-7c6a-7c64-9a5a-4f5e6a3c2b10",
"status": "QUEUED",
"statusUrl": "/api/v2/transaction-requests/018f2f6e-7c6a-7c64-9a5a-4f5e6a3c2b10"
}
```
For pending settlements, the contract cancels immediately. For armed HTLC
settlements, the same cancel request records the caller's cancel vote. A second
cancel request from the same participant while that vote is still active is not a
safe retry. Check the settlement state before retrying a submitted request.
Use the withdraw-cancel action only when the participant intentionally wants to
remove an active cancel vote before the final required vote is cast.
## Production checks [#production-checks]
Before cancelling an HTLC settlement, confirm these points:
| Check | Why it matters |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| Settlement is still open | Cancel actions are rejected after execution, cancellation, expiry, or secret reveal |
| Caller is a local participant | Only local participants can cancel, vote, or withdraw a cancel vote |
| Approval state is understood | Pending settlement cancellation is immediate. Armed settlement cancellation is unanimous |
| External-chain teams are coordinated | Armed cancellation can affect counterparties who already acted on the external leg |
| Audit trail is captured | Cancel votes, withdrawn votes, secret reveal, and final cancellation are emitted as settlement events |
## Troubleshooting [#troubleshooting]
| Issue | What to check |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cancel** is not visible | You must be a local participant in the settlement. |
| **Propose Cancel** appears instead of **Cancel** | The HTLC settlement is armed, so local participants must vote. |
| The settlement stays open after your vote | Other local participants still need to vote. Check the vote count on the settlement. |
| You cannot propose cancellation | The secret may have been revealed, the settlement may have executed, or the cutoff may have passed. |
| You need to undo your vote | Use **Withdraw Cancel Proposal** before the final required vote is cast. |
| Your second cancel attempt failed | Your active cancel vote may already be recorded. Check the settlement state before retrying. |
| The settlement has expired | Use [Withdraw expired](/docs/operators/user-guides/system-addons/xvp-settlement/actions/withdraw-expired) instead of retrying cancellation. |
## Next steps [#next-steps]
Follow the full HTLC settlement flow from setup through execution or recovery.
Recover escrowed local assets after the settlement cutoff passes.