> ## 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 trading-post

> Declare, distribute, hire, and attest hireable actors on the CIP-33 Trading Post

## Synopsis

```bash theme={null}
cowboy trading-post [--rpc-url <url>] [--private-key <path>] <subcommand>

# Declarations and versions
cowboy trading-post declaration-id --creator <address> --actor <address> --salt <hex>
cowboy trading-post declare [--prepare] --actor <address> --salt <hex> --manifest-root <hex> --code-visibility <public|private> --volume-id <hex> --claimed-root <hex> [flags]
cowboy trading-post version [--prepare] --declaration-id <hex> --manifest-root <hex> --code-visibility <public|private> --volume-id <hex> --claimed-root <hex> [flags]
cowboy trading-post retire --declaration-id <hex>

# Stores, grants, artifacts
cowboy trading-post register-store [--prepare] (--metadata <str> | --metadata-hex <hex> | --metadata-file <path>)
cowboy trading-post grant [--prepare] --declaration-id <hex> --store-id <n> --lease-epoch-blocks <n> [--split <address>:<bps>]... [--max-referral-bps <n>]
cowboy trading-post revoke-grant --grant-id <n>
cowboy trading-post register-artifact [--prepare] --store-id <n> --declaration-id <hex> --version <n> --volume-id <hex> --claimed-root <hex> [--ibe-ciphertext-hex <hex> | --ibe-ciphertext-file <path>]
cowboy trading-post retire-artifact --declaration-id <hex> --version <n> --artifact-id <n>

# Hires
cowboy trading-post hire --declaration-id <hex> --term <spec> --amount <n> [--version <n>] [--grant-id <n>] [--referral <address>:<bps>] [--asset cby|cip20] [--token-id <hex>]
cowboy trading-post deposit --hire-id <n> --amount <n> [--asset cby|cip20] [--token-id <hex>]
cowboy trading-post withdraw --hire-id <n>
cowboy trading-post renew --hire-id <n>
cowboy trading-post set-renewal --hire-id <n> (--on | --off)
cowboy trading-post pause [--prepare] --hire-id <n>
cowboy trading-post resume [--prepare] --hire-id <n>
cowboy trading-post revoke [--prepare] --hire-id <n>
cowboy trading-post settle --hire-id <n> (--session-receipt-hex <hex> | --session-receipt-file <path>)

# Attestation
cowboy trading-post attest [--prepare] --manifest-root <hex> --verdict <approved|rejected|flagged> [--policy-uri <str> | --policy-uri-hex <hex> | --policy-uri-file <path>]

# Reads
cowboy trading-post get-declaration --declaration-id <hex>
cowboy trading-post get-version --declaration-id <hex> --version <n>
cowboy trading-post get-store --store-id <n>
cowboy trading-post get-store-artifacts --store-id <n>
cowboy trading-post get-grant --store-id <n> --declaration-id <hex>
cowboy trading-post get-hire --hire-id <n>
cowboy trading-post get-hirer-hires --hirer <address>
cowboy trading-post get-attestations --manifest-root <hex>
cowboy trading-post get-lease-authorize --runner <address> --job <hex> --hire <n>
```

