Skip to main content
This guide walks through a complete single-platform DvP settlement where both buyer and seller are on your platform.

​
Prerequisites

  • Authenticated with M2M token (Authentication)
  • A DvP settlement template

​
Flow overview

​
Step 1: Create the settlement

Provide party details and legs inline in the settlement instruction. 
curl -X POST https://api.keystoneos.xyz/v1/settlements \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "dvp-example-001",
    "template_id": "YOUR_DvP_TEMPLATE_ID",
    "timeout_at": "2026-03-17T12:00:00Z",
    "parties": [
      {
        "role": "seller",
        "external_reference": "seller-acct-001",
        "name": "Acme Securities",
        "wallet_address": "0xSellerWallet...",
        "chain_id": 11155111
      },
      {
        "role": "buyer",
        "external_reference": "buyer-acct-002",
        "name": "Beta Capital",
        "wallet_address": "0xBuyerWallet...",
        "chain_id": 11155111
      }
    ],
    "legs": [
      {
        "leg_type": "asset",
        "instrument_id": "0xTokenContractAddress",
        "quantity": "1000",
        "direction": "deliver",
        "party_role": "seller"
      },
      {
        "leg_type": "payment",
        "instrument_id": "USDC",
        "quantity": "250000",
        "direction": "deliver",
        "party_role": "buyer"
      }
    ]
  }'
The API returns the settlement with state: "INSTRUCTED" and the engine begins processing immediately.

​
Step 2: Compliance screening

The engine automatically screens all parties through LSEG World-Check (entity) and CipherOwl (wallet). In ~95% of cases, this completes automatically and the settlement advances to COMPLIANCE_CLEARED. If a party is flagged, the settlement pauses. Submit a compliance decision to continue: 
curl -X POST https://api.keystoneos.xyz/v1/settlements/$ID/compliance-decision \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"decision": "approve"}'

​
Step 3: Escrow registration and deposits

Once compliance clears, the engine registers the settlement on the escrow smart contract and waits for deposits. Both parties deposit their assets to the escrow contract address on-chain. KeyStone detects deposits in real-time via Alchemy webhooks.
You don’t need to notify KeyStone when deposits are made. On-chain monitoring detects them automatically.

​
Step 4: Execution and finalization

When all deposits are confirmed:
  1. The escrow contract executes the atomic swap
  2. Tokens go to the buyer’s wallet, USDC goes to the seller’s wallet
  3. Settlement transitions to SETTLED, then FINALIZED
  4. Your webhook endpoint receives settlement.state.finalized

​
Monitoring

Track the settlement via polling or webhooks: 
# Get current state
curl https://api.keystoneos.xyz/v1/settlements/$ID \
  -H "Authorization: Bearer $TOKEN"

# Get full event history
curl https://api.keystoneos.xyz/v1/settlements/$ID/events \
  -H "Authorization: Bearer $TOKEN"

​
Error scenarios

ScenarioResult
Compliance rejectionSettlement -> ROLLED_BACK
Deposit timeoutSettlement -> TIMED_OUT, deposits returned
Execution failureSettlement -> ROLLED_BACK, deposits returned
Network error during deposit checkEngine retries on next webhook/poller cycle