Settlements

Settlements can also be viewed and monitored in the KeyStone Dashboard. Use the SDK for programmatic creation and automation.

create

Direct settlement creation when both parties are known.

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",
})

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(). The bilateral instruction flow is the recommended approach for most integrations.

get

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

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

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

# 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

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}")

Overview

Backend SDKs

Frontend Library

Tools

create

get

Settlement fields

list

get_events

submit_compliance_decision

get_related

​create

​get

​Settlement fields

​list

​get_events

​submit_compliance_decision

​get_related

create

get

Settlement fields

list

get_events

submit_compliance_decision

get_related