Your First Settlement

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"

const { items } = await client.templates.list();

for (const template of items) {
  console.log(`${template.slug} - ${template.name}`);
}

result = await client.templates.list()

for template in result.items:
    print(f"{template.slug} - {template.name}")

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": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "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"
  }'

const sellerInstruction = await client.instructions.submit({
  idempotencyKey: client.generateIdempotencyKey(),
  templateSlug: "dvp-standard",
  role: "seller",
  party: {
    externalReference: "seller-001",
    name: "Acme Securities",
    walletAddress: "0x1234567890abcdef1234567890abcdef12345678",
  },
  legs: [
    { legType: "asset_delivery", instrumentId: "0xTokenAddress", quantity: "100", direction: "deliver", chainId: 11155111 },
    { legType: "payment", instrumentId: "0xUSDCAddress", quantity: "50000", direction: "receive", chainId: 11155111 },
  ],
  timeoutAt: "2026-03-17T00:00:00Z",
});

const tradeReference = sellerInstruction.tradeReference;

seller_instruction = await client.instructions.submit({
    "idempotency_key": "my-first-dvp-seller",
    "template_slug": "dvp-standard",
    "role": "seller",
    "party": {
        "external_reference": "seller-001",
        "name": "Acme Securities",
        "wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
    },
    "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",
})

trade_reference = seller_instruction.trade_reference

Save the returned trade_reference (e.g. KS-abc123...).

3. Submit the buyer instruction

The buyer’s platform submits the counterpart 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": "0xfedcba9876543210fedcba9876543210fedcba98"
    },
    "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"
  }'

const buyerInstruction = await client.instructions.submit({
  idempotencyKey: client.generateIdempotencyKey(),
  tradeReference: "KS-abc123...",
  templateSlug: "dvp-standard",
  role: "buyer",
  party: {
    externalReference: "buyer-001",
    name: "Beta Capital",
    walletAddress: "0xfedcba9876543210fedcba9876543210fedcba98",
  },
  legs: [
    { legType: "asset_delivery", instrumentId: "0xTokenAddress", quantity: "100", direction: "receive", chainId: 11155111 },
    { legType: "payment", instrumentId: "0xUSDCAddress", quantity: "50000", direction: "deliver", chainId: 11155111 },
  ],
  timeoutAt: "2026-03-17T00:00:00Z",
});

console.log(buyerInstruction.status);       // "matched"
console.log(buyerInstruction.settlementId); // "550e8400-..."

buyer_instruction = await client.instructions.submit({
    "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": "0xfedcba9876543210fedcba9876543210fedcba98",
    },
    "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",
})

print(buyer_instruction.status)         # "matched"
print(buyer_instruction.settlement_id)  # "550e8400-..."

The idempotency_key ensures safe retries. If you send the same key twice, the API returns the existing instruction instead of creating a duplicate. Keys starting with match- are reserved for keys KeyStone derives and are refused with 422.

The response includes status: "matched" and a settlement_id. The settlement is created automatically; it is registered on-chain once compliance clears.

4. Watch compliance run

After confirmation, 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"}'

const settlement = await client.compliance.approve("550e8400-...");

settlement = await client.compliance.approve("550e8400-...")

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. For each deliver leg, call POST /v1/settlements/{id}/legs/{leg_index}/deposit-calldata to obtain pre-encoded depositLeg calldata with the deposit secret embedded, plus the ERC-20 approval calldata. Your platform submits both transactions through its custody provider (such as MPC wallets or any signing infrastructure). Settlement reads never include the deposit secret; the calldata endpoint is the only place it leaves the API. KeyStone is not involved in the deposit step. The escrow contract verifies keccak256(abi.encode(msg.sender, depositSecret)) == depositKey to authorize the deposit - the key binds both the depositor wallet and the secret, so a leaked secret is useless from any other wallet.

6. Contracts handle the rest

Once every leg is deposited, the KeystoneSettlement contract takes over autonomously:

The last required deposit executes the settlement inline, provided the on-chain compliance gate has passed
The contract pays every leg to its recipient bound at registration - one atomic transaction, all-or-nothing
Tokens go to the buyer’s wallet, USDC goes to the seller’s wallet
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"

// Get settlement status
const settlement = await client.settlements.get("550e8400-...");
console.log(settlement.state);

// View event history
const events = await client.settlements.events("550e8400-...");
for (const event of events.items) {
  console.log(`${event.fromState} -> ${event.toState}`);
}

# Get settlement status
settlement = await client.settlements.get("550e8400-...")
print(settlement.state)

# View event history
events = await client.settlements.events("550e8400-...")
for event in events.items:
    print(f"{event.from_state} -> {event.to_state}")

What if something goes wrong?

Compliance rejection - Settlement ends in REJECTED. No deposits were made at that point.
Deposit timeout - If deposits are not received by timeout_at, the settlement transitions to TIMED_OUT and partial deposits become reclaimable. The operator or any depositor can trigger the timeout on-chain; it cannot be paused.
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.

Submitting Instructions

Full guide to instruction submission, confirmation, and cancellation.

Getting Started

Core Concepts

Guides

Smart Contracts

Your First Settlement

What we are building

1. Browse available templates

2. Submit the seller instruction

3. Submit the buyer instruction

4. Watch compliance run

5. Deposit to escrow

6. Contracts handle the rest

7. Check the result

What if something goes wrong?

Core Concepts

Submitting Instructions

​What we are building

​1. Browse available templates

​2. Submit the seller instruction

​3. Submit the buyer instruction

​4. Watch compliance run

​5. Deposit to escrow

​6. Contracts handle the rest

​7. Check the result

​What if something goes wrong?

Core Concepts

Submitting Instructions

What we are building

1. Browse available templates

2. Submit the seller instruction

3. Submit the buyer instruction

4. Watch compliance run

5. Deposit to escrow

6. Contracts handle the rest

7. Check the result

What if something goes wrong?