Anatomy of a settlement
Every settlement has:| Property | Description |
|---|---|
id | Unique identifier (UUID) |
template_id | The template governing this settlement’s workflow |
state | Current position in the state machine |
settlement_type | single_platform or cross_platform |
parties | The entities involved and their roles |
legs | The obligations to be fulfilled |
idempotency_key | Client-provided key for safe retries |
timeout_at | Deadline - settlement rolls back if not completed by this time |
settlement_category | Optional. repo_open, repo_close, or null for standard DvP |
parent_settlement_id | Optional. Links a repo_close settlement to its repo_open parent |
maturity_at | Optional. When a repo_open settlement’s closing leg should be created |
Settlement types
Single-platform
Both parties belong to the same platform. The initiating platform provides all party details (external reference, name, wallet address) inline in the settlement instruction. The settlement proceeds immediately through the state machine.Cross-platform
Parties span multiple platforms. The initiating platform specifies counterparty platforms by slug. Counterparty parties are created as placeholders (status: pending_confirmation) until the counterparty platform confirms by providing their party details.
Settlement categories
Settlements can optionally carry asettlement_category that identifies their role in a multi-settlement workflow.
| Category | Description |
|---|---|
repo_open | Opening leg of a tokenised repo. Created by the platform with a maturity_at timestamp. |
repo_close | Closing leg of a tokenised repo. Auto-created by KeyStone at maturity with reversed legs. |
null | A standard settlement (default). |
Repo settlements
A tokenised repo is modelled as two linked DvP settlements. The opening settlement carries amaturity_at timestamp. When it finalizes and maturity arrives, KeyStone automatically creates the closing settlement with:
parent_settlement_idpointing to the opening settlement- Reversed legs (buyer returns bonds, seller returns USDC)
- Full compliance re-screening
GET /v1/settlements/{id}/related.
See Tokenised Repo for the full concept explanation and Execute a Tokenised Repo for a step-by-step guide.
Idempotency
Every settlement instruction includes anidempotency_key scoped to your environment. If you send the same key twice, the API returns the existing settlement rather than creating a duplicate. This makes all settlement creation calls safe to retry.
Timeout and rollback
Every settlement has atimeout_at deadline. If the settlement hasn’t reached a terminal state by this time, it transitions to TIMED_OUT and the escrow contract returns any deposits to their original owners.
This guarantee means there is no risk of funds being locked indefinitely.