> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowboy.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# cowboy session

> Open, fund, settle, close, and inspect CIP-8 MPP payment sessions

## Synopsis

```bash theme={null}
cowboy session [--rpc-url <url>] <subcommand>

cowboy session models [--json]
cowboy session open --model <name> --max-amount <wei> [--expires-at <block>] [--exclude <address>]... [--signer <address>] [--session-id <hex>] [--price-advert-digest <hex>] [--private-key <path>] [--nonce <n>] [--json]
cowboy session open --runner <address> --max-amount <wei> --expires-at <block> [--session-id <hex>] [--price-advert-digest <hex>] [--private-key <path>] [--nonce <n>] [--json]
cowboy session voucher --session-id <hex> --cumulative-amount <wei> --voucher-nonce <n> --voucher-expires-at <block> [--usage-digest <hex>] [--private-key <path>] [--json]
cowboy session deposit --session-id <hex> --amount <wei> [--private-key <path>] [--nonce <n>] [--json]
cowboy session settle --session-id <hex> --cumulative-amount <wei> --voucher-nonce <n> --voucher-expires-at <block> [--usage-digest <hex>] [--signer-key <path>] [--private-key <path>] [--nonce <n>] [--json]
cowboy session settle --voucher <json|@file> [--session-id <hex>] [--private-key <path>] [--nonce <n>] [--json]
cowboy session close --session-id <hex> [--private-key <path>] [--nonce <n>] [--json]
cowboy session finalize --session-id <hex> [--private-key <path>] [--nonce <n>] [--json]
cowboy session get --session-id <hex> [--json]
```

