bgc — the agent-native CLI for Bitget

@bitget-ai/bitget-agent-cli

The shell surface of the Bitget Agent Hub — an agent-first command line for the Bitget Unified Trading Account (UTA / v3) API.

Most CLIs are built for humans and merely tolerate automation. bgc is built the other way around: every design choice optimizes for an AI assistant driving it from a shell (Claude Code, Codex CLI, OpenClaw), with a human reading the result. A small set of intent verbs, a self-describing surface the agent explores at runtime, and deterministic write-safety that makes it safe to hand the keys to an autonomous agent.

npm install -g @bitget-ai/bitget-agent-cli

The binary is bgc.

Why npm install -g and not npx? bgc is a persistent CLI — your AI assistant calls it dozens of times per session, so you want it on $PATH with zero per-call overhead. The other Bitget AI packages (@bitget-ai/bitget-agent-skill, @bitget-ai/bitget-signal, @bitget-ai/bitget-agent-mcp, @bitget-ai/bitget-agent-installer) are one-shot or subprocess-launched, so they use npx.

Prerequisites: Node.js ≥ 20. A Bitget API key, secret, and passphrase (create one) — only for private (account / trade) calls; market data is public.

Why agent-native?

| What an AI agent needs | How bgc answers it | |---|---| | Learn the API at runtime — an LLM can't read your docs, and a 100-operation catalog won't fit in its context | Progressive disclosure via discover: drill domains → verbs → actions → exact params, loading only the slice the task needs | | A surface it can reason about | 14 intent verbs (order, position, market…) map to what you want to do; the 100+ raw operations stay one raw / --full away | | Calls it can assemble without guessing | Every parameter's type, enum, auth, and read/write flag is queryable live — no hand-maintained schema to drift from the SDK | | Safety when running unattended | Deterministic gates — --dry-run, --read-only, --confirm, --paper-trading are pure flags, no interactive prompts | | Output a program can parse | Unix-clean I/O — JSON result on stdout (exit 0), structured error on stderr (exit 1); pipe to jq, branch on the exit code |

The rest of this README expands on each. The first one is the heart of it.

Progressive disclosure — the core idea

An AI agent has a finite context window. Pre-loading every Bitget operation and its parameters wastes that budget and goes stale the moment the API changes. bgc instead exposes a self-describing surface the agent walks top-down, paying only for what it's about to use:

bgc discover                               →  7 domains          market, trade, account, funds, subaccount, loan, tax
bgc discover --domain trade                →  3 verbs            order, position, strategy_order
bgc discover --tool order                  → 10 actions          place, cancel, cancelAll, open, detail, history, …
bgc discover --tool order --action place   →  the exact contract  required + optional params · types · enums · auth · read/write

The last rung is the payoff — the precise, machine-readable contract for one action:

bgc discover --tool order --action place --pretty

{
  "tool": "order", "action": "place",
  "operationId": "placeOrder", "method": "POST", "path": "/api/v3/trade/place-order",
  "auth": "private", "isWrite": true,
  "required": [
    { "name": "category",  "type": "string", "enum": ["SPOT","MARGIN","USDT-FUTURES","COIN-FUTURES","USDC-FUTURES"] },
    { "name": "symbol",    "type": "string" },
    { "name": "side",      "type": "string", "enum": ["buy","sell"] },
    { "name": "orderType", "type": "string", "enum": ["limit","market"] },
    { "name": "qty",       "type": "string" }
  ],
  "optional": [
    { "name": "price", "type": "string" },
    { "name": "timeInForce", "type": "string", "enum": ["ioc","fok","gtc","post_only"] },
    { "name": "clientOid", "type": "string" },
    { "name": "takeProfit", "type": "string" }, { "name": "stopLoss", "type": "string" }
    /* … tp/sl trigger & limit params … */
  ]
}

With that in hand, the agent assembles the call directly — same camelCase field names, no translation layer:

bgc order --action place --category SPOT --symbol BTCUSDT \
    --side buy --orderType market --qty 0.001 --dry-run

Two properties make this work for agents specifically:

• Self-guiding. Every discover response carries a hint field that names the next rung, so an agent with zero prior knowledge can navigate the whole surface from bgc discover alone.
• Zero-drift. The disclosed schema is derived live from the SDK — there is no static catalog in this repo to fall out of sync. What discover says is, by construction, exactly what the CLI does.

