Create
Learn how to create an XvP settlement from the XvP add-on page. Configure asset flows, settlement options, external-flow hashlocks, and review the summary before submission.
The XvP settlement wizard creates a settlement from a specific XvP add-on factory. Start from the add-on page, add the flows that define the exchange, configure settlement-level options, then review the summary before you submit.
The wizard has three steps: Asset Flows, Configuration, and Summary. You can move between the steps while the draft is valid. If you leave the wizard before creating the settlement, the platform asks you to confirm because unsaved draft values are not submitted.
Prerequisites
- Access to the XvP Settlement add-on in the platform
- Permission to create settlements for the selected XvP add-on factory
- Wallet addresses for the parties sending and receiving assets
- Token contract addresses for the assets being exchanged
- For external flows: the external chain ID, token decimals, and either a precomputed hashlock or the raw secret used to derive one
- For V3 XvP factories: the ISO 3166-1 numeric country code for the settlement
Create access is permission-gated
If the Create Settlement action is unavailable, check that your platform role and the selected add-on factory allow you to manage XvP settlements.
Create a settlement
Open the XvP add-on page
In the sidebar, open the XvP add-on factory you want to use, then click Create Settlement.
The settlement is created against that factory. If you operate more than one XvP add-on factory, confirm that you are on the correct add-on page before opening the wizard.
Add asset flows
On Asset Flows, add the transfers that make up the settlement. Each flow defines the asset, sender, recipient, and amount.
Use Add Local Flow for transfers that execute on the current chain. Use Add External Flow for a matching transfer that executes on another chain. Every settlement must include at least one local flow.
| Flow type | Use it for | Required fields |
|---|---|---|
| Local flow | A transfer executed by this XvP settlement | Token address, sender wallet, recipient wallet, amount |
| External flow | A matching transfer coordinated on another chain | Token address, sender wallet, recipient wallet, amount, chain ID, token decimals |
Local vs external flows
Local flows execute on the current chain. External flows record the matching transfer on another chain, including its chain ID and token decimals, but do not execute locally.
For larger exchanges, use Import Flows to upload one or more JSON files. Imported flows are appended to the wizard instead of replacing existing rows.
Configure settlement options
On Configuration, enter the settlement-level details.
| Option | Description |
|---|---|
| Name | A clear settlement name, such as BOND-for-USDC Trade |
| Cutoff date | The deadline after which the settlement can no longer proceed |
| Auto-execute | When enabled, the settlement executes automatically after the required approvals are complete |
| Country | Required only for V3 XvP factories. Use the ISO 3166-1 numeric country code for the settlement. |
For V3 factories, confirm the country code on this step before continuing to the summary.
If the settlement contains any external flow, choose one HTLC mode:
- Enter hashlock when a counterparty has already shared the 32-byte hashlock for the external leg.
- Enter secret when you want the platform to derive the hashlock from a raw secret. You can generate a secret in the wizard or paste your own.
Keep the secret available
If you use a raw secret, store it securely before submitting. The secret is needed to coordinate execution on chains that use the same hashlock.
Review and create
On Summary, review the settlement before submission:
- Check each asset address, sender, recipient, amount, and external chain value.
- Confirm the cutoff date gives every sender enough time to approve.
- For external flows, confirm the hashlock matches the value expected by the counterparties.
Click Create and authenticate with your PIN or OTP to submit the transaction.
After creation
After the transaction is submitted:
- The settlement appears in the XvP add-on settlement list.
- The settlement detail page shows the settlement ID, status, flows, and required actions.
- Senders for local flows can approve and lock their assets into the settlement.
- For external-flow settlements, coordinate the shared hashlock and secret handling with the counterparties responsible for the other chain.
Import flows from JSON
For complex settlements with many flows, you can import flow rows from JSON files.
- On Asset Flows, click Import Flows.
- Upload up to five
.jsonfiles. - Review the parsed flows in the import dialog.
- Click Import Flows to append them to the wizard.
Each file must contain a JSON array of flow objects:
[
{
"type": "local",
"assetId": "0x1234567890abcdef1234567890abcdef12345678",
"assetSymbol": "USDC",
"assetDecimals": 6,
"from": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"to": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"amount": "1000000"
},
{
"type": "external",
"assetId": "0x567890abcdef1234567890abcdef1234567890ab",
"from": "0xcccccccccccccccccccccccccccccccccccccccc",
"to": "0xdddddddddddddddddddddddddddddddddddddddd",
"amount": "500000000000000000",
"externalChainId": 1,
"externalAssetDecimals": 18
}
]Field reference:
| Field | Required for local | Required for external | Description |
|---|---|---|---|
type | Yes | Yes | "local" or "external" |
assetId | Yes | Yes | Token contract address |
from | Yes | Yes | Sender wallet address |
to | Yes | Yes | Recipient wallet address |
amount | Yes | Yes | Amount as string, in the token's smallest unit |
assetSymbol | Yes | No | Token symbol for local imported flows |
assetDecimals | Yes | No | Decimals for local imported flows |
externalChainId | No | Yes | Chain ID for external flows |
externalAssetDecimals | No | Yes | Decimals for external flows |
Imported files must be valid JSON arrays. If a file is empty, malformed, not an array, or missing required fields, the wizard shows the validation error before import.
Next steps
Approve flows
How senders lock their assets into the settlement.
Local walkthrough
See a complete local settlement example.