Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.keystoneos.xyz/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks through a complete single-platform DvP settlement where both buyer and seller are on your platform. After compliance, the contracts handle everything autonomously.

​
Prerequisites

  • Authenticated with M2M token (Authentication)
  • A DvP settlement template available (browse via GET /v1/settlement-templates)

​
Flow overview

​
Step 1: Submit the seller instruction

Provide the seller’s party details and their legs: 
curl -X POST https://api.keystoneos.xyz/v1/instructions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "dvp-seller-001",
    "template_slug": "dvp-standard",
    "role": "seller",
    "party": {
      "external_reference": "seller-acct-001",
      "name": "Acme Securities",
      "wallet_address": "0xSellerWallet..."
    },
    "legs": [
      {
        "leg_type": "asset_delivery",
        "instrument_id": "0xTokenContractAddress",
        "quantity": "1000",
        "direction": "deliver",
        "chain_id": 11155111
      },
      {
        "leg_type": "payment",
        "instrument_id": "0xUSDCAddress",
        "quantity": "250000",
        "direction": "receive",
        "chain_id": 11155111
      }
    ],
    "timeout_at": "2026-03-17T12:00:00Z"
  }'
Save the returned trade_reference for the next step.

​
Step 2: Submit the buyer instruction

Submit the buyer’s matching instruction with the same trade reference: 
curl -X POST https://api.keystoneos.xyz/v1/instructions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "dvp-buyer-001",
    "trade_reference": "KS-abc123...",
    "template_slug": "dvp-standard",
    "role": "buyer",
    "party": {
      "external_reference": "buyer-acct-002",
      "name": "Beta Capital",
      "wallet_address": "0xBuyerWallet..."
    },
    "legs": [
      {
        "leg_type": "asset_delivery",
        "instrument_id": "0xTokenContractAddress",
        "quantity": "1000",
        "direction": "receive",
        "chain_id": 11155111
      },
      {
        "leg_type": "payment",
        "instrument_id": "0xUSDCAddress",
        "quantity": "250000",
        "direction": "deliver",
        "chain_id": 11155111
      }
    ],
    "timeout_at": "2026-03-17T12:00:00Z"
  }'
The response includes status: "matched" and a settlement_id. The settlement is created on-chain and the engine begins processing.

​
Step 3: Compliance screening

The engine automatically screens all parties through LSEG World-Check (entity) and CipherOwl (wallet). Results are attested to the ComplianceRegistry on-chain. 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/$SETTLEMENT_ID/compliance-decision \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"decision": "approve"}'

​
Step 4: Parties deposit to escrow

Once compliance clears, the settlement reaches AWAITING_DEPOSITS. Both parties deposit their assets directly to the escrow smart contract on-chain using their deposit_secret (included in the settlement response for each leg). Your platform calls depositLeg(settlementId, legIndex, depositSecret) via its custody provider (such as MPC wallets or any signing infrastructure). KeyStone is not involved in the deposit step. The escrow contract verifies keccak256(depositSecret) == depositKey to authorize each deposit.

​
Step 5: Contracts auto-execute and finalize

When all deposits are confirmed, the contracts take over autonomously:
  1. The escrow contract detects all deposits are complete and notifies the SettlementCoordinator
  2. The coordinator verifies the atomicity gate and calls executeSettlement with recipient addresses (revealed at this point)
  3. Tokens go to the buyer’s wallet, USDC goes to the seller’s wallet
  4. Settlement transitions to FINALIZED
  5. 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/$SETTLEMENT_ID \
  -H "Authorization: Bearer $TOKEN"

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

​
Error scenarios

ScenarioResult
Compliance rejectionSettlement -> ROLLED_BACK
Deposit timeoutSettlement -> TIMED_OUT, deposits returned (permissionless on-chain)
Execution failureSettlement -> ROLLED_BACK, deposits returned