And when the agent only has a fuzzy idea, it can keyword-search the entire surface:

bgc discover --search funding
# → matches: market (actions: fundingRate, fundingRateHistory), account_overview, …

Quick start

export BITGET_API_KEY=...
export BITGET_SECRET_KEY=...
export BITGET_PASSPHRASE=...

# Public market data — no auth needed
bgc market --action tickers --category SPOT --symbol BTCUSDT

# Authenticated read — one-call account snapshot
bgc account_overview --coin USDT

# Preview a write without sending it (nothing leaves the process)
bgc order --action place --category SPOT --symbol BTCUSDT \
    --side buy --orderType market --qty 0.001 --dry-run

# Authenticated write — [CAUTION] real order
bgc order --action place --category SPOT --symbol BTCUSDT \
    --side buy --orderType market --qty 0.001

# Destructive write — high-risk, refuses to run without --confirm
bgc order --action cancelAll --category SPOT --symbol BTCUSDT --confirm

# Pretty-print JSON for human eyes
bgc --pretty position --action info --category USDT-FUTURES

The grammar

bgc <tool> [--action <name>] [--<param> <value> ...] [global flags]
bgc discover [--domain <d> | --tool <t> [--action <a>] | --search <q>]
bgc raw --operationId <id> [--args '<json>']

• <tool> is an intent verb (market, order, position, …), one of the meta tools discover / raw, or — with --full — any 1:1 generated operation.
• --action <name> picks the action on an action-routed verb (e.g. order --action place, order --action cancelAll) and is forwarded to the SDK verbatim. (account_overview, discover, and raw take no --action.)
• Business params forward as-is using the SDK's exact camelCase field names: --symbol BTCUSDT --side buy --orderType market --qty 0.001. Values are coerced naturally — true/false → boolean, a value starting with [/{ → parsed JSON (e.g. --orders '[{...}]'), everything else stays a string (the SDK coerces numerics, so numeric ids are never mistyped).

You never need a command reference in your head — bgc discover is the reference, and it can't go stale.

raw — the escape hatch

The 14 verbs front the common operations. When you need one they don't — or you already know the exact operationId — call it directly:

bgc raw --operationId getTickers --args '{"category":"SPOT","symbol":"BTCUSDT"}'

Drop to the full 1:1 surface (100+ generated operations) with --full when you want every operation exposed as its own tool.

Write-safety

bgc inherits the SDK's layered write-safety gate. Every safety decision happens before any request leaves the process, and every control is a deterministic flag — no interactive prompt — so it is safe in unattended and AI-driven shells.

| Control | Effect | |---|---| | --dry-run | Previews a write and returns the exact payload that would be sent (data.dryRun: true). No network call. | | --read-only | Blocks every write at validation time — a write verb returns a ValidationError and never reaches the network. | | --confirm | Required for destructive / high-risk actions (order --action cancelAll, position --action closeAll, withdraw --action submit, …). Without it the call returns data.confirmationRequired: true and does nothing. | | --paper-trading | Routes writes to Bitget's demo environment (needs demo credentials). Mutually exclusive with --read-only. |

# Dry-run: see what would be sent, send nothing
bgc order --action place --category SPOT --symbol BTCUSDT \
    --side buy --orderType market --qty 0.001 --dry-run

# Read-only: writes are refused before the network
bgc --read-only order --action place --category SPOT --symbol BTCUSDT --side buy ...
# → ValidationError: Operation "placeOrder" is a write and readOnly mode is enabled.

# High-risk gate: cancelAll does nothing until you confirm
bgc order --action cancelAll --category SPOT --symbol BTCUSDT
# → { data: { confirmationRequired: true, ... } }     (stdout, exit 0 — not an error)
bgc order --action cancelAll --category SPOT --symbol BTCUSDT --confirm
# → executes

Output contract

• Success → the resolved ToolResult ({ endpoint, requestTime, data }) is printed to stdout; exit code 0. dryRun previews and confirmationRequired gates are normal results (stdout, exit 0) — they are not errors.
• Failure → a structured error payload ({ ok: false, error: { type, category, message, suggestion, retryable }, timestamp }) is printed to stderr; exit code 1.

Success output is compact JSON (add --pretty for 2-space indentation); error payloads are always pretty-printed. The split is unix-clean: pipe stdout to jq, branch on the exit code, read error.retryable to decide whether to back off and retry.

