An XvP Settlement exchanges asset amounts the parties agreed beforehand. A local flow is a transfer on this chain, and an external flow is one on another chain. Each sender of a local flow approves the settlement, which locks the amount it owes. Before a secret is revealed, execution moves every local leg in one transaction, or none moves. After a reveal commits a cross-chain settlement, a delivery the token refuses is parked for its recipient and the other deliveries complete. An external flow needs its own funded contract on the other chain. XvP Settlement explains the atomicity and net-position model behind every step on this page.
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.
The “Settlements” list with a “Create XvP settlement” button and one row per settlement.
Each row shows the settlement's name and type, “Status”, “Approvals”, “Expiry” and a row menu under “Actions”.
Steps
Open the settlements list
In the Console, select Settlements under “Wealth” in the sidebar. The entry appears once your organisation has the XvP settlement add-on. With the “Permission manager” or “Asset manager” system role, the list shows every settlement the add-on has created. Without either role, it shows only the settlements where one of your wallets is the creator, a sender or recipient of a flow, or an approver.
The list includes settlements in every status, and each row shows the settlement's name, type, status, approval progress and expiry. The creation date is one of the columns you can switch on in the table's view options. A settlement that waits for your approval reads “Needs your approval” and has an “Approve” button on its row. A local participant can also use the row's “Cancel settlement” shortcut to open the cancel dialog.
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.
The first step, “Asset flows”, opens with one local flow, “Flow 1”, and its “From address”, “To address”, “Asset” and “Amount” fields.
Add local flow describes a transfer that executes on the current chain. “Add external flow” describes one on another chain that this settlement does 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. A field left empty, the amount included, reads “This field is required” under it. A from or to address whose capitalisation does not match its checksum is refused on the field rather than rewritten, so a mistyped paste is caught before the settlement is created. “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. Only the creator of a cross-chain settlement handles the secret. A counterparty only approves.
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. If you are a local sender named in one of the flows, select “Approve” on its list row, or Approve settlement in the page header, to lock your asset in the contract. If another wallet of yours is the sender, the button is disabled and tells you to switch to the wallet that sends a flow in this settlement. If your custody account signs in your own wallet, the sheet asks that wallet to confirm the approval, together with any spending allowance the lock needs, and records the approval once the wallet signs.
“Actions” lists the other steps your account can take. 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. When the settlement is ready, select “Execute settlement”. Executing cannot be undone. With “Auto-execute on final approval” on, the final approval runs it, or on a cross-chain settlement the reveal does.
Manage an existing settlement
Actions on a settlement's detail page holds five more steps, and the Console states each one's consequence before you confirm.
Revealing the secret cannot be undone. Select Reveal secret only once every external hashed timelock contract the settlement depends on holds funds. The Console warns that counterparties can use the secret the moment it lands on-chain, whether or not you execute. A reveal before an external leg holds funds lets a counterparty take the secret without delivering their side.
After the cutoff date, Reveal secret no longer appears, so an unrevealed cross-chain settlement can only be withdrawn. The reveal also commits the settlement: “Cancel settlement” disappears, withdrawal after expiry no longer applies, and the settlement can only execute.
After you revoke, you can approve again whenever you are ready. On a cross-chain settlement that reached full approval, 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 shows a direct cancellation instead. If a needed participant never votes, the only other way out is to wait for the cutoff date and withdraw.
A refund that a token refuses stays parked in the settlement. On a cross-chain settlement whose secret is revealed, a delivery the token refuses at execution is parked too. On any other settlement, that refusal makes the execution fail and nothing moves. The settlements list marks such a settlement with “Parked amount to claim” for the wallet it is parked for.
Select Claim parked amount under “Actions”. Under “Send to”, choose “My wallet” or “Another address”. Before you confirm, the Console checks that each listed asset accepts that address. The address must accept every listed asset: if one refuses, nothing moves, and you can claim again to another address. Once the settlement's secret is revealed, a parked refund cannot be claimed: the settlement can only execute. The Console hides “Claim parked amount” until it has executed.
The Escrow tile on a settlement's detail page lists, for each participant and asset, the amount “Locked” into the settlement, the amount “Parked” for them, and the amount “Refunded”. It appears once anyone has locked an asset or has an amount parked. Before execution, the locked amount minus the refunded amount is still in the settlement. Execution delivers the locked amounts and leaves the tile's totals as they were.
To find the settlements whose contract still holds money, add the Escrow filter in the settlements list and choose “Holds escrow”. The filter keeps a settlement that holds a parked amount, and one that was cancelled, or passed its cutoff date without a revealed secret, while a participant has locked more than the settlement refunded. “Withdraw assets” or “Claim parked amount” returns that money.
What approving locks
Only the local senders named in the flows approve, and each approval locks that sender's assets in the settlement contract as soon as it clears. The contract pulls them through an ERC-20 allowance, so the approval sheet shows your current allowance for each asset and says whether approving sets it to the amount the settlement locks. 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 afterwards to return them. Short of its cutoff date, nothing in the settlement times it out, and “Pending” or “Waiting for secret” lasts as long as the remaining senders take to act.
The settlement contract sits on the compliance bypass list, so your deposit into escrow skips the recipient-side checks, and execution applies them. A holder of a token's “Custodian” role can still freeze or move an escrowed amount of that token. What if a sender falls out of compliance after approving? covers the compliance check at execution.
Settlement statuses
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 means the secret is revealed, so the settlement stays executable past its cutoff date.
- Executed means the settlement ran and is closed for good.
- Cancelled means the settlement was cancelled and is closed for good. A cancelled settlement can never execute.
Executing, revealing a secret and cancelling cannot be undone, and each says so before you confirm.
Approving locks a sender's assets, execution transfers them, cancellation refunds them, a revoked approval refunds only that sender, and expiry needs a separate withdrawal, unless a revealed secret keeps the settlement executable.
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, for each asset, the net amount the sender owes across all its flows in the settlement, and it cannot partially lock a smaller balance even when your wallet holds most of what is needed. 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 does 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 behaviour on another chain. Before you reveal the secret, confirm outside the Console that the external hashed timelock contract holds funds and matches the flow. A reveal without that check lets a counterparty take the secret without delivering.
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.” Reveal secret no longer appears after the cutoff date. An unrevealed settlement that reaches that date cannot execute. Its locked assets then wait for one “Withdraw assets”, which any party can select after the cutoff. 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: on a settlement whose secret is not revealed, every local leg pays out, or none does. On a cross-chain settlement whose secret is revealed, a leg the token refuses is parked instead of failing the execution. When it fails, the Console shows an error naming why, and the settlement's status does not change and no leg has paid out. 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 does not vote, the settlement cannot be cancelled. After the cutoff date, any party can select “Withdraw assets”.
A settlement's expiry is approaching
The Console flags any settlement inside 24 hours of its cutoff with “Settlement expires soon”. Execute it before the cutoff if it is ready. If it is not ready in time, it expires, and any party to the settlement can then select Withdraw assets to return the locked assets.
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 Actions 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 settlement executes. On that revealed settlement, a delivery the token refuses is parked for its recipient to claim with Claim parked amount.
API routes
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.