Instructions - KeyStone OS

submit

Submit your side of a settlement.

instruction = await client.instructions.submit({
    "template_slug": "cross_platform_dvp",
    "role": "seller",
    "party": {
        "external_reference": "KSFI-II-4401",
        "name": "Securitize Fund I",
        "wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
    },
    "legs": [
        {
            "leg_type": "asset_delivery",
            "instrument_id": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
            "quantity": "12000000",
            "direction": "deliver",    # seller delivers the asset
            "chain_id": 11155111,
        },
        {
            "leg_type": "payment",
            "instrument_id": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
            "quantity": "12120000000000",
            "direction": "receive",    # seller receives payment
            "chain_id": 11155111,
        },
    ],
    "timeout_at": "2026-12-01T00:00:00Z",
    "idempotency_key": client.generate_idempotency_key(),
})

print(instruction.trade_reference)  # "KS-abc12345"
print(instruction.status)           # "pending_match" or "matched"
print(instruction.settlement_id)    # UUID if matched, None if pending

Parameters

Field	Type	Required	Description
`template_slug`	`str`	Yes	Settlement template
`role`	`str`	Yes	`"seller"` or `"buyer"`
`party`	`dict`	Yes	Your party details
`legs`	`list[dict]`	Yes	What you’re delivering
`timeout_at`	`str \| datetime`	Yes	Settlement timeout
`idempotency_key`	`str`	Yes	Unique key for safe retries; must not start with `match-`, which is reserved for keys KeyStone derives
`trade_reference`	`str`	No	Counterparty’s reference for the same pre-agreed trade. Your own reference pairs only within your environment; cross-platform pairing uses the generated reference, between environments of the same type (match scope)
`trade_type`	`str`	No	`"repo_open"` for repo lifecycle (`"spot_dvp"` default)
`repo_terms`	`dict`	With `repo_open`	Repo economics: `tenor_days`, `rate_bps`, `haircut_bps`, `margin_band_lower`, `margin_band_upper`

Return type: Instruction

Field	Type	Description
`id`	`UUID`	Instruction UUID
`trade_reference`	`str`	Trade reference (generated if not provided)
`status`	`str`	`"pending_match"`, `"matched"`, `"cancelled"`, `"expired"`
`settlement_id`	`UUID \| None`	Settlement UUID if matched

The pending_match / matched statuses describe reference correlation of a pre-agreed trade, not order matching - see what “matched” means.

| template_slug | str | Template used | | role | str | Submitted role | | party | dict | Party details | | legs | list[dict] | Leg details | | timeout_at | datetime | Settlement timeout | | expires_at | datetime | When this instruction expires | | created_at | datetime | Creation timestamp |

get / list / cancel

instruction = await client.instructions.get("instruction-uuid")

result = await client.instructions.list(status="pending_match", limit=20)
for instr in result.items:
    print(f"{instr.trade_reference}: {instr.status}")

cancelled = await client.instructions.cancel("instruction-uuid")