Tyche CLI

@tyche/cli is the orderbook CLI for Tyche and WTHRBook.

It is built around the actual backend API in ../orderbook and the signing model used in packages/dapp/services/wthrbook-orderbook.ts. This package focuses on the flows that exist today:

• health checks
• orderbook, positions, trades, and fee reads
• live SSE event streaming
• shared-address and settlement funding reads/writes
• tradable market discovery and market full-set minting
• signed order creation and submission
• signed cancel creation and submission
• admin fee management
• command and schema introspection for agents

Runtime configuration

Global flags:

• --api-url
• --chain-id
• --environment
• --rpc-url
• --ponder-url
• --settlement-address
• --usdc-address
• --fee-recipient
• --output auto|text|json|ndjson

Environment variables:

• TYCHE_API_URL
• TYCHE_CHAIN_ID
• TYCHE_ENVIRONMENT
• TYCHE_RPC_URL or BASE_RPC_URL
• TYCHE_PONDER_URL
• TYCHE_SETTLEMENT_ADDRESS
• TYCHE_USDC_ADDRESS
• TYCHE_PRIVATE_KEY

Signing and settlement write commands read the wallet key from TYCHE_PRIVATE_KEY. The CLI does not accept private keys on the argv surface.

When contract addresses or the order fee recipient are not passed explicitly, the CLI resolves them from @tyche/shared/addresses.json using the selected chain id (8453 = base, 84532 = baseSepolia). Settlement funding commands read the actual collateral token from TycheOrderSettlement.usdc() so they do not accidentally use the generic chain USDC address when the settlement was deployed against MockUSDC.

Ponder defaults are public endpoints, not local services:

• staging and development: https://ponder-wthrbook-staging.dclimate.net/
• production: https://ponder-wthrbook.dclimate.net/

Override with --ponder-url or TYCHE_PONDER_URL when testing a custom indexer.

Use tyche config inspect --output json to print the resolved non-secret runtime configuration for agents. It includes API, RPC, Ponder, settlement, USDC/collateral, and WTHRBookFeeRecipient values, and it does not require TYCHE_PRIVATE_KEY.

The CLI also falls back to the frontend env names used by packages/dapp:

• NEXT_PUBLIC_WTHRBOOK_API_URL
• NEXT_PUBLIC_PONDER_URL
• NEXT_PUBLIC_ENVIRONMENT

Command surface

• health
• orderbook list
• positions list
• trades list
• fees quote
• fees negotiated list|set|clear
• fees discount-tiers list|set|clear
• orders create|submit|submit-bulk
• cancels create|submit
• config inspect
• markets tradable|mint-full-set
• settlement addresses|balance|approve|deposit|withdraw
• stream
• describe
• schema list|get

Output contract

Non-streaming commands emit a stable JSON envelope in --output json mode:

{
  "ok": true,
  "command": "orderbook.list",
  "data": {},
  "meta": {
    "timestamp": "2026-04-23T12:00:00.000Z",
    "apiUrl": "http://127.0.0.1:3001"
  }
}

Errors use the matching envelope shape on stderr:

{
  "ok": false,
  "command": "orders.submit",
  "error": {
    "code": "api_error",
    "message": "invalid signature"
  }
}

stream emits one JSON object per line in --output ndjson mode.

Read commands are bounded by default. orderbook list, positions list, and trades list default to --limit 100 and accept --offset; JSON output includes the backend pageInfo metadata (limit, offset, nextOffset, hasNextPage).

orders submit-bulk --output json keeps the final JSON envelope on stdout and writes per-order progress events as JSON lines on stderr, so long batches can be monitored without corrupting the machine-readable result. Bulk submission defaults to --concurrency 2; orders from the same maker are still serialized to avoid backend submission locks. Add --summary to return aggregate counts and bounded failure samples instead of every per-order result. Add --failed-output-file ./failed-orders.json to write failed signed payloads as a retryable JSON array.

Exit codes

• 0: success
• 1: unexpected internal error
• 2: usage or validation error
• 3: runtime configuration error
• 4: API request or response error
• 5: admin auth error
• 6: signing error
• 7: chain/RPC transaction error

Examples

tyche health --output json
tyche config inspect --chain-id 84532 --output json
tyche orderbook list --pool-id 12 --limit 100 --offset 0 --output json
tyche positions list --maker 0xabc... --output json
tyche trades list --market-id 0xabc... --limit 25 --offset 0 --output json
tyche fees quote --maker 0xabc... --product-type COLLATERAL --output json
tyche orders create --product-type COLLATERAL --pool-id 12 --side BUY --shares 5 --limit-price 0.55 --output json
tyche orders submit --input-file ./order.json --output json
tyche orders submit-bulk --input-file ./orders.json --output json
tyche orders submit-bulk --input-file ./orders.json --summary --failed-output-file ./failed-orders.json --output json
tyche cancels create --order-hash 0xabc... --output json
tyche markets tradable --limit 25 --output json
tyche markets mint-full-set --market-id 0xabc... --amount 10 --approve --allowance-settle-ms 1000 --output json
tyche settlement addresses --chain-id 84532 --output json
tyche settlement balance --owner 0xabc... --output json
tyche settlement deposit --amount 25 --approve --output json
tyche settlement withdraw --amount 10 --output json
tyche stream --market-id 0xabc... --output ndjson
tyche describe orders.create --output json
tyche schema list --output json

orders submit and cancels submit accept either a bare signed payload or the full JSON envelope emitted by the matching create --output json command.

Buy orders spend the maker's internal settlement balance, not wallet USDC directly. Deposit USDC into TycheOrderSettlement before submitting tradable buy orders; active match locks temporarily reduce the withdrawable amount shown by settlement balance.