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 a complete tokenised repo lifecycle - from opening to maturity to closing - using bilateral instructions and autonomous on-chain execution.

​
Prerequisites

  • Authenticated with M2M token (Authentication)
  • A DvP settlement template available
  • Both parties have wallet addresses on a supported chain
  • You know the maturity date and repayment amount for the repo

​
Flow overview

A repo consists of two linked settlements:
  1. Opening: Both parties submit repo_open instructions that match to create the opening settlement
  2. Closing: KeyStone auto-creates a repo_close settlement when maturity arrives
Both settlements follow the standard flow: instruction matching, compliance, deposits to escrow, autonomous execution.

​
Step 1: Submit opening instructions

Both counterparties submit instructions with settlement_category: "repo_open". The first party receives a trade reference, the second party includes it to trigger matching. Seller submits first: 
curl -X POST https://api.keystoneos.xyz/v1/instructions \
  -H "Authorization: Bearer $SELLER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_slug": "dvp-standard",
    "role": "seller",
    "party": {
      "external_reference": "bond-holder-001",
      "name": "Acme Fixed Income",
      "wallet_address": "0xSellerWallet...",
      "chain_id": 11155111
    },
    "legs": [
      {
        "leg_type": "asset_delivery",
        "instrument_id": "0xBondTokenAddress",
        "quantity": "1000",
        "direction": "deliver"
      },
      {
        "instrument_id": "0xUSDCAddress",
        "quantity": "950000",
        "direction": "receive"
      }
    ],
    "timeout_at": "2026-03-20T12:00:00Z",
    "idempotency_key": "repo-seller-001",
    "settlement_category": "repo_open",
    "maturity_at": "2026-04-17T12:00:00Z",
    "repayment_amount": "952375.00",
    "repo_rate": "0.05"
  }'
Response includes a trade_reference: 
{
  "id": "...",
  "trade_reference": "KS-abc123...",
  "status": "pending_match"
}
Buyer submits with the same trade_reference: 
curl -X POST https://api.keystoneos.xyz/v1/instructions \
  -H "Authorization: Bearer $BUYER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trade_reference": "KS-abc123...",
    "template_slug": "dvp-standard",
    "role": "buyer",
    "party": {
      "external_reference": "cash-lender-002",
      "name": "Beta Capital",
      "wallet_address": "0xBuyerWallet...",
      "chain_id": 11155111
    },
    "legs": [
      {
        "leg_type": "asset_delivery",
        "instrument_id": "0xBondTokenAddress",
        "quantity": "1000",
        "direction": "receive"
      },
      {
        "leg_type": "payment",
        "instrument_id": "USDC",
        "quantity": "950000",
        "direction": "deliver"
      }
    ],
    "timeout_at": "2026-03-20T12:00:00Z",
    "idempotency_key": "repo-buyer-001",
    "settlement_category": "repo_open",
    "maturity_at": "2026-04-17T12:00:00Z",
    "repayment_amount": "952375.00",
    "repo_rate": "0.05"
  }'
When instructions match, the response shows status: "matched" and includes the settlement_id.
timeout_at controls when the opening settlement times out if not completed. maturity_at controls when the closing settlement is created after the opening finalizes. repayment_amount is the exact amount for the closing leg’s payment (principal + interest).

​
Step 2: Repo-specific instruction fields

FieldRequired for repo_openDescription
settlement_categoryYesMust be "repo_open"
maturity_atYesWhen the closing leg should trigger (must be in the future)
repayment_amountYesExact closing leg cash amount (principal + interest)
repo_rateNoInterest rate (informational, stored in metadata)

​
Step 3: Opening settlement processes

The matched instructions create a settlement with:
  • settlement_category: "repo_open"
  • maturity_at and repo_metadata stored on the settlement
  • Standard DvP flow: compliance screening, escrow deposits, atomic swap
The settlement engine processes it automatically through all stages.

​
Step 4: Await maturity

The opening settlement finalizes. KeyStone monitors the maturity_at timestamp. When maturity arrives, the system automatically creates the closing settlement.

​
Triggering maturity early (admin only)

Administrators can trigger maturity before the scheduled date: 
curl -X POST https://api.keystoneos.xyz/v1/admin/settlements/$OPENING_ID/trigger-maturity \
  -H "Authorization: Bearer $ADMIN_TOKEN"

​
Step 5: Closing settlement auto-created

At maturity, both parties submit new instructions for the closing leg (reversed directions). The closing settlement goes through the full flow: matching, compliance re-screening, deposits to escrow, autonomous execution.
  • Reversed roles: Opening seller becomes closing buyer, and vice versa
  • Reversed directions: Deliver becomes receive, receive becomes deliver
  • Repayment amount: Payment leg uses repayment_amount instead of original price
  • Linked: parent_settlement_id points to the opening settlement

​
Step 6: Closing settlement completes

The closing settlement follows the same standard DvP flow:
  1. Compliance screening
  2. Escrow deposits (buyer deposits bonds, seller deposits USDC with interest)
  3. Atomic swap (bonds return to seller, USDC + interest returns to buyer)
  4. Settlement finalizes
Your webhook endpoint receives settlement.state.finalized for the closing settlement. At any point, you can query both legs of a repo: 
curl https://api.keystoneos.xyz/v1/settlements/$OPENING_ID/related \
  -H "Authorization: Bearer $TOKEN"
Response: 
{
  "opening": {
    "id": "a1b2c3d4-...",
    "settlement_category": "repo_open",
    "state": "FINALIZED",
    "parent_settlement_id": null,
    "maturity_at": "2026-04-17T12:00:00Z"
  },
  "closing": {
    "id": "e5f6g7h8-...",
    "settlement_category": "repo_close",
    "state": "FINALIZED",
    "parent_settlement_id": "a1b2c3d4-..."
  }
}

​
Error scenarios

ScenarioResult
Opening compliance rejectionOpening settlement rolls back. No closing settlement is created.
Opening deposit timeoutOpening settlement times out. Deposits returned. No closing created.
Closing compliance rejectionClosing settlement rolls back. Opening remains finalized.
Closing deposit timeoutClosing settlement times out. Deposits returned. Manual resolution needed.
See Webhooks for setup instructions.