Skip to main content
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

FieldTypeDescription
idUUIDSettlement UUID
statestrCurrent lifecycle state
template_idUUIDTemplate UUID
template_versionintTemplate version at creation
external_referencestr | NoneYour trade reference
partieslist[SettlementParty]Parties with roles and status
legslist[SettlementLeg]Legs with amounts and status
timeout_atdatetimeSettlement timeout
created_atdatetimeCreation timestamp
parent_settlement_idUUID | NoneFor repo closing legs
settlement_categorystr | None"repo_open", "repo_close", or None
maturity_atdatetime | NoneRepo maturity date
repo_metadatadict | NoneRepo rate, repayment amount

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

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