Execute a Tokenised Repo

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 repo economics: tenor, rate, and haircut

Flow overview

A repo consists of two linked settlements:

Opening: Both parties submit repo_open instructions that match to create the opening settlement
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 trade_type: "repo_open" and matching repo_terms. 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",
    "trade_type": "repo_open",
    "repo_terms": {
      "tenor_days": 30,
      "rate_bps": 500,
      "haircut_bps": 500,
      "margin_band_lower": "0.95",
      "margin_band_upper": "1.05"
    }
  }'

const sellerInstruction = await sellerClient.instructions.submit({
  idempotencyKey: sellerClient.generateIdempotencyKey(),
  templateSlug: "dvp-standard",
  role: "seller",
  party: {
    externalReference: "bond-holder-001",
    name: "Acme Fixed Income",
    walletAddress: "0xSellerWallet...",
    chainId: 11155111,
  },
  legs: [
    { legType: "asset_delivery", instrumentId: "0xBondTokenAddress", quantity: "1000", direction: "deliver" },
    { instrumentId: "0xUSDCAddress", quantity: "950000", direction: "receive" },
  ],
  timeoutAt: "2026-03-20T12:00:00Z",
  tradeType: "repo_open",
  repoTerms: {
    tenorDays: 30,
    rateBps: 500,
    haircutBps: 500,
    marginBandLower: "0.95",
    marginBandUpper: "1.05",
  },
});

const tradeReference = sellerInstruction.tradeReference;

seller_instruction = await seller_client.instructions.submit({
    "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",
    "trade_type": "repo_open",
    "repo_terms": {
        "tenor_days": 30,
        "rate_bps": 500,
        "haircut_bps": 500,
        "margin_band_lower": "0.95",
        "margin_band_upper": "1.05",
    },
})

trade_reference = seller_instruction.trade_reference

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",
    "trade_type": "repo_open",
    "repo_terms": {
      "tenor_days": 30,
      "rate_bps": 500,
      "haircut_bps": 500,
      "margin_band_lower": "0.95",
      "margin_band_upper": "1.05"
    }
  }'

const buyerInstruction = await buyerClient.instructions.submit({
  idempotencyKey: buyerClient.generateIdempotencyKey(),
  tradeReference: "KS-abc123...",
  templateSlug: "dvp-standard",
  role: "buyer",
  party: {
    externalReference: "cash-lender-002",
    name: "Beta Capital",
    walletAddress: "0xBuyerWallet...",
    chainId: 11155111,
  },
  legs: [
    { legType: "asset_delivery", instrumentId: "0xBondTokenAddress", quantity: "1000", direction: "receive" },
    { legType: "payment", instrumentId: "USDC", quantity: "950000", direction: "deliver" },
  ],
  timeoutAt: "2026-03-20T12:00:00Z",
  tradeType: "repo_open",
  repoTerms: {
    tenorDays: 30,
    rateBps: 500,
    haircutBps: 500,
    marginBandLower: "0.95",
    marginBandUpper: "1.05",
  },
});

buyer_instruction = await buyer_client.instructions.submit({
    "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",
    "trade_type": "repo_open",
    "repo_terms": {
        "tenor_days": 30,
        "rate_bps": 500,
        "haircut_bps": 500,
        "margin_band_lower": "0.95",
        "margin_band_upper": "1.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 is derived, not passed: the closing settlement is due tenor_days after the opening settlement is created. The closing leg’s repayment amount is also derived - from tenor_days, rate_bps, and the opening payment-leg quantity - so you never pass it explicitly.

Step 2: Repo-specific instruction fields

Field	Required for repo_open	Description
`trade_type`	Yes	Must be `"repo_open"` (`"repo_close"` is auto-generated at maturity, not submitted)
`repo_terms.tenor_days`	Yes	Repo tenor; maturity = opening creation time + tenor
`repo_terms.rate_bps`	Yes	Repo rate in basis points; drives the derived repayment amount
`repo_terms.haircut_bps`	Yes	Collateral haircut in basis points
`repo_terms.margin_band_lower` / `margin_band_upper`	Yes	Margin band around the collateral value

Step 3: Opening settlement processes

The matched instructions create a settlement with:

trade_type: "repo_open"
repo_terms 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 derives the maturity as the opening settlement’s creation time plus tenor_days and checks it on a schedule. 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"

await client.settlements.triggerMaturity("550e8400-...");

await client.settlements.trigger_maturity("550e8400-...")

Step 5: Closing settlement auto-created

At maturity, KeyStone auto-creates two matching instructions for the closing leg (reversed roles and directions) - no party action is required to create it. The closing settlement then goes through the full flow: 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: The closing payment leg is derived from tenor_days, rate_bps, and the opening payment quantity (principal + interest)
Linked: linked_settlement_id ties the closing settlement to its opening (and repo_terms.close_leg_settlement_id on the opening points forward)

Step 6: Closing settlement completes

The closing settlement follows the same standard DvP flow:

Compliance screening
Escrow deposits (buyer deposits bonds, seller deposits USDC with interest)
Atomic swap (bonds return to seller, USDC + interest returns to buyer)
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"

const related = await client.settlements.related("550e8400-...");

console.log(`Opening: ${related.opening.state}`);
console.log(`Closing: ${related.closing?.state}`);

related = await client.settlements.related("550e8400-...")

print(f"Opening: {related.opening.state}")
print(f"Closing: {related.closing.state if related.closing else 'pending'}")

Response:

{
  "opening": {
    "id": "a1b2c3d4-...",
    "trade_type": "repo_open",
    "state": "FINALIZED",
    "linked_settlement_id": null,
    "repo_terms": {
      "tenor_days": 30,
      "rate_bps": 500,
      "haircut_bps": 500,
      "close_leg_settlement_id": "e5f6g7h8-..."
    }
  },
  "closing": {
    "id": "e5f6g7h8-...",
    "trade_type": "repo_close",
    "state": "FINALIZED",
    "linked_settlement_id": "a1b2c3d4-..."
  }
}

(Both objects are full settlement resources; only the repo-relevant fields are shown here. Calling /related on either leg returns the same pair.)

Error scenarios

Scenario	Result
Opening compliance rejection	Opening settlement ends in `REJECTED` (pre-deposit). No closing settlement is created.
Opening deposit timeout	Opening settlement times out. Deposits reclaimable. No closing created.
Closing compliance rejection	Closing settlement ends in `REJECTED`. Opening remains finalized.
Closing deposit timeout	Closing settlement times out. Deposits reclaimable. Manual resolution needed.

See Webhooks for setup instructions.

Getting Started

Core Concepts

Guides

Smart Contracts

Execute a Tokenised Repo

Prerequisites

Flow overview

Step 1: Submit opening instructions

Step 2: Repo-specific instruction fields

Step 3: Opening settlement processes

Step 4: Await maturity

Triggering maturity early (admin only)

Step 5: Closing settlement auto-created

Step 6: Closing settlement completes

Error scenarios

​Prerequisites

​Flow overview

​Step 1: Submit opening instructions

​Step 2: Repo-specific instruction fields

​Step 3: Opening settlement processes

​Step 4: Await maturity

​Triggering maturity early (admin only)

​Step 5: Closing settlement auto-created

​Step 6: Closing settlement completes

​Step 7: Query related settlements

​Error scenarios

Prerequisites

Flow overview

Step 1: Submit opening instructions

Step 2: Repo-specific instruction fields

Step 3: Opening settlement processes

Step 4: Await maturity

Triggering maturity early (admin only)

Step 5: Closing settlement auto-created

Step 6: Closing settlement completes

Step 7: Query related settlements

Error scenarios