bie — BIE trading CLI + MCP server

Trade on BIE from a terminal, a script, or any AI agent. One package, two entry points:

• bie — command line for humans and scripts. Five groups: connect · agent · trade · market · watch.
• bie mcp (alias bie-mcp) — local MCP server over stdio for Claude Code, Claude Desktop, Cursor, Codex and any MCP client. No install needed if you prefer the hosted endpoint (see below).

Every write goes preview → confirm. The confirm step is bound to a hash of the exact parameters that were previewed; the hosted service enforces it in front of the exchange API, and the local stdio server enforces the same valve in-process.

Install

npm i -g bie-cli
bie --help
bie --describe          # machine-readable command surface (JSON)

Node 18+. Zero native dependencies.

Two steps to a first (simulated) order

bie connect demo                                                        # opens a PAPER session — simulated funds, no login
bie agent ask "buy 50 USDT of BTC" --pair BTC-USDT --instrument spot    # returns an ORDER PREVIEW, exit code 4
bie trade confirm <action_id> --sha <args_sha256> --conv <conv_id>

--instrument spot must be passed explicitly — the default instrument is perpetual with 3x leverage.

bie connect demo is a paper session: previews and receipts are marked MODE: PAPER, nothing real moves. To trade a real account, sign in to the BIE trading terminal, open My Agent → CLI access, generate a one-time code and run bie connect login.

Give it to your AI agent (MCP)

Hosted endpoint — nothing to install. Public market data needs no auth; account and order tools need a session token from the trading terminal.

# Claude Code
claude mcp add bie --transport http <hosted MCP URL>
claude mcp add bie --transport http <hosted MCP URL> --header "Authorization: Bearer <session token>"

The current hosted URL, plus ready-made snippets for Claude Desktop, Cursor, Codex and curl, are kept in one place: https://bie-brand.pages.dev/build/mcp (the production domain bie.ai takes over once live; the page always shows the URL that answers today).

Local stdio server (runs on your machine, talks to BIE directly with your BIE_TOKEN):

// Claude Desktop / .mcp.json / .cursor/mcp.json
{
  "mcpServers": {
    "bie": {
      "command": "bie",
      "args": ["mcp"],
      "env": { "BIE_TOKEN": "<session token — leave out for read-only market data>" }
    }
  }
}

tools/list carries MCP tool annotations (readOnlyHint / destructiveHint / idempotentHint / openWorldHint) on every tool. Write tools return a preview with action_id + args_sha256; bie_confirm_action executes it (single use, 120 s). Their descriptions end with the confirm protocol sentence (below).

Skill. A self-contained SKILL.md for agent runtimes is served at https://bie.ai/SKILL.md (mirror: https://bie-brand.pages.dev/SKILL.md) and lives in the repository at skills/bie/SKILL.md; .claude-plugin/, .codex-plugin/, .cursor-plugin/ and openclaw.plugin.json manifests point at it.

Agents: read AGENTS.md — it is written for you.

Command groups

| group | what | examples | |---|---|---| | connect | identity & authorization | login · demo · keycard (prints the session policy, ceiling, spent, remaining) · status · revoke · logout | | agent | natural-language trading (core) | ask "buy 100u" --pair BTC-USDT --instrument spot [--max-notional 200] · conversations · new | | trade | deterministic orders | open / close / buy / sell · confirm <id> --sha · positions · orders | | market | read-only market data | price BTC · funding BTCUSDT · depth BTC · list [--cap perp] | | watch | supervision | audit [--conv id] [--follow] |

Global flags: --format json · --yes (direct-mode writes only) · --no-input · --base <url> · --max-notional <usdt> · --describe · --version. Expert escape hatch: bie <tool_name> runs any registry tool directly (bie tools lists them).

--describe

bie --describe prints one JSON document generated from the same registry the CLI runs on: the five groups with their subcommands, global flags, the exit-code table, and all 26 tools with tier, capability, annotations and parameter schema. bie <group> --describe prints just that group and the tools it maps to. --format json compacts it to one line.

--max-notional <usdt> (session mode)

