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 cross-platform DvP where Platform A’s seller delivers tokens to Platform B’s buyer using bilateral instruction submission and autonomous on-chain execution.

​
Flow overview

​
Step 1: Platform A submits seller instruction

Platform A creates their side of the settlement: 
curl -X POST https://api.keystoneos.xyz/v1/instructions \
  -H "Authorization: Bearer $PLATFORM_A_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "cross-dvp-seller-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": "0xTokenAddress",
        "quantity": "500",
        "direction": "deliver",
        "chain_id": 11155111
      },
      {
        "leg_type": "payment",
        "instrument_id": "0xUSDCAddress",
        "quantity": "125000",
        "direction": "receive",
        "chain_id": 11155111
      }
    ],
    "timeout_at": "2026-03-17T12:00:00Z"
  }'
The response includes a generated trade_reference: 
{
  "trade_reference": "KS-a1b2c3d4-...",
  "status": "pending_match"
}

​
Step 2: Share trade reference

Platform A shares the trade reference with Platform B through their own communication channels (API integration, OTC desk, email, etc.).

​
Step 3: Platform B submits buyer instruction

Platform B submits the matching instruction with the same trade reference: 
curl -X POST https://api.keystoneos.xyz/v1/instructions \
  -H "Authorization: Bearer $PLATFORM_B_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "cross-dvp-buyer-001",
    "trade_reference": "KS-a1b2c3d4-...",
    "template_slug": "dvp-standard",
    "role": "buyer",
    "party": {
      "external_reference": "buyer-acct-042",
      "name": "Beta Capital",
      "wallet_address": "0xBuyerWallet..."
    },
    "legs": [
      {
        "leg_type": "asset_delivery",
        "instrument_id": "0xTokenAddress",
        "quantity": "500",
        "direction": "receive",
        "chain_id": 11155111
      },
      {
        "leg_type": "payment",
        "instrument_id": "0xUSDCAddress",
        "quantity": "125000",
        "direction": "deliver",
        "chain_id": 11155111
      }
    ],
    "timeout_at": "2026-03-17T12:00:00Z"
  }'
The response includes status: "matched" and the new settlement_id.
Both platforms authenticate with their own M2M tokens. Each platform can only see and manage their own instructions.

​
Step 4: Compliance and autonomous execution

Once instructions match, the settlement is created on-chain with both parties confirmed. KeyStone handles compliance screening and attestation. After compliance clears:
  1. Both parties deposit to escrow contracts using their deposit secrets (via their own custody provider)
  2. Contracts detect deposits complete, coordinator reveals recipient addresses and auto-executes the atomic swap
  3. Settlement auto-finalizes
Both platforms receive webhooks at every state transition.

​
Monitoring

Both platforms can track the settlement: 
# Platform A queries settlement
curl https://api.keystoneos.xyz/v1/settlements/$SETTLEMENT_ID \
  -H "Authorization: Bearer $PLATFORM_A_TOKEN"

# Platform B queries settlement
curl https://api.keystoneos.xyz/v1/settlements/$SETTLEMENT_ID \
  -H "Authorization: Bearer $PLATFORM_B_TOKEN"

​
Cancelling before match

If Platform A wants to cancel before Platform B submits: 
curl -X DELETE https://api.keystoneos.xyz/v1/instructions/$INSTRUCTION_ID \
  -H "Authorization: Bearer $PLATFORM_A_TOKEN"
Only pending_match instructions can be cancelled. Once matched, the settlement follows its normal lifecycle.

​
Cross-chain variant

If Platform A’s seller has bonds on Ethereum and Platform B’s buyer has USDC on Avalanche, the same instruction flow works. Include the chain_id in each leg to indicate which chain the asset is on. See Cross-Chain Settlement for the full guide.