Skip to main content
A settlement is a coordinated bilateral transaction between two parties. It represents a real-world financial obligation (e.g. delivery of tokenized securities in exchange for payment) that must be executed atomically.

​
Anatomy of a settlement

Every settlement has:

​
On-chain coordination

Settlements are registered on the KeystoneSettlement contract with everything bound up front: recipients per leg, deposit keys, party hashes, and the timeout. The lifecycle itself is fixed in contract code - there are no per-settlement rules to store and no transition transactions.
  • On-chain enforcement - the contract owns its own lifecycle and checks gates (compliance, deposits) before any funds move; off-chain states are validated by the versioned dvp/v1 machine in the engine.
  • Autonomous post-compliance - after compliance clears, the contracts handle deposits, execution, and finalization.
  • Timeout safety - if the settlement has not completed by the deadline, every deposit becomes reclaimable per leg by its depositor.
See Smart Contracts for full architecture documentation.

​
Settlement types

​
Single-platform

Both parties belong to the same platform. Both parties submit instructions via POST /instructions using the same trade reference. The settlement proceeds immediately through the state machine after matching.

​
Cross-platform

Parties span multiple platforms. Both platforms independently submit instructions via POST /instructions. When the second instruction matches the first (same trade reference, compatible details), the settlement is created with both parties confirmed from the start.
See Cross-Platform Settlements for details.

​
Trade types

Settlements can optionally carry a trade_type that identifies their role in a multi-settlement workflow.

​
Repo settlements

A tokenised repo is modelled as two linked DvP settlements. The opening settlement carries repo_terms (tenor, rate, haircut, margin band); maturity is derived as its creation time plus tenor_days. When it finalizes and maturity arrives, KeyStone automatically creates the closing settlement with:
  • linked_settlement_id pointing to the opening settlement
  • Reversed legs (buyer returns bonds, seller returns USDC plus the derived interest)
  • Full compliance re-screening
See Tokenised Repo for the full concept explanation and Execute a Tokenised Repo for a step-by-step guide.

​
Idempotency

Every settlement instruction includes an idempotency_key scoped to your environment. If you send the same key twice, the API returns the existing instruction rather than creating a duplicate. This makes all creation calls safe to retry.

​
Timeout and rollback

Every settlement has a timeout_at deadline. If the settlement has not reached a terminal state by this time, it transitions to TIMED_OUT and the escrow contract returns any deposits to their original depositors. No funds are ever locked indefinitely.