A client-side cap on the notional of a single order. bie agent ask sends it as context.max_notional; the server applies min(session policy, your cap). For bie trade open/buy/sell/close the CLI compares the cap against the notional in the returned preview and refuses to confirm (exit 3) if the preview exceeds it. Direct mode (BIE_TOKEN) ignores the flag and says so on stderr. It can only tighten limits; loosening happens in the trading terminal.

Exit codes (machine-checkable)

| code | meaning | |---|---| | 0 | success | | 1 | runtime / network / upstream error; confirm expired or replayed; rate limited (retry with backoff) | | 2 | usage error (bad arguments, unknown command; error_code=invalid_args) | | 3 | unauthenticated / revoked / out of scope / policy or risk denied / CLI below min_cli_version | | 4 | order preview issued, awaiting confirm |

With no TTY, every write returns a preview and exit 4 — it never hangs waiting for input.

Error envelope → exit code

The service returns errors as { error, error_code, hint?, recoverable } (REST) or as a JSON string in the MCP isError text. The CLI maps recoverable to exit codes and prints hint on stderr:

| recoverable | error_code | exit | |---|---|---| | reauth | auth_required, live_unverified | 3 | | fix_params | invalid_args | 2 | | fix_params | policy_denied, risk_denied, confirm_rejected, unknown_tool | 3 | | backoff | rate_limited, upstream_error | 1 (stderr suggests retrying) | | confirm_required | — | 4 | | none | readonly_scope | 3 | | none | paper_no_account | 1 |

Responses without envelope fields keep the previous behaviour (401/403 → 3, other non-2xx → 1).

Version gate

At most once per 24 h the CLI reads GET <base>/healthz. If the response carries min_cli_version and the local version is lower, every command except --help / --version / --describe exits 3 with npm i -g bie-cli@latest on stderr. Network failures are cached for 1 h and let the command through. Cache: ~/.bie/version-check.json; BIE_SKIP_VERSION_GATE=1 disables the check.

Safety model — mechanisms

• Preview → confirm. A write call returns a preview with action_id + args_sha256; nothing executes. Confirm is single-use, expires after 120 s, and is rejected when the arguments differ from the preview.
• MODE at the top of every preview and receipt. PAPER (simulated), DRY-RUN, or LIVE.
• Tool surface without withdrawal. The registry contains no withdraw or transfer-out tool; MCP tools/list and bie --describe show the complete list.
• Scoped sessions with a policy. readonly · paper · live-confirm; each session carries markets, max_order_notional, max_total_notional, expires_at. bie connect keycard and the MCP tool bie_session_limits read the effective values and what remains; bie connect tighten and the MCP tool bie_tighten_limits tighten them (reduce-only). Clients can tighten (--max-notional); loosening is done by the principal in the terminal. bie connect revoke invalidates the session immediately.
• Append-only audit. bie watch audit replays what an agent did in the session.
• Schema-validated writes. Malformed orders are rejected before a request leaves your machine.
• Machine-readable risk annotations. Every tool carries MCP annotations, set per tool by hand (closing or cancelling is a write but not destructive; opening exposure is).

Write-tool confirm protocol

Every write tool's description ends with this sentence — the CLI, the MCP servers, the Skill and the docs all print the same constant (CONFIRM_PROTOCOL in src/tools.ts):

This call moves real funds in a live session (simulated funds in a PAPER session). It only returns a PREVIEW bound to args_sha256 — nothing executes. Show the full preview to your principal, wait for their explicit approval, then call bie_confirm_action with the same args_sha256. Changing any field invalidates the token. Never confirm in the same turn on your own.

Environment

| var | purpose | |---|---| | BIE_TOKEN | session token for account / order tools in bie mcp and direct mode; leave unset for public market data | | BIE_API_BASE | override the exchange API base (advanced) | | BIE_AGENT_BASE | agent-service base (same as --base) | | BIE_AGENT_TOKEN | session token without a credentials file | | BIE_SKIP_VERSION_GATE | set to skip the healthz version check |

Links

• CLI page & install: https://bie-brand.pages.dev/build/cli
• MCP endpoint & client snippets: https://bie-brand.pages.dev/build/mcp
• Skill for agent runtimes: https://bie.ai/SKILL.md
• Authorization flow: https://bie-brand.pages.dev/build/connect
• Trading terminal (issue tokens under My Agent): https://bie-app.pages.dev/agents