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

> How settlements span multiple platforms with bilateral instruction matching.

Cross-platform settlement is the core value proposition of KeyStone. Platform A's seller and Platform B's buyer can settle atomically, with contracts handling deposits, execution, and finalization autonomously.

## How it works

Both platforms independently submit settlement instructions via `POST /instructions`. KeyStone matches them automatically when the second instruction arrives with the same trade reference.

```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 (Seller)
    participant KS as KeyStone API
    participant PB as Platform B (Buyer)
    participant SC as Contracts

    PA->>KS: POST /instructions (seller side)
    KS-->>PA: trade_reference: "KS-abc123"

    Note over PA,PB: Platform A shares trade_reference with Platform B

    PB->>KS: POST /instructions (buyer side, same trade_reference)
    KS->>KS: Match instructions, create settlement on-chain
    KS->>KS: Compliance screening + attestation

    Note over SC: Contracts take over (autonomous)
    PA->>SC: Deposit to escrow (via custody provider or any wallet)
    PB->>SC: Deposit to escrow (via custody provider or any wallet)
    SC->>SC: Auto-execute and finalize

    SC-->>PA: Event: settlement finalized
    SC-->>PB: Event: settlement finalized
```

### 1. First instruction

Platform A submits their side of the trade. KeyStone generates a trade reference:

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

### 2. Trade reference exchange

Platform A shares the trade reference with Platform B through their own channels. KeyStone does not handle this exchange.

### 3. Matching instruction

Platform B submits their side with the same trade reference. KeyStone validates that the instructions are compatible (same template, different roles, same instruments, matching quantities, complementary directions) and creates a settlement with both parties confirmed.

### 4. Settlement proceeds autonomously

After matching, KeyStone handles compliance screening and attestation. From that point:

1. Both parties deposit to escrow contracts directly (using their own custody provider)
2. Contracts detect deposits complete and auto-execute the 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.

## Identity model

KeyStone does not maintain a global identity registry. Each platform provides their own party details in their instruction:

1. Platform A provides their party's wallet address, name, and external reference
2. Platform B provides their party's wallet address, name, and external reference
3. The trade reference links the two sides together
4. KeyStone does not need to know who's who across platforms

Platforms retain full control over their entity data.

## Authorization boundary

Each platform authenticates with its own M2M token. Platforms can only see and manage their own instructions. When instructions match, the resulting settlement is visible to both platforms.

## Webhook delivery

In cross-platform settlements, webhooks are delivered to ALL involved platforms, not just the first to submit. Every state change is pushed to every platform that has a party in the settlement.

## Cross-chain support

Cross-platform does not mean cross-chain: in v1 both legs settle on a single chain through the KeystoneSettlement contract. Cross-chain settlement (e.g. bond on Ethereum, USDC on Avalanche) is on the v2 roadmap.