Quickstart

This guide walks you through a complete DvP (Delivery vs. Payment) settlement using bilateral instruction submission and autonomous on-chain execution.

Prerequisites

A KeyStone OS platform account with API credentials (M2M client ID and secret) - find these in the KeyStone Dashboard under Settings > General
An active environment (sandbox or production)

Step 1: Authenticate

KeyStone uses Auth0 M2M (client credentials) tokens for platform API access.

curl --request POST \
  --url https://auth.keystoneos.xyz/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://api.keystoneos.xyz",
    "grant_type": "client_credentials"
  }'

import { KeystoneClient } from "@keystoneos/sdk";

// The SDK handles token acquisition and refresh automatically
const client = new KeystoneClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

from keystoneos import KeystoneClient

# The SDK handles token acquisition and refresh automatically
client = KeystoneClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)

The returned access_token is a JWT valid for 24 hours. Include it in all API requests:

Authorization: Bearer {access_token}

Step 2: Browse available templates

Templates define the settlement workflow and are pre-configured by KeyStone. Browse the available templates to find the right one for your use case.

curl https://api.keystoneos.xyz/v1/settlement-templates \
  -H "Authorization: Bearer $TOKEN"

const { items } = await client.templates.list();

for (const template of items) {
  console.log(`${template.slug} - ${template.name}`);
}

result = await client.templates.list()

for template in result.items:
    print(f"{template.slug} - {template.name}")

Pick the template that matches your settlement type. For a standard DvP settlement, use the dvp-standard template. Note the slug field - you will reference it when submitting instructions.

Step 3: Submit the seller instruction

Submit one side of the trade. KeyStone generates a trade reference that your counterparty will use to submit the other side.

curl -X POST https://api.keystoneos.xyz/v1/instructions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "dvp-2026-001",
    "template_slug": "dvp-standard",
    "role": "seller",
    "party": {
      "external_reference": "seller-001",
      "name": "Acme Securities",
      "wallet_address": "0xSellerWallet..."
    },
    "legs": [
      {
        "leg_type": "asset_delivery",
        "instrument_id": "0xTokenContractAddress",
        "quantity": "100",
        "direction": "deliver",
        "chain_id": 11155111
      },
      {
        "leg_type": "payment",
        "instrument_id": "0xUSDCAddress",
        "quantity": "50000",
        "direction": "receive",
        "chain_id": 11155111
      }
    ],
    "timeout_at": "2026-03-20T00:00:00Z"
  }'

const instruction = await client.instructions.submit({
  idempotencyKey: client.generateIdempotencyKey(),
  templateSlug: "dvp-standard",
  role: "seller",
  party: {
    externalReference: "seller-001",
    name: "Acme Securities",
    walletAddress: "0xSellerWallet...",
  },
  legs: [
    { legType: "asset_delivery", instrumentId: "0xTokenContractAddress", quantity: "100", direction: "deliver", chainId: 11155111 },
    { legType: "payment", instrumentId: "0xUSDCAddress", quantity: "50000", direction: "receive", chainId: 11155111 },
  ],
  timeoutAt: "2026-03-20T00:00:00Z",
});

console.log(instruction.tradeReference); // "KS-a1b2c3d4-..."

instruction = await client.instructions.submit({
    "idempotency_key": "dvp-2026-001",
    "template_slug": "dvp-standard",
    "role": "seller",
    "party": {
        "external_reference": "seller-001",
        "name": "Acme Securities",
        "wallet_address": "0xSellerWallet...",
    },
    "legs": [
        {"leg_type": "asset_delivery", "instrument_id": "0xTokenContractAddress", "quantity": "100", "direction": "deliver", "chain_id": 11155111},
        {"leg_type": "payment", "instrument_id": "0xUSDCAddress", "quantity": "50000", "direction": "receive", "chain_id": 11155111},
    ],
    "timeout_at": "2026-03-20T00:00:00Z",
})

print(instruction.trade_reference)  # "KS-a1b2c3d4-..."

The response includes a generated trade reference:

{
  "id": "inst-...",
  "trade_reference": "KS-a1b2c3d4-...",
  "status": "pending_match",
  "settlement_id": null
}

Send the trade_reference to your counterparty through your own channels (email, chat, API integration, etc.). They will use it to submit the matching instruction.

Step 5: Counterparty submits matching instruction

The counterparty submits their side with the same trade reference:

curl -X POST https://api.keystoneos.xyz/v1/instructions \
  -H "Authorization: Bearer $COUNTERPARTY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "dvp-2026-001-buyer",
    "trade_reference": "KS-a1b2c3d4-...",
    "template_slug": "dvp-standard",
    "role": "buyer",
    "party": {
      "external_reference": "buyer-001",
      "name": "Beta Capital",
      "wallet_address": "0xBuyerWallet..."
    },
    "legs": [
      {
        "leg_type": "asset_delivery",
        "instrument_id": "0xTokenContractAddress",
        "quantity": "100",
        "direction": "receive",
        "chain_id": 11155111
      },
      {
        "leg_type": "payment",
        "instrument_id": "0xUSDCAddress",
        "quantity": "50000",
        "direction": "deliver",
        "chain_id": 11155111
      }
    ],
    "timeout_at": "2026-03-20T00:00:00Z"
  }'

