Skip to main content

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.

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

​
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 on-chain 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..."
    },
    "legs": [
      {
        "leg_type": "asset_delivery",
        "instrument_id": "0xTokenContractAddress",
        "quantity": "1000",
        "direction": "deliver",
        "chain_id": 11155111
      },
      {
        "leg_type": "payment",
        "instrument_id": "0xUSDCAddress",
        "quantity": "250000",
        "direction": "receive",
        "chain_id": 11155111
      }
    ],
    "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..."
    },
    "legs": [
      {
        "leg_type": "asset_delivery",
        "instrument_id": "0xTokenContractAddress",
        "quantity": "1000",
        "direction": "receive",
        "chain_id": 11155111
      },
      {
        "leg_type": "payment",
        "instrument_id": "0xUSDCAddress",
        "quantity": "250000",
        "direction": "deliver",
        "chain_id": 11155111
      }
    ],
    "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.

​
Optional fields

FieldDescription
fee_modeOverride the default fee allocation for this settlement. Options: seller_pays, buyer_pays, split. Defaults to the platform environment setting.
settlement_categorySet to repo_open for repo opening legs. See Tokenised Repo.
maturity_atRequired for repo_open - when the closing leg should trigger.
repayment_amountRequired for repo_open - exact closing leg payment amount.
repo_rateOptional interest rate for repo (informational, stored in metadata).

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

Escrow Deposits

How parties deposit to escrow using commitment secrets.