Skip to main content
Cross-platform settlement is the core value proposition of KeyStone OS. Platform A’s seller and Platform B’s buyer can settle atomically, with KeyStone coordinating compliance, escrow, and execution between them.

​
How it works

​
1. Initiation

Platform A initiates a settlement with their own party details inline and specifies counterparty platforms by slug: 
{
  "parties": [
    {
      "role": "seller",
      "external_reference": "seller-001",
      "name": "Acme Securities",
      "wallet_address": "0xSellerWallet...",
      "chain_id": 11155111
    }
  ],
  "counterparty_parties": [
    {
      "platform_slug": "platform-b",
      "role": "buyer",
      "wallet_address_hint": "0x...",
      "counterparty_reference": "Entity Name or LEI"
    }
  ]
}
The wallet_address_hint and counterparty_reference are optional hints that help Platform B identify which entity to assign.

​
2. Counterparty notification

KeyStone creates the counterparty party as a placeholder (status: pending_confirmation) and sends a settlement.confirmation_required webhook to Platform B.

​
3. Confirmation

Platform B reviews the settlement details and confirms with their party details: 
curl -X POST https://api.keystoneos.xyz/v1/settlements/$ID/confirm \
  -H "Authorization: Bearer $PLATFORM_B_TOKEN" \
  -d '{
    "external_reference": "buyer-acct-042",
    "name": "Beta Capital",
    "wallet_address": "0xBuyerWallet...",
    "chain_id": 11155111
  }'

​
4. Settlement proceeds

Once all parties confirm, the engine resumes and processes the settlement through the normal state machine (compliance, escrow, execution).

​
5. Rejection

Platform B can reject instead: 
curl -X POST https://api.keystoneos.xyz/v1/settlements/$ID/reject \
  -H "Authorization: Bearer $PLATFORM_B_TOKEN" \
  -d '{"reason": "Entity not found"}'
Rejection transitions the settlement to a failure state.

​
Identity model

KeyStone does not maintain a global identity registry. The confirmation flow IS the identity linking mechanism:
  1. Platform A optionally provides hints (wallet address, entity reference)
  2. Platform B uses those hints to find the right entity (or ignores them)
  3. Platform B confirms with their actual party details
  4. KeyStone doesn’t need to know who’s who across platforms
This means platforms retain full control over their entity data.

​
Authorization boundary

Each platform authenticates with its own M2M token. When Platform B calls /confirm, KeyStone verifies:
  • Platform B’s token is valid
  • Platform B has a pending_confirmation party in this settlement
  • The confirmation is scoped to Platform B’s environment
Platform A cannot confirm on Platform B’s behalf, and vice versa.

​
Webhook delivery

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

​
Idempotency

  • Confirming an already-confirmed party returns 200 (safe to retry)
  • Rejecting an already-rejected settlement returns 200 (safe to retry)
  • Confirming after rejection returns 409 (conflict, not a retry)
  • Rejecting after confirmation returns 409 (conflict, not a retry)