Configuration

Global flags

--action <name>    Action for an action-routed verb (forwarded as the tool's action)
--modules <list>   Modules to enable (default: all to-C modules); name a hidden one, e.g. --modules broker
--surface <mode>   intent (default) | full (also expose the 1:1 generated operations)
--full             Shorthand for --surface full
--read-only        Block all writes (mutually exclusive with --paper-trading)
--paper-trading    Route writes to the Bitget demo environment (needs demo credentials)
--dry-run          Preview a write without sending it (maps to dryRun)
--confirm          Required to execute destructive (high-risk) writes
--base-url <url>   Override API base URL (else BITGET_API_BASE_URL)
--timeout <ms>     Per-request timeout in ms (else BITGET_TIMEOUT_MS, default 15000)
--pretty           Pretty-print JSON output
--help             Show this help (verb list derived live from the SDK)
--version          Show version

Environment variables

BITGET_API_KEY        API key      ┐
BITGET_SECRET_KEY     API secret   ├─ required only for private (account / trade) calls
BITGET_PASSPHRASE     passphrase   ┘
BITGET_API_BASE_URL   override the API base URL (else --base-url, else Bitget default)
BITGET_TIMEOUT_MS     per-request timeout in ms (else --timeout, default 15000)

Credentials are read from the environment only — never logged, never written to disk.

Verbs at a glance

The default (intent) surface exposes 14 intent verbs across 7 domains — 13 are action-routed (pick the operation with --action), plus the single-shot account_overview — alongside the discover / raw meta tools:

| Domain | Verbs | Auth | |---|---|:---:| | market | market | public | | trade | order, position, strategy_order | private | | account | account_overview, account_config, repayment | private | | funds | transfer_funds, deposit, withdraw, funds_records | private | | subaccount | subaccount | private | | loan | loan | private | | tax | tax | private |

Each action-routed verb fronts several underlying operations via --action. The hidden broker / institutional-loan modules are opt-in (--modules broker, --modules inst_loan). Power users can drop to the --full surface to call any of the 100+ generated 1:1 operations directly.

There is no hand-maintained catalog here to drift — browse it all live with bgc discover.

How bgc is built

bgc is a thin, zero-business-logic shell wrapper around the Bitget Agent SDK. All routing, validation, write-safety, normalization — and the discovery surface itself — live in the SDK. The CLI only parses argv, builds the configured surface, forwards the call, and prints the result:

bgc CLI  (argv → tool call → JSON on stdout / error on stderr)
   │
   ▼
@bitget-ai/bitget-agent-sdk  (intent verbs, action dispatch, progressive
   │                          discovery, write-safety, REST client, HMAC
   │                          signing, rate limiting)
   ▼
Bitget UTA (v3) REST API

Because the discovery and safety logic live in the SDK, the CLI picks up new operations, parameters, and gates for free — a spec change is reflected in bgc discover with no code change here. Every command translates into a single signed HTTPS request. No telemetry, no proxy, no remote dependencies.

Where bgc fits

bgc exists so AI assistants that already live in your shell — Claude Code, Codex CLI, OpenClaw — can drive Bitget with no extra integration wiring. The LLM writes a bgc … command, the shell runs it, the JSON comes back.

• Speak MCP instead? (Claude Desktop, Cursor, Continue, ChatGPT Desktop, Windsurf) → @bitget-ai/bitget-agent-mcp — same intent surface, MCP-shaped.

• Want your assistant to know when to reach for bgc without teaching it each command? Install the Bitget Agent Skill on top:

  npx @bitget-ai/bitget-agent-skill

  Then say "buy 0.1 BTC at market on Bitget" or "show my open futures positions" and it composes the right bgc invocation.

Security

• Credentials are read from environment variables only — never logged, never written to disk.
• All authenticated requests are signed with HMAC-SHA256 in-process.
• Client-side rate limiting protects against accidental AI loops hitting Bitget's API limits.
• Writes are gated by --dry-run / --read-only / --confirm; destructive (high-risk) actions refuse to run without explicit --confirm.
• --read-only and --paper-trading are layered safety nets for handing the CLI to an AI agent.

License

MIT

Part of the Bitget Agent Hub ecosystem · Trading Stack · Surface. Foundation: agent-sdk · Other surfaces: agent-mcp · agent-skill · Market signals: bitget-signal