Cross-Platform Settlement

This guide walks through a cross-platform DvP where Platform A’s seller delivers tokens to Platform B’s buyer using 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": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "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: "0x1234567890abcdef1234567890abcdef12345678",
  },
  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": "0x1234567890abcdef1234567890abcdef12345678",
    },
    "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.). The generated reference is unguessable and acts as the matching capability, so only a party it was shared with can submit the counterpart. A trade reference Platform A chose itself would not match here: caller-chosen references pair only within their own environment, so for cross-platform settlement the first instruction must be submitted with trade_reference: null and the generated reference shared. Both environments must also be the same type - a development instruction never pairs with a production one, whatever reference it presents - see match scope.

Step 3: Platform B submits buyer instruction

Platform B submits the counterpart 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": "0xfedcba9876543210fedcba9876543210fedcba98"
    },
    "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: "0xfedcba9876543210fedcba9876543210fedcba98",
  },
  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": "0xfedcba9876543210fedcba9876543210fedcba98",
    },
    "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 both instructions are confirmed, 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)
The final deposit executes the settlement atomically - every leg pays the recipient bound at registration
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 confirmation

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 confirmed, the settlement follows its normal lifecycle.

Cross-chain variant

Legs may live on different chains. Each leg must name a chain the environment has an active settlement contract on, which you can read from GET /v1/chains; a leg naming any other chain is rejected at registration. Where the leg set spans more than one chain, the KeystoneRouter coordinates release across them and the assets never bridge.

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 confirmation

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 confirmation

​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 confirmation

Cross-chain variant