Skip to main content
Bilateral instruction submission is the primary way to initiate settlements in KeyStone OS. Both counterparties independently submit their side of the trade. When both instructions arrive, KeyStone automatically matches them and creates a settlement.

​
How it works

  1. First party submits: Platform A sends an instruction without a trade_reference. KeyStone generates one (format: KS-{uuid}).
  2. Share the reference: Platform A shares the trade reference with Platform B through their own channels (email, chat, API, etc.).
  3. Second party submits: Platform B sends an instruction with the same trade_reference. KeyStone finds the matching pending instruction.
  4. Automatic matching: KeyStone validates that both instructions are compatible and creates a settlement with both parties confirmed.

​
Step 1: Submit the first instruction

The first party submits their side of the trade. Leave trade_reference null to have KeyStone generate one. 
curl -X POST https://api.keystoneos.xyz/v1/instructions \
  -H "Authorization: Bearer $PLATFORM_A_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "seller-instruction-001",
    "template_slug": "dvp-standard",
    "role": "seller",
    "party": {
      "external_reference": "seller-acct-001",
      "name": "Acme Securities",
      "wallet_address": "0xSellerWallet...",
      "chain_id": 11155111
    },
    "legs": [
      {
        "instrument_id": "0xTokenContractAddress",
        "quantity": "1000",
        "direction": "deliver"
      },
      {
        "instrument_id": "0xUSDCAddress",
        "quantity": "250000",
        "direction": "receive"
      }
    ],
    "timeout_at": "2026-03-20T00:00:00Z"
  }'
Response: 
{
  "id": "inst-...",
  "trade_reference": "KS-abc123-def4-5678-...",
  "status": "pending_match",
  "role": "seller",
  "settlement_id": null,
  "created_at": "2026-03-19T10:00:00Z"
}

​
Step 2: Share the trade reference

The trade reference (KS-abc123...) is shared between counterparties through their own communication channels. KeyStone does not handle this exchange - it is an out-of-band coordination step. Common methods:
  • Platform-to-platform API integration
  • Pre-agreed trade reference via OTC desk
  • Shared trade confirmation system

​
Step 3: Submit the matching instruction

The second party submits their instruction with the trade reference from Step 1. 
curl -X POST https://api.keystoneos.xyz/v1/instructions \
  -H "Authorization: Bearer $PLATFORM_B_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "buyer-instruction-001",
    "trade_reference": "KS-abc123-def4-5678-...",
    "template_slug": "dvp-standard",
    "role": "buyer",
    "party": {
      "external_reference": "buyer-acct-042",
      "name": "Beta Capital",
      "wallet_address": "0xBuyerWallet...",
      "chain_id": 11155111
    },
    "legs": [
      {
        "instrument_id": "0xTokenContractAddress",
        "quantity": "1000",
        "direction": "receive"
      },
      {
        "instrument_id": "0xUSDCAddress",
        "quantity": "250000",
        "direction": "deliver"
      }
    ],
    "timeout_at": "2026-03-20T00:00:00Z"
  }'
If the instructions match, the response includes the settlement: 
{
  "id": "inst-...",
  "trade_reference": "KS-abc123-def4-5678-...",
  "status": "matched",
  "settlement_id": "stl-...",
  "created_at": "2026-03-19T10:05:00Z"
}

​
What matching validates

Both instructions must agree on:
FieldValidation
template_slugMust be identical
roleMust be different (one seller, one buyer)
InstrumentsSame set of instrument_id values
QuantitiesMust match per instrument
DirectionsMust be complementary (seller delivers what buyer receives)
If validation fails, the second instruction is still saved as pending_match. It will not be automatically paired with the first instruction. The submitting platform can cancel it and resubmit with corrected details.

​
Cancellation

Cancel a pending instruction if it was submitted in error or the trade is no longer needed: 
curl -X DELETE https://api.keystoneos.xyz/v1/instructions/$INSTRUCTION_ID \
  -H "Authorization: Bearer $TOKEN"
Only instructions with status: pending_match can be cancelled. Matched or expired instructions cannot be cancelled.

​
Expiry

Instructions have a default 24-hour time-to-live. After expiry, they are no longer eligible for matching. This prevents stale instructions from accidentally matching with new ones submitted days later.

​
Listing instructions

View your platform’s instructions: 
# All instructions
curl https://api.keystoneos.xyz/v1/instructions \
  -H "Authorization: Bearer $TOKEN"

# Filter by status
curl "https://api.keystoneos.xyz/v1/instructions?status=pending_match" \
  -H "Authorization: Bearer $TOKEN"

​
Single-platform use

Bilateral instructions work for single-platform settlements too. When both instructions come from the same platform, the settlement is created as single_platform type. This is useful when your platform intermediates trades between its own users.

Cross-Chain Settlement

How bilateral instructions enable cross-chain DvP.

Direct Contract Integration

Bypass the API and call contracts directly.