`cowboy session` drives the on-chain [CIP-8](https://docs.cowboy.inc/cips/cip-8-mpp-session.md) Session actor (`0x0C`): a payer escrows CBY against a runner, the runner is paid by cumulative off-chain vouchers, and unspent deposit is refunded after a dispute window.

Write subcommands sign with the key found by [key auto-discovery](https://docs.cowboy.inc/cli-specs/key-auto-discovery.md). Each signs with a 500,000 cycle / 100,000 cell limit and the protocol default access limit, prints the transaction hash, and submits via `POST /submit`. Without `--json` a write returns on acceptance; with `--json` it waits up to 90 seconds for the transaction to commit and reports it only once committed (`transaction_failed` if it commits unsuccessfully, `receipt_pending` if it does not commit in time).

**Parent flags:**

| Flag | Default | Description |
| - | - | - |
| `--rpc-url` | Auto-discovered | RPC URL (auto-discovered from `.cowboy/config.json` if not provided) |

## Subcommands

### `cowboy session models`

List the models active inference runners serve, with how many runners serve each (`*` is a runner that serves any model). Counts only runners that run `llm` jobs, advertise the inference entitlement, and have a route-serving endpoint. Read-only; no private key.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--json` | `false` | Emit a versioned JSON response |

***

### `cowboy session open`

Open a new session, escrowing `max_amount` from the payer: for a model the chain assigns a runner to (`--model`, the usual way), or, as an advanced option, against a runner you name (`--runner`). Exactly one of `--model` and `--runner` is required.

**Behavior:**

1. Load the payer key and derive the payer address.
2. With `--model`: default `--expires-at` to the current height plus 2,592,000 blocks (30 days of 1-second blocks), default the session id to 32 random bytes, and submit `SessionOpenAssigned`; the chain assigns the runner when the transaction commits.
3. With `--runner`: compute the session id as `--session-id` if given, otherwise `keccak256(payer || runner || nonce || expires_at)` using the `--nonce` value as passed (before auto-fetch), and submit `SessionOpen`. The runner must be registered and not the payer, but need not serve a model.
4. Both use asset CBY, the given `max_amount`, and the price-advert digest (all zeros if omitted).
5. Print `session_id`, `payer`, then `runner` (with `--runner`) or `model`, any `exclude` and `signer` (with `--model`), then `max_amount` and `expires_at`. With `--json`, wait for commit and report the session id, assigned runner, its endpoint, deposit, expiry, and transaction hash.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--model` | None | Model to open an inference session for (at most 256 bytes; non-empty); the chain assigns a runner that serves it. Conflicts with `--runner` |
| `--runner` | None | Advanced: runner address the session will pay (hex). Requires `--expires-at`; conflicts with `--model` |
| `--max-amount` | Required | Maximum escrow, in CBY wei |
| `--expires-at` | Current height + 2,592,000 with `--model` | Block height at which the session expires (must be above current); required with `--runner` |
| `--session-id` | Derived | Pre-chosen 32-byte session id (hex) |
| `--price-advert-digest` | All zeros | keccak256 of the off-chain price advert (hex) |
| `--exclude` | None | With `--model`, a runner address the chain must not assign; repeatable, at most 8, no duplicates. Conflicts with `--runner` |
| `--signer` | This wallet | With `--model`, the address whose key signs this session's vouchers while this wallet pays (a sponsored session). Conflicts with `--runner` |
| `--private-key` | Auto-discovered | Payer private key file |
| `--nonce` | `0` (auto-fetch) | Transaction nonce |
| `--json` | `false` | Emit a versioned JSON response once the session is open |

**Example:**

```bash theme={null}
$ cowboy session open --runner 0x5e6F...A7B8 --max-amount 1000000000 --expires-at 20000
Transaction hash: 0xabc123...
session_id : 0x9f1c...
payer      : 0x7a3B...F92E
runner     : 0x5e6F...A7B8
max_amount : 1000000000 wei
expires_at : block 20000
```

***

### `cowboy session voucher`

Sign a voucher with the global `--private-key` and print it as JSON; nothing is sent. The output (or the `voucher` object of `--json`) is what `settle --voucher` accepts.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--session-id` | Required | Session id (hex, 32 B) |
| `--cumulative-amount` | Required | Voucher cumulative amount, in CBY wei |
| `--voucher-nonce` | Required | Voucher nonce; must strictly exceed the last on-chain nonce |
| `--voucher-expires-at` | Required | Voucher expiry block |
| `--usage-digest` | All zeros | 32-byte usage digest (hex) |
| `--private-key` | Auto-discovered | Key that signs the voucher |
| `--json` | `false` | Emit a versioned JSON response |

***

### `cowboy session deposit`

Top up an open session.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--session-id` | Required | Session id (hex, 32 B) |
| `--amount` | Required | Amount to add, in CBY wei |
| `--private-key` | Auto-discovered | Private key file |
| `--nonce` | `0` (auto-fetch) | Transaction nonce |
| `--json` | `false` | Emit a versioned JSON response once the deposit has committed |

***

### `cowboy session settle`

Submit `SessionSettle` with a voucher the session's signer signed elsewhere (`--voucher`), or sign one here with `--signer-key`.

**Behavior:**

1. With `--voucher`: parse the voucher object (inline JSON or `@FILE`, at most 64 KiB), check it matches `--session-id` if given, and sign the transaction with the global `--private-key`.
2. Otherwise: load the signer key (`--signer-key`) and, if given, a separate submitter key (`--private-key`); the submitter defaults to the signer. Sign the voucher's EIP-712 digest with the signer key over the Session actor domain.
3. Read the session and check the voucher recovers to the session's signer (its payer, unless opened with `--signer`) before anything is submitted.
4. Submit `SessionSettle { session_id, voucher }` signed by the submitter.
5. Print `session_id`, `signer` (voucher signer), `submitter` (tx signer), and the voucher's nonce, cumulative amount, and expiry.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--session-id` | Required unless `--voucher` | Session id (hex, 32 B); with `--voucher` it defaults to the voucher's and must match it |
| `--voucher` | None | A signed voucher object as `session voucher --json` returns it under `voucher`, inline or as `@FILE`. Conflicts with `--cumulative-amount`, `--voucher-nonce`, `--voucher-expires-at`, `--usage-digest`, and `--signer-key` |
| `--cumulative-amount` | Required unless `--voucher` | Voucher cumulative amount, in CBY wei |
| `--voucher-nonce` | Required unless `--voucher` | Voucher nonce; must strictly exceed the last on-chain nonce |
| `--voucher-expires-at` | Required unless `--voucher` | Voucher expiry block |
| `--usage-digest` | All zeros | 32-byte usage digest (hex) |
| `--signer-key` (alias `--payer-key`) | Auto-discovered | The session signer's key file, which signs the voucher |
| `--private-key` | `--signer-key` | Submitter key that signs the transaction |
| `--nonce` | `0` (auto-fetch) | Transaction nonce |
| `--json` | `false` | Emit a versioned JSON response once the settle has committed |

***

### `cowboy session close`

Payer-initiated close; the session enters its dispute window.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--session-id` | Required | Session id (hex, 32 B) |
| `--private-key` | Auto-discovered | Private key file |
| `--nonce` | `0` (auto-fetch) | Transaction nonce |
| `--json` | `false` | Emit a versioned JSON response once the close has committed |

***

### `cowboy session finalize`

Refund the unspent deposit after the dispute window expires.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--session-id` | Required | Session id (hex, 32 B) |
| `--private-key` | Auto-discovered | Private key file |
| `--nonce` | `0` (auto-fetch) | Transaction nonce |
| `--json` | `false` | Emit a versioned JSON response once the refund has committed |

***

### `cowboy session get`

Read on-chain session state by id. Read-only; no private key.

**Behavior:**

1. Compute the session storage key and `GET /actors/<session actor>/storage/value?key=<key>`.
2. A key the node does not hold fails with `session_not_found`; a node without the route fails with `rpc_failed`; a native route session's record fails with `session_unsupported`.
3. Otherwise print `session_id`, `payer`, `signer`, `runner`, `deposit`, `spent`, `max_amount`, `opened_at_block`, `expires_at_block`, `last_voucher_nonce`, and `status` (`Open`, `Closing (closed_at=N)`, `Disputed`, `Settled`, or `Refunded`), followed by the runner's `endpoint` when it has one.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--session-id` | Required | Session id (hex, 32 B) |
| `--json` | `false` | Emit a versioned JSON response |

## Edge Cases

* Amounts are in CBY wei (1 CBY = 10^9 wei), not CBY.
* With `--nonce 0` the transaction nonce is fetched from the account; the derived session id for `open --runner` still uses the literal `0`, so pass `--session-id` to control it explicitly.
* `settle` lets a different account submit the transaction than the one that signed the voucher; the voucher signature is always the session signer's (the payer, or the sponsor `open --signer` named), and a voucher signed by any other key is refused before submission.
* `get` fails when the session is not on chain or the node does not serve actor storage reads.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.