Skip to main content
A settlement is a coordinated transaction between parties. It represents a real-world financial obligation (e.g. delivery of tokenized securities in exchange for payment) that must be executed atomically. The number of parties and their roles are set by the settlement’s template, not fixed by the platform: a standard DvP names two, a tri-party repo names three, and the contracts accept up to 50 parties and 50 legs. The paired-instruction flow described below covers the two-party case; templates with more roles are created directly through POST /v1/settlements.

​
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 confirmation.

​
Cross-platform

Parties span multiple platforms. Both platforms independently submit instructions via POST /instructions. When the second instruction arrives with the same trade reference and the details agree, 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.

​
Fees

KeyStone charges a settlement fee, paid on-chain to a KeyStone wallet by the settlement contract at the same moment the legs pay out. There is no invoice and no separate payment step. How it is calculated. The rate is set per environment in basis points (fee_bps, 1 bps = 0.01%) and defaults to zero. The fee is charged on deliver-direction payment legs only, computed from each such leg’s own quantity, and denominated in that leg’s token. A settlement funded by several cash legs is charged proportionally across them. Asset legs are never charged, and neither is a receive-direction payment leg. Who bears it. Set by fee_mode on the platform environment, which is the single source of fee policy. There is no per-settlement or per-instruction override, and the value in force is the one on the environment when KeyStone registers the settlement on-chain: A leg carries at most 10 fee entries (MAX_FEES_PER_LEG), each with its own recipient, amount and additive-or-deductive flag, all fixed at registration. Deductive fees can never exceed the leg amount; registration reverts if they do. When it is fixed. The fee amount, the split and the recipient wallet are all written into the settlement contract in the single registration call, before any deposit. Nothing can change them afterwards, and no KeyStone action selects or times the payment: the contract pays the fee as part of the same transaction that pays every leg.
Fees are the only respect in which a KeyStone address is a recipient of value from a settlement. Leg recipients are bound at registration and no KeyStone role can alter them. If a settlement is aborted or times out, no fee is charged: an additive fee is returned to the depositor along with the leg amount, and a deductive fee is never taken because no payout occurs.

​
Idempotency

Every create carries an idempotency_key you choose, unique within your environment. POST /v1/settlements and POST /v1/instructions both answer 201 with the existing resource when they see a key again, including when two requests with the same key run at the same time, so every creation call is safe to retry after a timeout. Keys starting with match- are refused with 422: KeyStone derives keys of that shape for the settlements it creates itself, and they share the namespace with yours. A key that merely contains -CLOSE-, such as GMRA-7781-CLOSE-LEG, is yours to use.

​
Timeout and rollback

Every settlement has a timeout_at deadline. In the pre-deposit states KeyStone’s timeout worker enforces it, escalating an expired settlement to MANUAL_REVIEW for an operator. Once the settlement is awaiting deposits with an escrow registered, the contract enforces the deadline itself: deposits and execution are accepted strictly before timeout_at, and at or after it either party can call the permissionless claimTimeout to move the escrow to TIMED_OUT, then claimRefund per deposited leg. KeyStone never calls claimTimeout for you, but it does surface the condition: reads report timeout_claimable: true, GET /v1/settlements?timeout_claimable=true lists every settlement in that condition, and a settlement.timeout_claimable activity entry is recorded. Refunds are pull payments, so no funds are ever locked indefinitely.