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

> Create, monitor, and manage settlements.

<Info>
  Settlements can also be viewed and monitored in the [KeyStone Dashboard](https://app.keystoneos.xyz). Use the SDK for programmatic creation and automation.
</Info>

## create

Direct settlement creation when both parties are known.

```python theme={null}
settlement = await client.settlements.create({
    "idempotency_key": client.generate_idempotency_key(),
    "template_slug": "dvp-bilateral",
    "external_reference": "TRADE-2026-0042",
    "parties": [
        {"role": "seller", "external_reference": "ACC-001", "wallet_address": "0xSeller..."},
        {"role": "buyer", "external_reference": "ACC-002", "wallet_address": "0xBuyer..."},
    ],
    "legs": [
        {"leg_type": "asset_delivery", "instrument_id": "OUSG", "quantity": "500000",
         "direction": "deliver", "party_role": "seller"},
        {"leg_type": "payment", "instrument_id": "USDC", "quantity": "502500",
         "direction": "deliver", "party_role": "buyer"},
    ],
    "timeout_at": "2026-12-01T00:00:00Z",
})
```

<Note>
  **Direct creation vs. bilateral instructions:** Use `settlements.create()` when your platform knows both parties upfront (single-platform use case). For cross-platform settlements - or when counterparties submit independently - use [`instructions.submit()`](/sdks/python/instructions). The bilateral instruction flow is the recommended approach for most integrations.
</Note>

***

## get

```python theme={null}
settlement = await client.settlements.get("settlement-uuid")

print(settlement.state)           # "AWAITING_DEPOSITS"
print(len(settlement.parties))    # 2
print(len(settlement.legs))       # 2
```

### Settlement fields

| Field                  | Type                    | Description                                                                                      |
| ---------------------- | ----------------------- | ------------------------------------------------------------------------------------------------ |
| `id`                   | `UUID`                  | Settlement UUID                                                                                  |
| `state`                | `str`                   | Current lifecycle state                                                                          |
| `template_id`          | `UUID`                  | Template UUID                                                                                    |
| `template_version`     | `int`                   | Template version at creation                                                                     |
| `external_reference`   | `str \| None`           | Your trade reference                                                                             |
| `parties`              | `list[SettlementParty]` | Parties with roles and status                                                                    |
| `legs`                 | `list[SettlementLeg]`   | Legs with amounts and status                                                                     |
| `timeout_at`           | `datetime`              | Settlement timeout                                                                               |
| `created_at`           | `datetime`              | Creation timestamp                                                                               |
| `linked_settlement_id` | `UUID \| None`          | Ties a repo's opening and closing legs together                                                  |
| `trade_type`           | `str \| None`           | `"spot_dvp"`, `"repo_open"`, or `"repo_close"`                                                   |
| `repo_terms`           | `RepoTerms \| None`     | Repo economics (`tenor_days`, `rate_bps`, `haircut_bps`, margin band, `close_leg_settlement_id`) |

***

## list

```python theme={null}
result = await client.settlements.list(state="FINALIZED", limit=20, offset=0)

for settlement in result.items:
    print(f"{settlement.id}: {settlement.state}")

print(f"Total: {result.total}, Has more: {result.has_more}")
```

***

## get\_events

```python theme={null}
result = await client.settlements.get_events("settlement-uuid")

for event in result.items:
    print(f"{event.from_state} -> {event.to_state} at {event.created_at}")
    print(f"  By: {event.triggered_by}, Hash: {event.content_hash}")
```

***

## submit\_compliance\_decision

```python theme={null}
# Approve
settlement = await client.settlements.submit_compliance_decision(
    "settlement-uuid", {"decision": "approve"}
)

# Reject
settlement = await client.settlements.submit_compliance_decision(
    "settlement-uuid", {"decision": "reject"}
)
```

***

## get\_related

```python theme={null}
related = await client.settlements.get_related("settlement-uuid")
if related.opening:
    print(f"Opening: {related.opening.id}")
if related.closing:
    print(f"Closing: {related.closing.id}")
```