# Settlements Source: https://docs.settlemint.com/docs/console/my-assets/settlements Create a multi-party exchange, approve and lock your leg, then execute, cancel or withdraw after expiry. Every local leg moves in one transaction or none does. 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](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement) explains the atomicity and net-position model behind every step on this page. Use a [transfer](https://docs.settlemint.com/docs/console/asset-management/manage/transfers) to send tokens without a reciprocal exchange. Use [Trading](https://docs.settlemint.com/docs/console/my-assets/trading) to trade against an order book. A settlement uses amounts agreed before creation. It does not discover a price. ![Settlements list with the Create XvP settlement action](https://docs.settlemint.com/docs/screenshots/console-settlements-list.light.en.webp) [Screenshot] 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". ## Before you start [#before-you-start] - **Approving.** Your wallet must be the sender of a local flow and hold the amount it owes. Any signed-in account can create a settlement, but nothing moves from a sender's wallet until that sender approves its own leg, and the contract checks the sender itself. - **Approve and Revoke approval.** Only the settlement's local senders can run them. - **Execute settlement and Reveal secret.** Any account can run them, once the status allows it. - **Withdraw assets.** Any party to the settlement can run it: its creator, a sender or recipient of a flow, or an approver. - **Cancel settlement.** Only an account that sends or receives a flow on this chain can run it. - **What the Console shows.** The Console shows only the steps your account and the settlement's status both permit. The contract accepts execute, reveal and withdraw calls from any account, whatever the Console shows. ## Steps [#steps] ### Open the settlements list [#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 [#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. ![Create XvP settlement wizard at the Asset flows step](https://docs.settlemint.com/docs/screenshots/console-settlements-create-flows.light.en.webp) [Screenshot] 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 [#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 [#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. | 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, unless the token refuses the delivery, in which case the settlement holds it for **Claim parked amount**. | 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, except a refund the token refuses, which stays parked for its sender to claim. | The settlement expired without executing. | Any party to the settlement can trigger it, and it runs once for the whole settlement. | | **Claim parked amount** | Sends a refund, or on a revealed cross-chain settlement a settled delivery, that a token refused and the settlement holds for you, to an address you choose. | The settlements list marks the settlement with **Parked amount to claim**. | If the chosen address does not accept every listed asset, nothing moves and you can claim again to another address. | 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 [#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?](#what-if-a-sender-falls-out-of-compliance-after-approving) covers the compliance check at execution. ## Settlement statuses [#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. [Figure] Approval, execution, and cancellation of a settlement. A settlement starts awaiting approval and moves to fully approved once every local sender approves. From there, executing pays every leg in one transaction and cannot be undone. A successful cancellation refunds every locked asset. Revoking an approval refunds that sender without closing the settlement. Expiry requires a separate withdrawal to refund locked assets. Labels: Awaiting approval; senders still to approve; Fully approved; ready, or waiting on a secret; every sender approves; Executed; value moved, cannot be undone; Cancelled; every locked asset refunded; execute; cancel; cancel. 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. ## You should see [#you-should-see] - After approval, execution, or withdrawal, check the Settlement Verdict and the settlement status. An operation is done when its transaction confirms, and the status then changes. - Return to the settlements list and confirm it shows the expected status. Approved senders move it towards "Ready" or "Waiting for secret", execution moves it to "Executed", and a cancellation or a passed cutoff moves it to "Cancelled" or "Expired". - Open the settlement's detail page and confirm the approvals panel, the flows table, and, once revealed, the secret panel show your action. The approvals panel names the sender and timestamp behind every approval, and the secret panel names who revealed the secret and when. The full event history is on chain, as [XvP Settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement) describes. - Once a settlement reaches "Executed", "Cancelled", or "Expired", its status no longer changes. A parked amount on it stays marked "Parked amount to claim" until its owner claims it. ## Troubleshooting [#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 [#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 [#api-routes] The [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) documents settlement creation, approval, and execution for integrations. The [CLI command guide](https://docs.settlemint.com/docs/api-reference/cli/commands) explains how to call those endpoints from the command line.