# BIE Open Platform — llms.txt (for AI agents)

> BIE is a zero-gas trading venue (spot / perpetuals / swap / prediction / insurance).
> This file tells an AI agent how to trade on BIE on behalf of its principal (the human).
> Base site: https://bie.ai · Terminal: https://app.bie.ai

## Start here
If you are an AI agent and want to trade on BIE, read https://bie.ai/agent.md — it is the
machine-readable version of the human page at https://bie.ai/agent, and contains a copy-paste
runnable path from zero to a first simulated fill. Everything below is reference detail.
- Skill (one-line install): https://bie.ai/SKILL.md — tell your agent runtime "Read https://bie.ai/SKILL.md and set up bie".
  The Skill carries the same tool list, the same write-tool protocol and the same session-policy fields as this file.

## Zero-to-first-fill without any human step
1. Connect to the hosted MCP endpoint (below). No auth needed to list tools.
2. Call tool bie_connect_paper (no arguments) — it returns a PAPER session token. No login, no human.
3. Send that token as Authorization: Bearer <token> and call any write tool — you get an ORDER PREVIEW.
4. Call bie_confirm_action with the preview's action_id + args_sha256 — you get a simulated fill.
   PAPER means simulated: no real funds move. Say so when you report back to your principal.

## Honest status (updated 2026-09-05)
- live: 26 tools + confirm valve. Two ways in — hosted MCP endpoint (below) or local stdio server (npm: bie-cli). Public market data needs no auth.
- live: Skill — https://bie.ai/SKILL.md (one-line install, see Start here).
- live: per-session limits — every session carries a policy (markets / max_order_notional / max_total_notional / expires_at); read it with tool bie_session_limits or GET /agent/policy; tighten your own with tool bie_tighten_limits or POST /agent/policy (reduce-only).
- live: CLI on npm — npm i -g bie-cli (0.3.1 ships --describe, session-limit KeyCard and error envelopes; bins: bie / bie-mcp; "bie mcp" = local stdio MCP server). Compare bie --version with GET /healthz.min_cli_version.
- preview: conversational trading via bie-agent-service (connect-code -> session token -> chat/confirm flow, running in staging)
- planned: agent marketplace

## Hosted MCP endpoint (JSON-RPC 2.0, stateless Streamable HTTP)
- URL (live now): https://bie-brand.pages.dev/api/mcp
- URL (production domain, coming soon): https://bie.ai/api/mcp — use the live URL above until this one answers tools/list
- Public market tools: no auth. Account/write tools: header Authorization: Bearer <session token>.
- methods: initialize / tools/list / tools/call. Write tools return an ORDER PREVIEW (never execute);
  show it to your principal, then on approval call tool bie_confirm_action{conv_id, action_id, args_sha256}.
- tools/list returns MCP annotations per tool (readOnlyHint / destructiveHint / idempotentHint / openWorldHint).
  The [tier · risk] tag on each tool line below is derived from those annotations:
  destructive = opens exposure or spends; reducing = closes / cancels / adjusts risk (still goes through the valve); readonly = no side effect.
- Add to Claude Code:  claude mcp add bie --transport http https://bie-brand.pages.dev/api/mcp --header "Authorization: Bearer <token>"

## Safety model (why your principal can trust this)
1. NEVER-WITHDRAW (agent tool surface): agent sessions have no withdraw/transfer-out tools. Not a policy — the tool surface does not contain them.
2. CONFIRM VALVE: every write tool (place order / open position / swap / bet / toggle insurance) requires a one-time confirm token,
   bound to the sha256 of the exact arguments previewed to the human. Tampered args = rejected. TTL 120s, single use.
3. SCOPES: readonly | paper (simulated fills, recommended default) | live-confirm (real orders, each confirmed by the human).
4. KILL SWITCH: POST /agent/revoke invalidates the session token immediately. Every call goes into the append-only audit trail.
5. Zero gas: BIE chain charges no gas on trade actions — high-frequency agent behavior is economically viable.
6. SESSION POLICY: markets / max_order_notional / max_total_notional / expires_at, effective = min(session, ceiling); agent can only tighten (tool bie_tighten_limits / POST /agent/policy); loosening needs the principal's login in the terminal.
   The default ceiling is published at GET /healthz.ceiling; the value in force for your session is GET /agent/policy (or tool bie_session_limits). No number here — it changes per session.

## Write-tool protocol (verbatim, also in every write tool's description)
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.

## Connect flow (agent playbook)
1. Ask your principal to sign in at https://bie.ai/agent and grab a one-time code (looks like BIE-XXXXXXXX, valid 5 min).
2. Redeem it yourself: POST {AGENT_SERVICE}/connect/redeem {"code":"BIE-XXXXXXXX"} -> { token, scope, keycard }. The keycard carries the session policy.
3. Chat: POST {AGENT_SERVICE}/agent/chat (SSE) with Authorization: Bearer <token>, body {"conv_id":"...","message":"..."}.
4. When you receive a "preview" event, show it to your principal; on their approval call POST /agent/confirm
   {"conv_id":..,"action_id":..,"args_sha256":..} and relay the receipt.
5. Policy: GET /agent/policy reads it; POST /agent/policy tightens it (any field, only towards stricter);
   POST /agent/policy/loosen is for the principal only and needs their login credential (X-Login-Token) — you cannot call it.
