> ## 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.

# Settlements

> The core transaction object in KeyStone - created and enforced on-chain.

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:

| 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                                                                                                       |
| `trade_type`           | Optional. `repo_open`, `repo_close`, or `null` for standard DvP                                                                                                      |
| `linked_settlement_id` | Optional. Links a repo's opening and closing settlements to each other                                                                                               |
| `repo_terms`           | Optional. The repo economics (`tenor_days`, `rate_bps`, `haircut_bps`, margin band); maturity is derived as the opening settlement's creation time plus `tenor_days` |

## 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](/smart-contracts/overview) 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](/concepts/cross-platform) for details.

## Trade types

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

| Trade type          | Description                                                                               |
| ------------------- | ----------------------------------------------------------------------------------------- |
| `repo_open`         | Opening leg of a tokenised repo. Created by the platform with `repo_terms`.               |
| `repo_close`        | Closing leg of a tokenised repo. Auto-created by KeyStone at maturity with reversed legs. |
| `spot_dvp` / `null` | A standard settlement (default).                                                          |

### 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](/concepts/tokenised-repo) for the full concept explanation and [Execute a Tokenised Repo](/guides/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.