XvP settlement flows

XvP settlements coordinate multiple value-transfer legs between participants. Use this flow to create a settlement, collect approvals, execute the local DALP-managed leg, reconcile external legs, 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.

For external-flow settlements, DALP does not operate a bridge, relay messages, or move assets on another chain. It does not prove that another chain executed. DALP records the external-chain leg, requires a secret or hashlock, and exposes fields your integration can compare with evidence from the external EVM chain.

When to use this flow

Use an XvP settlement when your system has the XvP settlement add-on factory available.

A valid XvP settlement has at least one local on-chain flow managed by the active DALP system. Use this page when participants need to approve the settlement before execution, or when your integration must 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 for exact request and response fields, and the CLI Command Reference for command syntax.

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:

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.

An external flow is a reconciliation reference. Set externalChainId to a different EVM chain from the active DALP chain. The asset address, sender, recipient, amount, and decimals must match the evidence your integration checks on that external chain. DALP stores those fields and gates local execution with the hashlock. DALP does not submit, guarantee, or roll back the external-chain transaction.

For systems using the current XvP settlement factory identity model, include the ISO 3166-1 numeric country code required by the factory.

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

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.

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.

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:

await client.addons.xvp.execute({
  body: { settlementAddress, walletVerification },
});

If a participant needs to back out before execution, use approval revocation:

await client.addons.xvp.revokeApproval({
  body: { settlementAddress, walletVerification },
});

If the settlement should not proceed, use cancellation:

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.

Verify an external-flow settlement

An external-flow settlement combines at least one DALP-managed local leg with one or more external references. DALP records each external leg's chain, asset reference, parties, amount, hashlock, and secret-reveal state. Your integration uses that record to reconcile the local settlement against matching external-chain evidence.

This boundary is important: DALP does not submit, relay, or guarantee the external transfer. A revealed secret only shows that the hashlock gate for the DALP-managed settlement was satisfied. Your system must still verify the matching external execution with the venue, chain, or workflow that handles that leg.

Treat the external leg as evidence to verify, not as a DALP-managed execution path. The external route may be an HTLC, bridge, exchange, custody workflow, or another controlled settlement process chosen outside DALP. The DALP read response shows the local record and local hashlock secret state. The response does not prove that the external route is safe or that a third-party venue completed its side correctly.

Check that evidence before approval, reveal, execution, or recovery.

Use the read response as the reconciliation surface:

const settlement = await client.addons.xvp.read({
  params: { settlementAddress },
});

for (const flow of settlement.data.flows) {
  if (flow.isExternal) {
    console.log(flow.externalChainId, flow.asset?.id, flow.from.id, flow.to.id, flow.amountExact);
  }
}

console.log(settlement.data.hashlock, settlement.data.secretRevealed, settlement.data.secretRevealTx);

For each external flow, match the response against the corresponding settlement or evidence on the external EVM chain:

Proceed only when the local approvals are complete and the matching external-chain settlement or evidence agrees with the recorded external flow. If the matching side cannot be verified before the cutoff date, use cancellation or expired-settlement recovery instead of forcing execution.

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.

Monitor settlement state

XvP integrations reconcile settlement state through the list and read endpoints. The list endpoint is the polling surface for settlement collections.

Use collection pagination, global search, and filters for name, cutoffDate, participant, systemAddon, and createdAt. Use the read endpoint when you already know the settlement address and need the current approvals, flows, and terminal flags for that settlement.

const page = await client.addons.xvp.list({
  query: {
    limit: 25,
    offset: 0,
    sortBy: "createdAt",
    sortDirection: "desc",
    filters: [
      { id: "participant", operator: "eq", value: "0xPARTICIPANT" },
      { id: "systemAddon", operator: "eq", value: "0xXVPADDON" },
    ],
  },
});

for (const item of page.data) {
  const detail = await client.addons.xvp.read({
    params: { settlementAddress: item.id },
  });

  if (detail.data.executed || detail.data.cancelled || detail.data.withdrawn) {
    continue;
  }

  // Continue approval, reveal, execution, cancellation, or expiry handling.
}

Treat the indexed payload as your checkpoint. The indexer records these XvP events before the API exposes them:

• creation,
• approval and approval revocation,
• execution,
• cancellation and cancel votes,
• expiry withdrawal,
• secret reveal.

A transaction can be final on-chain before the latest indexed state appears in the list response. Poll the list or read endpoint until the expected flag, approval row, or secret-reveal metadata appears.

Do not wait for a webhook when your integration needs the current XvP state. Use collection filtering and read polling as the stable reconciliation path. Webhook endpoints are available for selected DALP event delivery.

CLI coverage

The DALP CLI exposes XvP create, read, and lifecycle operations under dalp xvp-settlements:

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

• API integration getting started
• API Reference
• CLI Command Reference