XvP settlement
XvP settlement is the Console workspace for a multi-party exchange in which every party's asset moves in one transaction or none move, so no party sends first.
An XvP SettlementXvP Settlement lets two or more parties exchange tokenized assets without either side delivering first: local legs settle atomically, external legs by hashlock.Read the concept exchanges agreed asset amounts between parties. Each local sender approves and locks the amount they owe. Execution transfers the local assets in one transaction: either every local leg succeeds or none does. A cross-chain settlement also describes external flows, which require separate funded contracts on the other chains.
Use a transfer to send tokens without a reciprocal exchange. Use Trading to trade against an order book. A settlement uses amounts agreed before creation; it does not discover a price.
After approval, execution, or withdrawal, check the Settlement VerdictA Settlement Verdict lets you report success only when an operation actually happened, not from acceptance alone, across four recorded end states.Read the concept and the settlement status. Submitting a request starts the operation; confirmation records its outcome.
Senders lock their assets by approving. Execution transfers the local assets; a successful cancellation refunds them. Revoking an approval refunds only that sender and leaves the settlement open. Expiry requires a separate withdrawal, unless a revealed secret keeps the settlement executable.
The Console shows one of seven statuses on every settlement, and each tells you what you can still do. "Pending" means at least one local sender has not approved yet. "Waiting for secret" means every sender has approved, but the settlement includes a cross-chain flow whose secret nobody has revealed. "Ready" means nothing stands between the settlement and execution. "Expired" means the cutoff date passed without execution. "Ready after reveal" marks the one settlement expiry does not stop: its secret was revealed, so it stays executable past its own cutoff date, because revealing the secret is the point where the exchange becomes final. "Executed" and "Cancelled" are the two ways a settlement closes for good.
Approving is per sender, not per settlement. Only the local senders named in the settlement's flows approve at all, and the approvals panel itself reminds you that only local senders approve on this chain. Locking happens the moment you approve, not when the settlement finishes: the assets you are sending move into the settlement contract as soon as your approval clears. They stay there, unavailable to you, until the settlement executes, someone cancels it, or you revoke. Passing the cutoff date does not free them by itself: it only stops the settlement from executing, and someone still has to select "Withdraw assets" afterward to actually return them. Nothing else times a settlement out. Short of its cutoff date, "Pending" or "Waiting for secret" lasts as long as the remaining senders take to act.
Three steps here cannot be taken back, and each says so before you confirm. Executing moves every party's assets to their recipients in one transaction. Revealing a secret is irreversible from the moment you submit it, because the secret becomes readable on-chain and any counterparty holding a matching external contract can use it from that point on, whether or not you execute. Cancelling closes the settlement permanently and refunds every locked asset to the party that sent it; a cancelled settlement can never execute afterward.
Steps
Open the settlements list
In the Console, open "Asset lifecycle" and select "XvP" in the sidebar. If your organization runs more than one XvP settlement addon, each appears under its own name instead. The list shows every settlement the addon has created, across every status, with its type, approval progress, expiry, and creation date. It also carries the "Create XvP settlement" control when your role permits it.
Create a settlement
Select "Create XvP settlement". The wizard has three steps, starting with "Asset flows", which defines who sends what to whom, one flow per transfer.
"Add local flow" describes a transfer that executes on the current chain; "Add external flow" describes one on another chain that this settlement will not execute itself. Each flow sets a from address, a to address, an asset, and an amount, and an external flow also names its chain and the asset's decimals. "Import flows" loads a whole set from a JSON file; a settlement needs at least one local flow and holds at most 100.
"Settlement configuration" names the settlement and sets the "Expiry date" after which it can no longer execute; the wizard proposes a date seven days out. "Auto-execute on final approval" runs the settlement the moment the last approval or reveal lands, instead of waiting for a manual execution. When any flow is external, this step also asks for "Secret management". Choose "Enter hashlock" if you already hold the matching secret outside the Console, or "Enter secret" to type or generate one. The platform then derives the hashlock when it creates the settlement and stores the secret encrypted off-chain; the settlement's secret tile shows the hashlock to share with the counterparty.
If the form shows "Country", it uses that value when registering the settlement contract's identity. "Review settlement" then shows the settlement type the Console derived from the chains involved, every flow, and every setting before you confirm.
Approve, then execute or wait
Open a settlement from the list to reach its detail page, then select "Manage" to see what your account can do next. If you are a local sender named in one of the flows, select "Approve settlement" to lock your asset in the contract; the approvals panel counts how many of the settlement's local senders have approved so far. Once every local sender has approved, a settlement with only local flows becomes ready immediately, while a settlement with a cross-chain flow waits for whoever holds the secret to reveal it. Select "Execute settlement" once the settlement is ready, unless you set auto-execute during creation, in which case the final approval, or on a cross-chain settlement the reveal, runs it for you.
The Platform API reference documents settlement creation, approval, and execution for integrations. The CLI command guide explains how to call those endpoints from the command line.
Managing an existing settlement
Four more steps live under "Manage" on a settlement's detail page, and each one closes the settlement or changes who can act on it, so the Console states the consequence before you confirm.
| Action | What it does | Choose it when | Consequence |
|---|---|---|---|
| "Reveal secret" | Unlocks a cross-chain settlement for execution. | Every external hashed timelock contract the settlement depends on already holds funds. | Cannot be undone. A counterparty can use the secret from the moment it lands on-chain, and "Cancel settlement" disappears once revealed. |
| "Revoke approval" | Unlocks your own asset and returns it to your wallet immediately. | You want out before the settlement executes, expires, or cancels. | Stays available on a local-only settlement even after everyone has approved. On a cross-chain settlement it disappears once every sender has approved. |
| "Cancel settlement" | Closes the settlement for every party and refunds every locked asset. | Before every sender approves, or on any settlement with only local flows. | Once a cross-chain settlement reaches full approval, this becomes "Propose cancel", a vote every local sender and recipient must join. |
| "Withdraw assets" | Returns every local participant's locked asset in one transaction. | The settlement expired without executing. | Any one of the settlement's own senders can trigger it, and it runs once for the whole settlement. |
Revealing the secret unlocks a cross-chain settlement for execution, and it cannot be undone. Select "Reveal secret" only once every external hashed timelock contract the settlement depends on actually holds funds. The Console warns that counterparties can use the secret the moment it lands on-chain, whether or not you execute. Reveal too early, before an external leg holds funds, and a counterparty can take the secret without delivering their side.
Reveal too late, though, and the settlement locks up instead. "Reveal secret" stops appearing under "Manage" once the settlement passes its cutoff date, so a secret you never reveal in time can never unlock the settlement, and every local sender's asset is left waiting on a withdrawal rather than an execution. The reveal also commits the settlement the moment it succeeds, since "Cancel settlement" disappears, withdrawal after expiry is off the table, and completing the exchange becomes the only path left.
Revoking approval undoes your own lock and stops the settlement from proceeding without you. Select "Revoke approval" to unlock the asset you already approved and return it to your wallet immediately, without waiting on any other sender. On a settlement with only local flows, revoking stays available until the settlement executes, expires, or cancels, even after every sender has approved. You can approve again whenever you are ready. On a cross-chain settlement, revoking is available only before every local sender has approved. Once that settlement reaches full approval, "Revoke approval" no longer appears, and cancelling or letting the settlement expire are the only ways left to back out.
Cancelling closes the settlement for every party, but the Console asks for it differently depending on how far the settlement has gone. Before every sender has approved, or on a settlement with only local flows, "Cancel settlement" closes it directly and refunds every locked asset. Once a cross-chain settlement reaches full approval, cancelling becomes a vote instead: "Propose cancel" records your consent and the Console names how many more votes are needed. Every local sender and recipient in the settlement's flows gets a vote, not only its senders. When yours is the last vote needed, the Console asks as a direct cancellation again. If a needed participant never votes, waiting for the cutoff date and withdrawing afterward is the only other way out.
Withdrawing returns assets once a settlement expires without executing. Select "Withdraw assets" on an expired settlement, and that single transaction returns every local participant's locked asset to their own wallet at once, not only yours. Any one of the settlement's own senders can trigger it, and it runs only once for the whole settlement.
Troubleshooting
Approve settlement shows an insufficient balance
The approval sheet names the assets and the amount still needed before it lets you approve. Add funds to the sending wallet and try again; approval locks the exact amount the flow specifies, and it cannot partially lock a smaller balance even when your wallet holds most of what the flow needs. Check the sending wallet against the flow's asset and chain as well as its amount, since a shortfall on the wrong asset produces the same message as a shortfall on the right one.
The configuration step will not accept a cross-chain settlement
Any external flow makes a hashlock or a secret mandatory, because a cross-chain settlement cannot execute atomically without one. The "Settlement configuration" step blocks with "External flows require a valid hashlock or secret. Enter an existing hashlock, or enter or generate a secret before continuing." Pick "Enter hashlock" if you hold the matching secret outside the Console, or "Enter secret" and let the platform derive the hashlock when it creates the settlement.
Creation fails on a flow that pays its own sender
The settlement contract refuses a flow whose sending and receiving address are the same, since such a flow never moves anything from one party to another, so creating the settlement fails. It does allow the same address to appear across different flows of one settlement; this supports circular obligations between counterparties. Review each flow's own sender and recipient before you create.
A settlement shows a cross-chain warning after creation
A settlement with an external flow warns that the platform cannot verify an external contract or a counterparty's behavior on another chain. You must confirm outside the Console, on your own, that an external hashed timelock contract holds funds and matches the flow before revealing the settlement's secret. Revealing without that confirmation lets a counterparty take the secret without delivering their side of the exchange, because the platform has no way to check an external chain on your behalf.
A fully approved settlement is still waiting
A settlement with a cross-chain flow does not become ready when every local sender approves; it waits until whoever holds the secret reveals it. After twelve hours in that state the Console adds its own reminder: "All approvals in, still waiting for secret reveal." The wait is normal, but it is not open-ended. "Reveal secret" stops working after the cutoff date. An unrevealed settlement that reaches that date cannot execute. Each locked leg needs a separate withdrawal. If you did not expect the wait, confirm with whoever created the settlement whether anyone can still reveal the secret before the cutoff.
Execute settlement fails or the status does not change
"Execute settlement" is one transaction: every local leg pays out, or none does. When it fails, the Console shows an error naming why, and the settlement's status stays exactly where it was, so no leg is left half paid and no retry can find it partway done. Correct whatever the error names and select "Execute settlement" again.
Cancel shows a vote count instead of closing the settlement
Once a cross-chain settlement reaches full approval, cancelling needs the consent of every local participant, recipients included, so no single party can unwind a shared exchange alone once everyone has locked value into it. "Cancel settlement" becomes "Propose cancel", and the Console shows how many votes remain. If a needed participant will not vote, cancelling stalls for good. Wait for the cutoff date, then have an already-approved sender select "Withdraw assets", the expiry fallback.
A settlement's expiry is approaching
The Console flags any settlement inside twenty-four hours of its cutoff with "Settlement expires soon", to help you track the deadline. Execute it before the cutoff if it is ready. If it is not ready in time, expect it to expire, and expect any one of the settlement's own senders to select "Withdraw assets" afterward, to return the locked assets.
Create XvP settlement is not visible
The control does not appear unless your account holds the admin or owner role, or an administrator has granted it the settlement-creation permission specifically. Ask an organization administrator for one of these before trying again.
Frequently asked questions
How large can one settlement be?
A settlement holds up to 100 flows, and each flow moves one asset from one sender to one recipient, so the number of parties is limited only by how many distinct addresses those flows name. When one address appears in several flows, the contract settles its net position per asset rather than paying each flow separately, so a party that both sends and receives the same asset only moves the difference.
Can I change a settlement after creating it?
No. The flows, amounts, expiry date, and auto-execute setting are fixed the moment the settlement is created, and nothing under "Manage" edits them. To correct a mistake, back out of the existing settlement, by revoking, cancelling, or letting it expire, and create a new one with the right values. Counterparties re-approve the new settlement from scratch.
What do "Local" and "HTLC" mean in the list's type column?
"Local" means every flow executes on the current chain, so full approval alone makes the settlement ready. "HTLC" means at least one flow describes a transfer on another chain, so the settlement is protected by a hashed timelock: it needs a hashlock at creation and a revealed secret before it can execute. The Console derives the type from the flows; you never choose it directly.
What if a sender falls out of compliance after approving?
Execution re-checks every funded local flow against the asset's compliance rules at the moment it pays out, so a party whose status changed between approval and execution blocks the whole settlement, and the error names the failing leg. The one exception is a cross-chain settlement whose secret is already revealed: it is committed, so the re-check is skipped and the exchange completes rather than stranding the escrow.
Related concepts
Read XvP Settlement for the atomicity and net-position model behind every step on this page, and Settlement Verdict for how the Console determines and reports a submitted request's actual outcome.
Venue operations
Operate the trading venue from the Console: list and halt markets, delist them, tune fees and bands, grant desk limits, and undo pending deliveries.
Governance votes
Governance votes are the Console workflow for creating an on-chain vote, casting ballots on it, and carrying out whatever a token's holders approved.