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.

This guide walks through the complete lifecycle of a Delivery vs. Payment (DvP) settlement, from instruction submission to autonomous on-chain finalization.

​
What we are building

A tokenized private credit settlement where:
  • Seller delivers 100 tokens of a private credit fund
  • Buyer pays 50,000 USDC
  • Both legs settle atomically - either both complete or neither does

​
1. Browse available templates

Templates define the settlement workflow and are pre-configured by KeyStone. Browse the available templates to find the right one for your use case. 
curl https://api.keystoneos.xyz/v1/settlement-templates \
  -H "Authorization: Bearer $TOKEN"
Pick the template that matches your settlement type. For a standard DvP settlement, use the dvp-standard template. Note the slug field - you will reference it when submitting instructions.
Templates are managed by KeyStone admins. If you need a custom template for your use case, contact your KeyStone representative.

​
2. Submit the seller instruction

The seller’s platform submits their side of the trade: 
curl -X POST https://api.keystoneos.xyz/v1/instructions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "my-first-dvp-seller",
    "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": "100",
        "direction": "deliver",
        "chain_id": 11155111
      },
      {
        "leg_type": "payment",
        "instrument_id": "0xUSDCAddress",
        "quantity": "50000",
        "direction": "receive",
        "chain_id": 11155111
      }
    ],
    "timeout_at": "2026-03-17T00:00:00Z"
  }'
Save the returned trade_reference (e.g. KS-abc123...).

​
3. Submit the buyer instruction

The buyer’s platform submits the matching instruction: 
curl -X POST https://api.keystoneos.xyz/v1/instructions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "my-first-dvp-buyer",
    "trade_reference": "KS-abc123...",
    "template_slug": "dvp-standard",
    "role": "buyer",
    "party": {
      "external_reference": "buyer-001",
      "name": "Beta Capital",
      "wallet_address": "0xBuyerWallet..."
    },
    "legs": [
      {
        "leg_type": "asset_delivery",
        "instrument_id": "0xTokenAddress",
        "quantity": "100",
        "direction": "receive",
        "chain_id": 11155111
      },
      {
        "leg_type": "payment",
        "instrument_id": "0xUSDCAddress",
        "quantity": "50000",
        "direction": "deliver",
        "chain_id": 11155111
      }
    ],
    "timeout_at": "2026-03-17T00:00:00Z"
  }'
The idempotency_key ensures safe retries. If you send the same key twice, the API returns the existing instruction instead of creating a duplicate.
The response includes status: "matched" and a settlement_id. The settlement is created automatically on-chain.

​
4. Watch compliance run

After matching, the settlement engine screens all parties through LSEG World-Check (entity) and CipherOwl (wallet). Results are attested to the ComplianceRegistry on-chain, and the contract enforces that compliance must pass before the settlement can advance. If a party is flagged, the settlement pauses at COMPLIANCE_CHECKING. A compliance officer reviews and submits a decision: 
curl -X POST https://api.keystoneos.xyz/v1/settlements/$SETTLEMENT_ID/compliance-decision \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"decision": "approve"}'
If rejected, the settlement transitions to ROLLED_BACK.

​
5. Deposit to escrow

When the settlement reaches AWAITING_DEPOSITS, both parties deposit their assets directly to the escrow smart contract on-chain. Each leg in the settlement response includes a deposit_secret and deposit_key. Your platform calls depositLeg(settlementId, legIndex, depositSecret) on the escrow contract using its custody provider (such as MPC wallets or any signing infrastructure) to sign the transaction. KeyStone is not involved in the deposit step. The escrow contract verifies keccak256(depositSecret) == depositKey to authorize the deposit - no address-based validation.

​
6. Contracts handle the rest

Once all deposits are confirmed, the contracts take over autonomously:
  1. The escrow contract detects all deposits are complete and notifies the SettlementCoordinator
  2. The coordinator verifies the atomicity gate (all legs deposited on all chains)
  3. The coordinator calls executeSettlement(settlementId, recipients[]) on the escrow - revealing recipient addresses only at this point
  4. Tokens go to the buyer’s wallet, USDC goes to the seller’s wallet
  5. Settlement transitions to FINALIZED

​
7. Check the result

Track progress in the KeyStone Dashboard under Settlements, or via the API: 
# Poll settlement status
curl https://api.keystoneos.xyz/v1/settlements/$SETTLEMENT_ID \
  -H "Authorization: Bearer $TOKEN"

# View event history
curl https://api.keystoneos.xyz/v1/settlements/$SETTLEMENT_ID/events \
  -H "Authorization: Bearer $TOKEN"

​
What if something goes wrong?

  • Compliance rejection - Settlement rolls back. No deposits affected.
  • Deposit timeout - If deposits are not received by timeout_at, the settlement transitions to TIMED_OUT and the escrow contract returns any partial deposits. Anyone can trigger this timeout permissionlessly on-chain.
  • Execution failure - The escrow contract rolls back, returning all deposits to their original owners.
Every failure path is deterministic and recorded in the event history. No funds are ever locked indefinitely.

Core Concepts

Deep dive into settlements, templates, and the state machine.

Bilateral Instructions

Full guide to instruction submission, matching, and cancellation.