const buyerInstruction = await counterpartyClient.instructions.submit({
  idempotencyKey: counterpartyClient.generateIdempotencyKey(),
  tradeReference: "KS-a1b2c3d4-...",
  templateSlug: "dvp-standard",
  role: "buyer",
  party: {
    externalReference: "buyer-001",
    name: "Beta Capital",
    walletAddress: "0xBuyerWallet...",
  },
  legs: [
    { legType: "asset_delivery", instrumentId: "0xTokenContractAddress", quantity: "100", direction: "receive", chainId: 11155111 },
    { legType: "payment", instrumentId: "0xUSDCAddress", quantity: "50000", direction: "deliver", chainId: 11155111 },
  ],
  timeoutAt: "2026-03-20T00:00:00Z",
});

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

buyer_instruction = await counterparty_client.instructions.submit({
    "idempotency_key": "dvp-2026-001-buyer",
    "trade_reference": "KS-a1b2c3d4-...",
    "template_slug": "dvp-standard",
    "role": "buyer",
    "party": {
        "external_reference": "buyer-001",
        "name": "Beta Capital",
        "wallet_address": "0xBuyerWallet...",
    },
    "legs": [
        {"leg_type": "asset_delivery", "instrument_id": "0xTokenContractAddress", "quantity": "100", "direction": "receive", "chain_id": 11155111},
        {"leg_type": "payment", "instrument_id": "0xUSDCAddress", "quantity": "50000", "direction": "deliver", "chain_id": 11155111},
    ],
    "timeout_at": "2026-03-20T00:00:00Z",
})

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

When the instructions match, the response includes the new settlement:

{
  "id": "inst-...",
  "trade_reference": "KS-a1b2c3d4-...",
  "status": "matched",
  "settlement_id": "550e8400-..."
}

Step 6: Settlement created on-chain

After matching, the settlement enters INSTRUCTED and KeyStone registers it on the KeystoneSettlement contract - recipients, deposit keys, party hashes, and the timeout are all bound at registration.

Step 7: Compliance runs automatically

If the template has compliance configured, KeyStone screens all parties through LSEG World-Check (entity) and CipherOwl (wallet), then attests the results to the ComplianceRegistry on-chain. The contract enforces that compliance must pass before the settlement can advance.

Step 8: Both parties deposit to escrow

When the settlement reaches AWAITING_DEPOSITS, the settlement response includes a deposit_secret and deposit_key for each leg. Both parties deposit their assets directly to the escrow smart contract by calling depositLeg(settlementId, legIndex, depositSecret). Your platform uses its custody provider to sign the deposit transaction. KeyStone is not involved in the deposit step.

Step 9: Contracts auto-execute and finalize

The last deposit executes the settlement inline once the compliance gate passes - the contract pays every leg to its recipient bound at registration in one atomic transaction. Tokens go to the buyer, USDC goes to the seller. KeyStone observes the SettlementExecuted event and the settlement moves through SETTLED to FINALIZED.

Step 10: Check the result

curl https://api.keystoneos.xyz/v1/settlements/$SETTLEMENT_ID \
  -H "Authorization: Bearer $TOKEN"

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

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

Or subscribe to webhooks for real-time notifications. Register a webhook endpoint in the KeyStone Dashboard under Settings > Webhooks.

What happened

INSTRUCTED --> COMPLIANCE_CHECKING --> COMPLIANCE_CLEARED
           --> AWAITING_DEPOSITS --> SETTLED --> FINALIZED

Phase	Who drives it
Instruction matching	KeyStone API (off-chain)
On-chain creation	KeyStone engine
Compliance screening	KeyStone compliance oracle
Compliance attestation	KeyStone compliance oracle
Past compliance gate	KeyStone engine (one transition)
Deposits	Parties deposit directly to escrow
Execution	Contracts (autonomous)
Finalization	Contracts (autonomous)
Timeout (if needed)	Operator or any depositor (not pausable)

Next: Authentication

Learn about M2M tokens, user tokens, scopes, and environment resolution.

Getting Started

Core Concepts

Guides

Smart Contracts

Prerequisites

Step 1: Authenticate

Step 2: Browse available templates

Step 3: Submit the seller instruction

Step 5: Counterparty submits matching instruction

Step 6: Settlement created on-chain

Step 7: Compliance runs automatically

Step 8: Both parties deposit to escrow

Step 9: Contracts auto-execute and finalize

Step 10: Check the result

What happened

Next: Authentication

​Prerequisites

​Step 1: Authenticate

​Step 2: Browse available templates

​Step 3: Submit the seller instruction

​Step 4: Share trade reference with counterparty

​Step 5: Counterparty submits matching instruction

​Step 6: Settlement created on-chain

​Step 7: Compliance runs automatically

​Step 8: Both parties deposit to escrow

​Step 9: Contracts auto-execute and finalize

​Step 10: Check the result

​What happened

Next: Authentication

Prerequisites

Step 1: Authenticate

Step 2: Browse available templates

Step 3: Submit the seller instruction

Step 4: Share trade reference with counterparty

Step 5: Counterparty submits matching instruction

Step 6: Settlement created on-chain

Step 7: Compliance runs automatically

Step 8: Both parties deposit to escrow

Step 9: Contracts auto-execute and finalize

Step 10: Check the result

What happened