Skip to main content
This guide walks you through initiating a single-platform DvP (Delivery vs. Payment) settlement using the KeyStone OS API.

​
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)
  • At least one settlement template configured

​
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"
  }'
The returned access_token is a JWT valid for 24 hours. Include it in all API requests: 
Authorization: Bearer {access_token}

​
Step 2: Initiate a settlement

Send a settlement instruction with parties, legs, and a template reference. Party details are provided inline - no separate registration step is needed. 
curl -X POST https://api.keystoneos.xyz/v1/settlements \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "dvp-2026-001",
    "template_id": "YOUR_TEMPLATE_ID",
    "timeout_at": "2026-03-17T00:00:00Z",
    "parties": [
      {
        "role": "buyer",
        "external_reference": "alice-001",
        "name": "Alice (Buyer)",
        "wallet_address": "0x1234...abcd",
        "chain_id": 11155111
      },
      {
        "role": "seller",
        "external_reference": "bob-001",
        "name": "Bob (Seller)",
        "wallet_address": "0x5678...efgh",
        "chain_id": 11155111
      }
    ],
    "legs": [
      {
        "leg_type": "asset",
        "instrument_id": "0xTokenContractAddress",
        "quantity": "100",
        "direction": "deliver",
        "party_role": "seller"
      },
      {
        "leg_type": "payment",
        "instrument_id": "USDC",
        "quantity": "50000",
        "direction": "deliver",
        "party_role": "buyer"
      }
    ]
  }'
The response includes the settlement ID and initial state: 
{
  "id": "a1b2c3d4-...",
  "state": "INSTRUCTED",
  "settlement_type": "single_platform",
  "parties": [...],
  "legs": [...],
  "created_at": "2026-03-16T12:00:00Z"
}

​
Step 3: Monitor progress

The settlement engine automatically advances through the template’s state machine. Track progress via: Polling: 
curl https://api.keystoneos.xyz/v1/settlements/$SETTLEMENT_ID \
  -H "Authorization: Bearer $TOKEN"
Webhooks (recommended): Register a webhook endpoint in the KeyStone Dashboard under Settings > Webhooks, then see the Webhooks guide for integration details.

​
What happens next

The engine processes each state in your template:
  1. INSTRUCTED - Settlement created, engine starts
  2. COMPLIANCE_CHECKING - Dual-layer compliance screening
  3. COMPLIANCE_CLEARED - All parties cleared
  4. REGISTERING_ESCROW - Escrow contract registration
  5. AWAITING_DEPOSITS - Waiting for on-chain deposits
  6. EXECUTING_SWAP - Atomic swap execution
  7. SETTLED - Assets exchanged
  8. FINALIZED - Settlement complete
If any step fails or times out, the settlement transitions to ROLLED_BACK and deposits are returned.

Next: Authentication

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