Single-Platform DvP

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": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "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"
  }'

const sellerInstruction = await client.instructions.submit({
  idempotencyKey: client.generateIdempotencyKey(),
  templateSlug: "dvp-standard",
  role: "seller",
  party: {
    externalReference: "seller-acct-001",
    name: "Acme Securities",
    walletAddress: "0x1234567890abcdef1234567890abcdef12345678",
  },
  legs: [
    { legType: "asset_delivery", instrumentId: "0xTokenContractAddress", quantity: "1000", direction: "deliver", chainId: 11155111 },
    { legType: "payment", instrumentId: "0xUSDCAddress", quantity: "250000", direction: "receive", chainId: 11155111 },
  ],
  timeoutAt: "2026-03-17T12:00:00Z",
});

const tradeReference = sellerInstruction.tradeReference;

seller_instruction = await client.instructions.submit({
    "idempotency_key": "dvp-seller-001",
    "template_slug": "dvp-standard",
    "role": "seller",
    "party": {
        "external_reference": "seller-acct-001",
        "name": "Acme Securities",
        "wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
    },
    "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",
})

trade_reference = seller_instruction.trade_reference

Save the returned trade_reference for the next step.

Step 2: Submit the buyer instruction

Submit the buyer’s counterpart 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": "0xfedcba9876543210fedcba9876543210fedcba98"
    },
    "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"
  }'

const buyerInstruction = await client.instructions.submit({
  idempotencyKey: client.generateIdempotencyKey(),
  tradeReference: "KS-abc123...",
  templateSlug: "dvp-standard",
  role: "buyer",
  party: {
    externalReference: "buyer-acct-002",
    name: "Beta Capital",
    walletAddress: "0xfedcba9876543210fedcba9876543210fedcba98",
  },
  legs: [
    { legType: "asset_delivery", instrumentId: "0xTokenContractAddress", quantity: "1000", direction: "receive", chainId: 11155111 },
    { legType: "payment", instrumentId: "0xUSDCAddress", quantity: "250000", direction: "deliver", chainId: 11155111 },
  ],
  timeoutAt: "2026-03-17T12:00:00Z",
});

console.log(buyerInstruction.status);       // "matched"
console.log(buyerInstruction.settlementId); // "550e8400-..."

buyer_instruction = await client.instructions.submit({
    "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": "0xfedcba9876543210fedcba9876543210fedcba98",
    },
    "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",
})

print(buyer_instruction.status)         # "matched"
print(buyer_instruction.settlement_id)  # "550e8400-..."

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"}'

const settlement = await client.compliance.approve("550e8400-...");

settlement = await client.compliance.approve("550e8400-...")

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. Fetch each deliver leg’s deposit transaction from POST /v1/settlements/{id}/legs/{leg_index}/deposit-calldata - the response carries pre-encoded depositLeg calldata with that leg’s deposit secret embedded - and submit it via your custody provider (such as MPC wallets or any signing infrastructure). The secret is served per leg by this endpoint only; it does not appear in settlement reads. KeyStone is not involved in the deposit step. The escrow contract verifies keccak256(abi.encode(msg.sender, depositSecret)) == depositKey to authorize each deposit - the key binds both the depositor wallet and the secret, so it can only be redeemed from the wallet it was computed for.

Step 5: Contracts auto-execute and finalize

When all deposits are confirmed, the contracts take over autonomously:

The last deposit triggers execution inline once the compliance gate passes
The contract verifies the compliance gate and pays every leg to its recipient bound at registration
Tokens go to the buyer’s wallet, USDC goes to the seller’s wallet
Settlement transitions to FINALIZED
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"

// Get current state
const settlement = await client.settlements.get("550e8400-...");
console.log(settlement.state);

// Get full event history
const events = await client.settlements.events("550e8400-...");
for (const event of events.items) {
  console.log(`${event.fromState} -> ${event.toState}`);
}

# Get current state
settlement = await client.settlements.get("550e8400-...")
print(settlement.state)

# Get full event history
events = await client.settlements.events("550e8400-...")
for event in events.items:
    print(f"{event.from_state} -> {event.to_state}")

Error scenarios

Scenario	Result
Compliance rejection	Settlement -> `REJECTED` (before any deposits)
Deposit timeout	Settlement -> `TIMED_OUT`, deposits reclaimable on-chain (operator or any depositor)
Execution failure	Settlement -> `ROLLED_BACK`, deposits returned

Getting Started

Core Concepts

Guides

Smart Contracts

Prerequisites

Flow overview

Step 1: Submit the seller instruction

Step 2: Submit the buyer instruction

Step 3: Compliance screening

Step 4: Parties deposit to escrow

Step 5: Contracts auto-execute and finalize

Monitoring

Error scenarios

​Prerequisites

​Flow overview

​Step 1: Submit the seller instruction

​Step 2: Submit the buyer instruction

​Step 3: Compliance screening

​Step 4: Parties deposit to escrow

​Step 5: Contracts auto-execute and finalize

​Monitoring

​Error scenarios

Prerequisites

Flow overview

Step 1: Submit the seller instruction

Step 2: Submit the buyer instruction

Step 3: Compliance screening

Step 4: Parties deposit to escrow

Step 5: Contracts auto-execute and finalize

Monitoring

Error scenarios