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

# Instructions

> Submit and manage bilateral settlement instructions.

## submit

Submit your side of a bilateral settlement.

```python theme={null}
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                                                                       |
| `trade_reference` | `str`             | No               | Existing reference to match                                                                       |
| `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                                 |
| `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

```python theme={null}
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")
```