> ## 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.

# Cross-Platform Settlement

> How to settle a trade between parties on different platforms.

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

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'actorBkg': '#1a3a35', 'actorBorder': '#2DD4A8', 'actorTextColor': '#e0f2ef', 'actorLineColor': '#2DD4A8', 'signalColor': '#2DD4A8', 'signalTextColor': '#e0f2ef', 'noteBkgColor': '#162e2a', 'noteTextColor': '#e0f2ef', 'noteBorderColor': '#1AAF8B', 'activationBkgColor': '#1a3a35', 'activationBorderColor': '#2DD4A8', 'labelBoxBkgColor': '#1a3a35', 'labelBoxBorderColor': '#2DD4A8', 'labelTextColor': '#e0f2ef', 'loopTextColor': '#2DD4A8'}}}%%
sequenceDiagram
    participant PA as Platform A
    participant K as KeyStone API
    participant PB as Platform B
    participant SC as Contracts

    PA->>K: POST /instructions (seller side)
    K-->>PA: trade_reference: "KS-abc123"
    Note over PA,PB: Platform A shares trade_reference with Platform B
    PB->>K: POST /instructions (buyer side, same trade_reference)
    K->>K: Match instructions, create settlement on-chain
    K->>K: Compliance screening + attestation

    Note over SC: Contracts take over (autonomous)
    PA->>SC: Seller deposits to escrow
    PB->>SC: Buyer deposits to escrow
    SC->>SC: Auto-execute and finalize

    K-->>PA: Webhook: settlement.state.finalized
    K-->>PB: Webhook: settlement.state.finalized
```

## Step 1: Platform A submits seller instruction

Platform A creates their side of the settlement:

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```typescript TypeScript SDK theme={null}
  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;
  ```

  ```python Python SDK theme={null}
  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
  ```
</CodeGroup>

The response includes a generated `trade_reference`:

```json theme={null}
{
  "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:

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```typescript TypeScript SDK theme={null}
  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-..."
  ```

  ```python Python SDK theme={null}
  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-..."
  ```
</CodeGroup>

The response includes `status: "matched"` and the new `settlement_id`.

<Note>
  Both platforms authenticate with their own M2M tokens. Each platform can only see and manage their own instructions.
</Note>

## 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 the settlement's webhooks as it progresses - see the [webhook event catalog](/guides/webhook-events) for which states emit events.

## Monitoring

Both platforms can track the settlement:

<CodeGroup>
  ```bash cURL theme={null}
  # 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"
  ```

  ```typescript TypeScript SDK theme={null}
  // Platform A queries settlement
  const settlement = await platformAClient.settlements.get("550e8400-...");

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

  ```python Python SDK theme={null}
  # Platform A queries settlement
  settlement = await platform_a_client.settlements.get("550e8400-...")

  # Platform B queries settlement
  settlement = await platform_b_client.settlements.get("550e8400-...")
  ```
</CodeGroup>

## Cancelling before match

If Platform A wants to cancel before Platform B submits:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.keystoneos.xyz/v1/instructions/$INSTRUCTION_ID \
    -H "Authorization: Bearer $PLATFORM_A_TOKEN"
  ```

  ```typescript TypeScript SDK theme={null}
  await platformAClient.instructions.cancel("inst-...");
  ```

  ```python Python SDK theme={null}
  await platform_a_client.instructions.cancel("inst-...")
  ```
</CodeGroup>

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.