NOTE: agent-service base URL (live now): https://bie-brand.pages.dev/api — production domain bie.ai/api once its reverse proxy is live.

## Errors (one envelope everywhere)
{ error, error_code, hint?, recoverable } — recoverable tells you what to do next:
- reauth: token expired/revoked → ask your principal for a new code
- backoff: rate limited / upstream busy → wait and retry the same call
- fix_params: your arguments were rejected (schema, market, or policy_denied) → change them and preview again
- confirm_required: this action needs bie_confirm_action with the previewed args_sha256
- none: not recoverable from your side → report to your principal

## Tools by capability (26 tools; [public]=no auth, [auth-read]=own data, [write]=confirm valve; · destructive|reducing|readonly from annotations)
### Market Data / 行情
- bie_spot_markets [public · readonly] — List all BIE spot markets with live ticker (mark/ask/bid), precision, fees, status. No auth.
- bie_spot_orderbook [public · readonly] — Get BIE spot order book (simulated maker quote in transition; asks/bids). No auth.
- bie_spot_klines [public · readonly] — Get BIE spot candlesticks (reference feed). No auth.
- bie_spot_recent_trades [public · readonly] — Get recent BIE spot trades. No auth.
- bie_perp_markets [public · readonly] — List BIE perpetual markets (symbol like BTCUSDT, leverage, precision). No auth.
- bie_perp_funding_rate [public · readonly] — Get funding rate for a perp symbol (e.g. BTCUSDT). No auth.

### Account / 账户
- bie_my_balances [auth-read · readonly] — Get my spot balances (available/frozen per currency). Requires BIE_TOKEN.
- bie_my_holdings [auth-read · readonly] — Get my spot holdings with cost/valuation/unrealized PnL. Requires BIE_TOKEN.
- bie_my_open_orders [auth-read · readonly] — Get my open (non-terminal) spot orders. Requires BIE_TOKEN.
- bie_perp_positions [auth-read · readonly] — Get my open perp positions. Requires BIE_TOKEN.

### Trading / 交易
- bie_spot_place_order [write · destructive] — Place a BIE spot order. Requires BIE_TOKEN. client_order_id is auto-generated (idempotent). RULES: market BUY → set quote_amount (USDT you pay). market SELL / any LIMIT → set quantity (base coin amount). LIMIT → also set price.
- bie_spot_cancel_order [write · reducing] — Cancel an open limit spot order by order_no. Requires BIE_TOKEN.
- bie_perp_open [write · destructive] — Open a BIE perp position IMMEDIATELY at market price. For limit / "buy when price drops to X" / conditional orders use bie_perp_place_order instead. Requires BIE_TOKEN. symbol e.g. BTCUSDT; size in base coin; leverage 1-x; margin_mode cross|isolated. Zero-gas.
- bie_perp_place_order [write · destructive] — Place a RESTING perp order on BIE — limit or conditional (trigger). Use for "buy when it drops to X", "sell at Y", limit entries, conditional exits. For an immediate market entry use bie_perp_open. Requires BIE_TOKEN. order_type=limit: rests at price (maker). order_type=conditional: arms at trigger_price; trigger_when=fall fires when mark price drops to it, rise fires when it climbs to it; with price it executes as a limit at that price, without price as market. action=open (default) opens a new position and freezes margin now; action=close reduces an existing position and needs position_id (from bie_perp_positions).
- bie_perp_set_tpsl [write · reducing] — Set or change take-profit / stop-loss on an EXISTING perp position (position_id from bie_perp_positions). Omit a side to leave it unchanged; pass "0" to clear it. Requires BIE_TOKEN.
- bie_perp_close [write · reducing] — Close a perp position by position_id (optional partial size). Requires BIE_TOKEN.
- bie_perp_close_all [write · reducing] — Close ALL my perp positions. Requires BIE_TOKEN.

### Swap / 闪兑
- bie_swap_config [public · readonly] — Get BIE swap config (USDT↔BIE rate/limits). No auth.
- bie_swap_execute [write · destructive] — Execute a USDT↔BIE swap. Requires BIE_TOKEN. direction per swap_config; amount as string.

### Prediction / 预测市场
- bie_prediction_events [public · readonly] — List BIE prediction (world-cup) events with markets/odds. No auth.
- bie_prediction_champions [public · readonly] — List champion (outright) markets. No auth.
- bie_prediction_my_bets [auth-read · readonly] — List my prediction bets. Requires BIE_TOKEN.
- bie_prediction_place_bet [write · destructive] — Place a prediction bet. Requires BIE_TOKEN. idempotency_key auto-generated. expected_odds = slippage guard (bet rejected if odds move past it).

### Insurance / 保险
- bie_insurance_status [auth-read · readonly] — My liquidation-protection (FloatSafe) on/off state. Requires BIE_TOKEN.
- bie_insurance_fee_info [auth-read · readonly] — FloatSafe fee info + pool overview. Requires BIE_TOKEN.
- bie_insurance_toggle [write · destructive] — Toggle my FloatSafe liquidation protection on/off. Requires BIE_TOKEN.

## Machine-readable
- OpenAPI for agent-service HTTP surface: https://bie.ai/openapi.json
- This file in Markdown for the human-facing page: https://bie.ai/agent.md
- Skill: https://bie.ai/SKILL.md
- This page's site is a thin client; the runtime is the product.

## Access
Open globally. On-chain access is borderless by design.