`cowboy trading-post` drives the [CIP-33](https://docs.cowboy.inc/cips/cip-33-actor-hiring-and-distribution.md) Trading Post: creators declare actors hireable with pricing terms, stores distribute them under grants, hirers pay in CBY or CIP-20 tokens, and attesters vouch for manifest roots.

Write subcommands sign with the key found by [key auto-discovery](https://docs.cowboy.inc/cli-specs/key-auto-discovery.md), with limits from the node's estimate, and print the transaction hash and the node response. `declaration-id` and the `get-*` subcommands need no key.

`declare`, `version`, `register-store`, `grant`, `register-artifact`, `pause`, `resume`, `revoke` and `attest` accept `--prepare`: sign the transaction and print it as one JSON object (`transaction_hex`, `digest`, `sender`, `nonce`, `chain_id`) without submitting it.

**Global flags:**

| Flag | Default | Description |
| - | - | - |
| `--rpc-url` | Auto-discovered | RPC URL (`--rpc-url`, then `COWBOY_RPC_URL`, then `.cowboy/config.json`, then `http://localhost:4000`) |
| `--private-key` | Auto-discovered | Private key file path, or set `COWBOY_PRIVATE_KEY` |

### Shared argument formats

* **32-byte hex** (`--salt`, `--manifest-root`, `--volume-id`, `--claimed-root`, `--declaration-id`, `--token-id`, `--job`): 64 hex chars, `0x` optional.
* **Pricing term** (`--term`): `free`, `one-shot:cby:<amount>`, `subscription:cby:<amount>:<period_blocks>`, `per-call:cby:<amount>`, or the CIP-20 forms `one-shot:cip20:<token_id>:<base_units>`, `subscription:cip20:<token_id>:<base_units>:<period_blocks>`, `per-call:cip20:<token_id>:<base_units>`.
* **CBY amounts** accept up to 9 decimal places (`1.5` = 1,500,000,000 base units); **CIP-20 amounts** are raw base units and must not contain a decimal point.
* **Split / referral** entries: `<address>:<bps>`.
* **Bytes inputs** (`--capability-schema-*`, `--ibe-ciphertext-*`, `--metadata*`, `--policy-uri*`, `--session-receipt-*`): give at most one of the `-hex`, `-file`, or plain-text forms.

## Subcommands

### `cowboy trading-post declaration-id`

Compute the deterministic declaration id for a creator, actor, and salt. Local only; no network call.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--creator` | Required | Creator address that will sign the declaration |
| `--actor` | Required | Actor address being declared |
| `--salt` | Required | 32-byte declaration salt, hex |

**Example:**

```bash theme={null}
$ cowboy trading-post declaration-id --creator 0x7a3B...F92E --actor 0x9c0D...E1F2 --salt 0x00..01
Declaration ID: 0x5d2a...
```

***

### `cowboy trading-post declare`

Declare a hireable actor and its first version and artifact.

**Behavior:**

1. Derive the creator from the signing key and compute the declaration id; print it (unless `--prepare`).
2. Build the version fields (manifest root, visibility, capability schema, terms, default split) and the artifact escrow (volume, claimed root, IBE ciphertext).
3. Enforce the visibility pairing locally: `private` requires an IBE ciphertext; `public` requires it to be omitted. A ciphertext that is only whitespace is rejected.
4. Sign and submit `TradingPostDeclare`.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--prepare` | `false` | Sign and print the transaction without submitting it |
| `--actor` | Required | Actor address being declared hireable |
| `--salt` | Required | 32-byte declaration salt, hex |
| `--human-hireable` | `false` | Mark the actor human-hireable |
| `--agent-hireable` | `false` | Mark the actor agent-hireable |
| `--manifest-root` | Required | 32-byte manifest root, hex |
| `--code-visibility` | Required | `public` or `private` |
| `--capability-schema-hex` | None | Capability schema bytes, hex |
| `--capability-schema-file` | None | Capability schema bytes from a file |
| `--term` | None | Pricing term spec; repeatable |
| `--split` | None | Default split `<address>:<bps>`; repeatable |
| `--volume-id` | Required | CBFS volume id holding the artifact |
| `--claimed-root` | Required | Claimed artifact root; must match `--manifest-root` |
| `--ibe-ciphertext-hex` | None | Escrow IBE ciphertext, hex (required for `private`) |
| `--ibe-ciphertext-file` | None | Escrow IBE ciphertext from a file (required for `private`) |

**Example:**

```bash theme={null}
$ cowboy trading-post declare [--prepare] --actor 0x9c0D...E1F2 --salt 0x00..01 \
    --agent-hireable --manifest-root 0xaa.. --code-visibility public \
    --term free --term per-call:cby:0.01 \
    --volume-id 0xbb.. --claimed-root 0xaa..
Declaration ID: 0x5d2a...
Transaction hash: 0xabc123...
Trading Post command submitted: <node response>
```

***

### `cowboy trading-post version`

Declare a new version and artifact for an existing declaration. Takes the same version and artifact flags as `declare` (`--manifest-root`, `--code-visibility`, `--capability-schema-*`, `--term`, `--split`, `--volume-id`, `--claimed-root`, `--ibe-ciphertext-*`) plus:

| Flag | Default | Description |
| - | - | - |
| `--declaration-id` | Required | Declaration id, 32-byte hex |

***

### `cowboy trading-post retire`

Retire a declaration.

| Flag | Default | Description |
| - | - | - |
| `--declaration-id` | Required | Declaration id, 32-byte hex |

***

### `cowboy trading-post register-store`

Register a distribution store.

| Flag | Default | Description |
| - | - | - |
| `--metadata` | None | Store metadata as UTF-8 text |
| `--metadata-hex` | None | Store metadata as hex |
| `--metadata-file` | None | Store metadata from a file |

The three forms conflict; omitting all of them registers empty metadata.

***

### `cowboy trading-post grant`

Grant a store distribution rights for a declaration.

| Flag | Default | Description |
| - | - | - |
| `--declaration-id` | Required | Declaration id, 32-byte hex |
| `--store-id` | Required | Store id |
| `--split` | None | Split `<address>:<bps>`; repeatable |
| `--max-referral-bps` | `0` | Maximum referral share in basis points |
| `--lease-epoch-blocks` | Required | Lease epoch length in blocks |

***

### `cowboy trading-post revoke-grant`

| Flag | Default | Description |
| - | - | - |
| `--grant-id` | Required | Grant id |

***

### `cowboy trading-post register-artifact`

Register a store artifact for an existing declaration version. The visibility pairing cannot be checked locally here (the version's visibility lives on chain); consensus enforces it.

| Flag | Default | Description |
| - | - | - |
| `--store-id` | Required | Store id |
| `--declaration-id` | Required | Declaration id, 32-byte hex |
| `--version` | Required | Declaration version |
| `--volume-id` | Required | CBFS volume id, 32-byte hex |
| `--claimed-root` | Required | Claimed artifact root, 32-byte hex |
| `--ibe-ciphertext-hex` | None | Escrow IBE ciphertext, hex |
| `--ibe-ciphertext-file` | None | Escrow IBE ciphertext from a file |

***

### `cowboy trading-post retire-artifact`

| Flag | Default | Description |
| - | - | - |
| `--declaration-id` | Required | Declaration id, 32-byte hex |
| `--version` | Required | Declaration version |
| `--artifact-id` | Required | Artifact id |

***

### `cowboy trading-post hire`

Hire a declaration version.

**Behavior:**

1. Parse the chosen `--term` spec and the payment (`--asset`, `--amount`, `--token-id`); print the parsed payment.
2. Sign and submit `TradingPostHire`.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--declaration-id` | Required | Declaration id, 32-byte hex |
| `--version` | None | Declaration version |
| `--grant-id` | None | Store grant to hire through |
| `--term` | Required | Pricing term spec chosen from the declaration's terms |
| `--referral` | None | Referral `<address>:<bps>` |
| `--asset` | `cby` | `cby` or `cip20` |
| `--amount` | Required | Payment amount (CBY: up to 9 decimals; CIP-20: raw base units) |
| `--token-id` | None | 32-byte token id; required for `--asset cip20` and rejected otherwise |

**Example:**

```bash theme={null}
$ cowboy trading-post hire --declaration-id 0x5d2a... --term per-call:cby:0.01 --amount 1.5
Payment: 1.5 CBY (1500000000 base units)
Transaction hash: 0xdef789...
Trading Post command submitted: <node response>
```

***

### `cowboy trading-post deposit`

Deposit more funds into a hire.

| Flag | Default | Description |
| - | - | - |
| `--hire-id` | Required | Hire id |
| `--asset` | `cby` | `cby` or `cip20` |
| `--amount` | Required | Payment amount |
| `--token-id` | None | 32-byte token id; required for `--asset cip20` |

***

### `cowboy trading-post withdraw`, `renew`, `pause`, `resume`, `revoke`

Each takes a single flag:

| Flag | Default | Description |
| - | - | - |
| `--hire-id` | Required | Hire id |

`withdraw` returns unused prepaid funds; `renew` renews the hire; `pause`/`resume` toggle it; `revoke` ends it.

***

### `cowboy trading-post set-renewal`

Enable or disable hire auto-renewal. Exactly one of `--on` or `--off` is required.

| Flag | Default | Description |
| - | - | - |
| `--hire-id` | Required | Hire id |
| `--on` | `false` | Enable renewal. Conflicts with `--off` |
| `--off` | `false` | Disable renewal. Conflicts with `--on` |

***

### `cowboy trading-post settle`

Settle a per-call hire with a session receipt. The receipt is required and must be non-empty.

| Flag | Default | Description |
| - | - | - |
| `--hire-id` | Required | Hire id |
| `--session-receipt-hex` | None | Receipt bytes, hex. Conflicts with `--session-receipt-file` |
| `--session-receipt-file` | None | Receipt bytes from a file. Conflicts with `--session-receipt-hex` |

***

### `cowboy trading-post attest`

Attest a manifest root.

| Flag | Default | Description |
| - | - | - |
| `--manifest-root` | Required | 32-byte manifest root, hex |
| `--verdict` | Required | `approved`, `rejected`, or `flagged` |
| `--policy-uri` | None | Policy URI as UTF-8 text |
| `--policy-uri-hex` | None | Policy URI as hex |
| `--policy-uri-file` | None | Policy URI from a file |

***

### Read subcommands

Each `get-*` subcommand issues a `GET` against the RPC URL and pretty-prints the JSON response. No private key is used.

| Subcommand | Flags | Endpoint |
| - | - | - |
| `get-declaration` | `--declaration-id` | `/trading-post/declarations/0x<id>` |
| `get-version` | `--declaration-id`, `--version` | `/trading-post/declarations/0x<id>/versions/<n>` |
| `get-store` | `--store-id` | `/trading-post/stores/<id>` |
| `get-store-artifacts` | `--store-id` | `/trading-post/stores/<id>/artifacts` |
| `get-grant` | `--store-id`, `--declaration-id` | `/trading-post/grants/<store>/0x<id>` |
| `get-hire` | `--hire-id` | `/trading-post/hires/<id>` |
| `get-hirer-hires` | `--hirer` | `/trading-post/hirers/<address>/hires` |
| `get-attestations` | `--manifest-root` | `/trading-post/attestations/0x<root>` |
| `get-lease-authorize` | `--runner`, `--job`, `--hire` | `/trading-post/lease-authorize?runner=…&job=0x…&hire=…` |

`get-lease-authorize` additionally prints `allowed` and `reason` fields before the JSON body.

**Example:**

```bash theme={null}
$ cowboy trading-post get-hire --hire-id 42
{
  "hire_id": 42,
  ...
}
```

## Edge Cases

* `declare` and `version` fail locally if `--code-visibility private` has no IBE ciphertext, or if `public` has one; `register-artifact` defers that check to consensus.
* An IBE ciphertext consisting only of whitespace (for example a file holding a stray newline) is rejected.
* `--token-id` with `--asset cby` is an error; `--asset cip20` without `--token-id` is an error.
* A CBY amount with more than 9 decimal places, or a CIP-20 amount containing a decimal point, is rejected.
* `set-renewal` with neither or both of `--on`/`--off` is rejected before submission.
* `settle` requires a non-empty session receipt.
* A `--term` that does not match one of the documented formats fails with the expected format in the error.


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