# XvP settlement flows Source: https://docs.settlemint.com/docs/developer-guides/api-integration/xvp-settlement-flows Create, approve, execute, and monitor XvP settlement flows through DALP APIs, SDKs, and CLI commands. # XvP settlement flows [#xvp-settlement-flows] XvP settlements coordinate value-transfer legs between participants. Use this flow to create a settlement, collect approvals, execute the settlement, or recover funds. DALP exposes XvP through the API, SDK, and CLI. The public API and SDK share the same settlement model. Integrations can create settlements programmatically and reconcile them through the platform UI or CLI. ## When to use this flow [#when-to-use-this-flow] Use an XvP settlement when: * a system has the XvP settlement add-on factory available, * at least one transfer leg is a local on-chain flow managed by the active DALP system, * participants need to approve the settlement before execution, * your integration needs to track approval, cancellation, execution, withdrawal, or secret-reveal state. Do not use XvP documentation as a substitute for the API Reference. Use the [API Reference](/docs/developer-guides/api-integration/api-reference) for exact request and response fields, and the [CLI Command Reference](/docs/developer-guides/cli/command-reference) for command syntax. ## Create a settlement [#create-a-settlement] Create a settlement with the XvP add-on factory address, a name, a future cutoff date, and an array of flows. Each flow includes an asset address, sender, recipient, and amount. DALP supports two flow types: | Flow type | What it represents | Extra fields | | ---------- | --------------------------------------------------------------------------------- | ------------------------------------------------- | | `local` | A transfer leg on the active DALP-managed chain. | None beyond asset, sender, recipient, and amount. | | `external` | A transfer leg that references an external chain asset as part of the settlement. | External chain ID and external asset decimals. | Every settlement must include at least one `local` flow. The factory address must belong to an XvP settlement add-on registered for the active system. If any flow is `external`, provide either a raw secret or a precomputed hashlock. Local-only settlements do not require a secret or hashlock. For systems using the current XvP settlement factory identity model, include the ISO 3166-1 numeric country code required by the factory. ```ts const created = await client.addons.xvp.create({ body: { factoryAddress: "0xFACTORY", name: "Primary sale settlement", autoExecute: false, cutoffDate: new Date("2026-06-30T17:00:00Z"), country: 756, flows: [ { type: "local", assetId: "0xASSET", from: "0xSENDER", to: "0xRECIPIENT", amount: "1000000", }, ], walletVerification, }, }); const settlementAddress = created.data.settlementId; ``` The create response returns the queued transaction hash and the settlement contract address after DALP resolves the created settlement. When you provide a raw secret, DALP stores the encrypted secret so authorized decrypt flows can retrieve it later; when you provide only a hashlock, your integration keeps the matching secret. ## List, approve, and execute [#list-approve-and-execute] After creation, participants can list settlements and submit approvals from their own wallet context. The list operation applies participant visibility. The read operation fetches a known settlement by address within the active system and chain; it is not restricted to the caller's participant membership, so do not treat read as a participant-visibility check. ```ts const settlements = await client.addons.xvp.list({ query: { page: { limit: 10, offset: 0 } }, }); const approval = await client.addons.xvp.approve({ body: { settlementAddress, walletVerification }, }); ``` Approval can complete synchronously or return an async acceptance with a `statusUrl`. When token allowance must be queued first, the first async acceptance can represent the token approval step, not the final settlement approval. Wait for the status URL to reach a terminal state, then call `approve` again if settlement approval still needs to be submitted. Read the settlement after the approval flow completes. ```ts const settlement = await client.addons.xvp.read({ params: { settlementAddress }, }); console.log(settlements.meta.total, settlement.data.userApproved); ``` Use the read response to check: * whether the current user has approved, * each recorded approval account and timestamp, * settlement flags such as executed, cancelled, withdrawn, and secret-revealed, * the settlement flows and their local or external status. When the settlement is ready, execute it: ```ts await client.addons.xvp.execute({ body: { settlementAddress, walletVerification }, }); ``` If a participant needs to back out before execution, use approval revocation: ```ts await client.addons.xvp.revokeApproval({ body: { settlementAddress, walletVerification }, }); ``` If the settlement should not proceed, use cancellation: ```ts await client.addons.xvp.cancel({ body: { settlementAddress, walletVerification }, }); ``` Use `withdraw-cancel` to withdraw a cancellation proposal before the final cancellation state. Use `withdraw-expired` for expired settlement recovery. ## Secret and hashlock handling [#secret-and-hashlock-handling] External-flow settlements require either a raw secret or a hashlock when they are created. * If you provide a raw secret, DALP derives the hashlock and stores the encrypted secret for later retrieval. * If you provide a hashlock, your integration is responsible for managing the matching secret. * Use the decrypt operation only when your integration needs to retrieve a stored secret through the API. * Use the reveal-secret operation to publish the secret for hashlock-based settlement completion when that path applies. Local-only settlements do not use hashlock enforcement. ## CLI coverage [#cli-coverage] The DALP CLI exposes XvP create, read, and lifecycle operations under `dalp xvp-settlements`: ```bash dalp xvp-settlements list dalp xvp-settlements read 0xSETTLEMENT dalp xvp-settlements create --factory-address 0xFACTORY --name "Primary sale settlement" --cutoff-date 2026-06-30T17:00:00Z --flows '[{"type":"local","assetId":"0xASSET","from":"0xSENDER","to":"0xRECIPIENT","amount":"1000000"}]' dalp xvp-settlements approve 0xSETTLEMENT dalp xvp-settlements revoke-approval 0xSETTLEMENT dalp xvp-settlements execute 0xSETTLEMENT dalp xvp-settlements cancel 0xSETTLEMENT dalp xvp-settlements withdraw-cancel 0xSETTLEMENT dalp xvp-settlements withdraw-expired 0xSETTLEMENT dalp xvp-settlements decrypt 0xSETTLEMENT dalp xvp-settlements reveal-secret --address 0xSETTLEMENT --secret "shared-secret-value-at-least-32-chars" ``` The CLI create command accepts the factory address, name, cutoff date, and flows JSON. Use the API or SDK for creation scenarios that require a V3 country code, a raw secret, or a precomputed hashlock. ## Related references [#related-references] * [API integration getting started](/docs/developer-guides/api-integration/getting-started) * [API Reference](/docs/developer-guides/api-integration/api-reference) * [CLI Command Reference](/docs/developer-guides/cli/command-reference)