# HTLC settlements
Source: https://docs.settlemint.com/docs/operators/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. While the settlement is pending, one local
participant can cancel it. Once every local sender approves, 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/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 | The contract rejects cancel. | Continue the execution flow. |
| Executed | The contract rejects cancel. | Treat the settlement as complete. |
| Expired | The contract rejects cancel. | Use [Withdraw expired](/docs/operators/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 has all approvals [#cancel-before-the-settlement-has-all-approvals]
When an HTLC settlement does not yet have every local sender approval, any local
participant can stop it without collecting votes from the others.
### Open the settlement [#open-the-settlement]
Go to Settlements and open the HTLC settlement you want to stop. Confirm the status shows Pending and that not all local senders have approved.
### Cancel the settlement [#cancel-the-settlement]
Click **Cancel** on the settlement detail page, review the confirmation, and submit the wallet verification. The platform submits a cancel transaction immediately.
### Verify the refund [#verify-the-refund]
The status changes to Cancelled. DALP refunds the escrowed local assets to the addresses that locked them. The settlement is now closed.
## Propose cancellation on an armed settlement [#propose-cancellation-on-an-armed-settlement]
An armed HTLC settlement has every required local sender approval. At that point,
DALP requires unanimous votes from the local participants before refunding
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]
Go to Settlements and open the armed HTLC settlement. Verify the status shows Armed before you proceed.
### Propose cancellation [#propose-cancellation]
Click **Propose Cancel** and submit the wallet verification. DALP records your cancel vote on chain. The settlement stays open until all required participants vote.
### 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 the final required vote has not been 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.
DALP removes the vote. The settlement remains armed and cannot cancel until the
participant proposes cancellation again.
You cannot withdraw a cancel vote after the settlement has cancelled,
executed, expired, or after the HTLC secret is published.
## 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 once the HTLC secret is published.
## API behavior [#api-behavior]
The public cancel endpoint queues a transaction against the settlement contract. The endpoint accepts the settlement address and wallet verification, then returns the result. Request and response shapes are below.
```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 request synchronously, it returns 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`, the platform accepts the request for
asynchronous processing and 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. Verify the settlement state before retrying a submitted request.
Use withdraw-cancel 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 the following points.
| Check | Why it matters |
| --------------------------------- | --------------------------------------------------------------------------------------- |
| Settlement is still open | The contract rejects cancel after execution, expiry, or secret reveal. |
| Caller is a local participant | Only local participants can cancel or vote. |
| Approval state is understood | Pending settlements cancel immediately. Armed settlements require unanimous votes. |
| External-chain teams are notified | Armed cancellation can affect counterparties who already acted on the external leg. |
| Audit trail is complete | The settlement contract emits events for votes, withdrawals, secret reveal, and cancel. |
## 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 all local participants must vote. |
| The settlement stays open after your vote | Other local participants still need to vote. Verify the vote count on the settlement. |
| You cannot propose cancellation | The contract may have received the secret, 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 | DALP may already hold your active cancel vote. Verify the settlement state before retrying. |
| The settlement has expired | Use [Withdraw expired](/docs/operators/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. Use this when you want to understand every state the settlement passes through before reaching a terminal state.
Recover escrowed local assets after the settlement cutoff passes. Use this path when the cutoff has already passed and cancel is no longer available.