Cross-Platform Settlement

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

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

const tradeReference = sellerInstruction.tradeReference;

seller_instruction = await platform_a_client.instructions.submit({
    "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",
})

trade_reference = seller_instruction.trade_reference

The response includes a generated trade_reference:

{
  "trade_reference": "KS-a1b2c3d4-...",
  "status": "pending_match"
}

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

const buyerInstruction = await platformBClient.instructions.submit({
  idempotencyKey: platformBClient.generateIdempotencyKey(),
  tradeReference: "KS-a1b2c3d4-...",
  templateSlug: "dvp-standard",
  role: "buyer",
  party: {
    externalReference: "buyer-acct-042",
    name: "Beta Capital",
    walletAddress: "0xBuyerWallet...",
  },
  legs: [
    { legType: "asset_delivery", instrumentId: "0xTokenAddress", quantity: "500", direction: "receive", chainId: 11155111 },
    { legType: "payment", instrumentId: "0xUSDCAddress", quantity: "125000", direction: "deliver", chainId: 11155111 },
  ],
  timeoutAt: "2026-03-17T12:00:00Z",
});

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

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

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

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:

Both parties deposit to escrow contracts using their deposit secrets (via their own custody provider)
Contracts detect deposits complete, coordinator reveals recipient addresses and auto-executes the atomic swap
Settlement auto-finalizes

Both platforms receive the settlement’s webhooks as it progresses - see the webhook event catalog for which states emit events.

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"

// Platform A queries settlement
const settlement = await platformAClient.settlements.get("550e8400-...");

// Platform B queries settlement
const settlement = await platformBClient.settlements.get("550e8400-...");

# Platform A queries settlement
settlement = await platform_a_client.settlements.get("550e8400-...")

# Platform B queries settlement
settlement = await platform_b_client.settlements.get("550e8400-...")

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"

await platformAClient.instructions.cancel("inst-...");

await platform_a_client.instructions.cancel("inst-...")

Only pending_match instructions can be cancelled. Once matched, the settlement follows its normal lifecycle.

Cross-chain variant

v1 settles single-chain: both legs must live on the configured settlement chain, and registration rejects foreign-chain legs. Cross-chain settlement (e.g. bonds on Ethereum against USDC on Avalanche) is on the v2 roadmap.

Getting Started

Core Concepts

Guides

Smart Contracts

Cross-Platform Settlement

Flow overview

Step 1: Platform A submits seller instruction

Step 3: Platform B submits buyer instruction

Step 4: Compliance and autonomous execution

Monitoring

Cancelling before match

Cross-chain variant

​Flow overview

​Step 1: Platform A submits seller instruction

​Step 2: Share trade reference

​Step 3: Platform B submits buyer instruction

​Step 4: Compliance and autonomous execution

​Monitoring

​Cancelling before match

​Cross-chain variant

Flow overview

Step 1: Platform A submits seller instruction

Step 2: Share trade reference

Step 3: Platform B submits buyer instruction

Step 4: Compliance and autonomous execution

Monitoring

Cancelling before match

Cross-chain variant