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.

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:
PropertyDescription
idUnique identifier (UUID)
template_idThe template governing this settlement’s workflow
stateCurrent position in the state machine
settlement_typesingle_platform or cross_platform
partiesThe entities involved and their roles
legsThe obligations to be fulfilled
idempotency_keyClient-provided key for safe retries
timeout_atDeadline - settlement rolls back if not completed by this time
settlement_categoryOptional. repo_open, repo_close, or null for standard DvP
parent_settlement_idOptional. Links a repo_close settlement to its repo_open parent
maturity_atOptional. When a repo_open settlement’s closing leg should be created

​
On-chain coordination

Settlements are created on the SettlementCoordinator contract. The contract stores the state machine rules and enforces that every transition is valid.
  • On-chain enforcement - the contract validates every state transition and checks gates (compliance, deposits) before allowing progress.
  • Autonomous post-compliance - after compliance clears, the contracts handle deposits, execution, and finalization.
  • Timeout safety - if the settlement has not completed by the deadline, the escrow contract returns all deposits.
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. 
Platform A submits instruction -> Gets trade reference
Platform A shares reference with Platform B (out-of-band)
Platform B submits matching instruction -> Settlement created automatically
See Cross-Platform Settlements for details.

​
Settlement categories

Settlements can optionally carry a settlement_category that identifies their role in a multi-settlement workflow.
CategoryDescription
repo_openOpening leg of a tokenised repo. Created by the platform with a maturity_at timestamp.
repo_closeClosing leg of a tokenised repo. Auto-created by KeyStone at maturity with reversed legs.
nullA standard settlement (default).

​
Repo settlements

A tokenised repo is modelled as two linked DvP settlements. The opening settlement carries a maturity_at timestamp. When it finalizes and maturity arrives, KeyStone automatically creates the closing settlement with:
  • parent_settlement_id pointing to the opening settlement
  • Reversed legs (buyer returns bonds, seller returns USDC)
  • 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.