The shell surface of the Bitget Agent Hub. Drive Bitget's Unified Trading Account (UTA / v3) API from Claude Code, Codex CLI, OpenClaw, or any shell-based AI assistant — through a small set of intent verbs and a self-describing surface the agent explores at runtime.
Quick Start · Why agent-native · Progressive disclosure · Installation · Commands · Write-safety · Security · Troubleshooting · FAQ
bitget-agent-cli (binary: bgc) is Bitget's official terminal trading tool, built to be driven by a shell-based AI assistant — Claude Code, Codex CLI, OpenClaw, or anything else that lives in your terminal — with a human reading the result.
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. A small set of intent verbs, a self-describing surface the agent walks at runtime, and deterministic write-safety that makes it safe to hand the keys to an autonomous agent.
Built on the Bitget Unified Trading Account (UTA / v3) API, bgc exposes 89 operations across 7 domains (market, trade, account, funds, subaccount, loan, tax) — fronted by 14 intent verbs plus the discover / raw meta tools. No host application config, no plugins: install and tell your AI what to trade.
Part of Bitget Agent Hub — the official open-source AI ecosystem. See the hub for desktop AI tools (MCP), the foundation SDK, and market-analysis skills.
- Node.js ≥ 20 (download)
- Bitget API Key (create here) — enable Read + Trade permissions. Only required for private (account / trade) calls; market data is public.
npm install -g @bitget-ai/bitget-agent-cli
npx @bitget-ai/bitget-agent-skill --target allThen set your credentials:
export BITGET_API_KEY="your-api-key"
export BITGET_SECRET_KEY="your-secret-key"
export BITGET_PASSPHRASE="your-passphrase"Why install both?
bitget-agent-cliis the execution tool (bgc);bitget-agent-skillteaches your AI when and how to use it. Without the skill file, your AI has the tool but lacks the reasoning to reach for it. Without the CLI, the skill has nothing to call. You need both.Why
npm install -gand notnpx?bgcis a persistent CLI — your AI assistant calls it dozens of times per session, so you want it on$PATHwith zero per-call overhead. The other Bitget AI packages (bitget-agent-skill,bitget-signal,bitget-agent-mcp) are one-shot or subprocess-launched, so they usenpx.
bgc --version
bgc discoverExpected: discover lists the 7 domains (market, trade, account, funds, subaccount, loan, tax) and the raw / discover meta tools.
| 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; any operation outside the curated verbs is 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.
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, modify, cancelAll, countdownCancel, open, detail, history, fills, maxOpen
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 --prettyWith 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-runTwo properties make this work for agents specifically:
- Self-guiding. Every
discoverresponse carries ahintfield that names the next rung, so an agent with zero prior knowledge can navigate the whole surface frombgc discoveralone. - 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
discoversays 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, …npm install -g @bitget-ai/bitget-agent-cliThis adds bgc to your system PATH.
npx @bitget-ai/bitget-agent-skill --target allDeploys to Claude Code, Codex, and OpenClaw simultaneously. Use --target claude or --target codex for a specific tool.
# Add to ~/.bashrc, ~/.zshrc, or similar
export BITGET_API_KEY="your-api-key"
export BITGET_SECRET_KEY="your-secret-key"
export BITGET_PASSPHRASE="your-passphrase"Reload your shell:
source ~/.bashrc # or source ~/.zshrc# Public data (no auth needed)
bgc market --action tickers --category SPOT --symbol BTCUSDT
# Private data (requires auth)
bgc account_overview --coin USDTbgc <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 toolsdiscover/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, andrawtake 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.
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 | Verb | Auth | Description | Example |
|---|---|---|---|---|
market |
market |
public | Tickers, orderbook, candles, funding rate, open interest, recent fills | bgc market --action tickers --symbol BTCUSDT |
trade |
order |
private | Place, cancel, modify, cancelAll, countdown, open/detail/history/fills | bgc order --action place --side buy --qty 0.1 |
trade |
position |
private | Position info, history, adl rank, close, closeAll | bgc position --action info --category USDT-FUTURES |
trade |
strategy_order |
private | Strategy (trigger/plan) orders: place, cancel, modify, open, history | bgc strategy_order --action open |
account |
account_overview |
private | One-call account snapshot (assets + settings + funding assets + positions + fee) | bgc account_overview --coin USDT |
account |
account_config |
private | Account settings & API key info | bgc account_config --action info |
account |
repayment |
private | Cross-margin / isolated-margin repayment | bgc repayment --action repay --coin USDT |
funds |
transfer_funds |
private | Move funds between accounts | bgc transfer_funds --fromAccountType spot --toAccountType futures --amount 100 |
funds |
deposit |
private | Deposit address & records | bgc deposit --action address --coin USDT |
funds |
withdraw |
private | Request withdrawals (high-risk, --confirm) |
bgc withdraw --action submit --coin USDT --amount 100 |
funds |
funds_records |
private | Transfer / deposit / withdraw history | bgc funds_records --action list |
subaccount |
subaccount |
private | Manage subaccounts & their deposits | bgc subaccount --action list |
loan |
loan |
private | Borrow / repay crypto loans | bgc loan --action borrow --coin USDT |
tax |
tax |
private | Query transaction tax records | bgc tax --action history --year 2024 |
Use raw --operationId <id> for any operation not covered by the curated verbs.
| Flag | Purpose | Example |
|---|---|---|
--action <name> |
Action on an action-routed verb | bgc order --action place |
--modules <list> |
Modules to enable (default: all to-C modules) | bgc --modules account,trade ... |
--surface <mode> |
intent (default) | full (also expose 1:1 operations) |
bgc --surface full discover |
--full |
Shorthand for --surface full |
bgc --full discover |
--read-only |
Block all writes (mutually exclusive with --paper-trading) |
bgc --read-only market ... |
--paper-trading |
Route writes to Bitget's demo environment (needs demo credentials) | bgc --paper-trading order ... |
--dry-run |
Preview a write without sending it | bgc order --action place ... --dry-run |
--confirm |
Required for destructive (high-risk) writes | bgc order --action cancelAll ... --confirm |
--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 | bgc market ... --pretty |
--help |
Show help (verb list derived live from the SDK) | bgc --help |
--version |
Show version | bgc --version |
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.
# Get BTC live price (no auth)
bgc market --action tickers --category SPOT --symbol BTCUSDT
# Check USDT balance (one-call snapshot)
bgc account_overview --coin USDT
# Preview a limit buy (dry run — nothing leaves the process)
bgc order --action place --category SPOT --symbol BTCUSDT \
--side buy --orderType limit --price 60000 --qty 0.001 --dry-run
# Execute the order
bgc order --action place --category SPOT --symbol BTCUSDT \
--side buy --orderType limit --price 60000 --qty 0.001
# Cancel a specific order
bgc order --action cancel --category SPOT --orderId 123456789
# Check futures positions
bgc position --action info --category USDT-FUTURES
# Set leverage to 10x
bgc position --action setLeverage --category USDT-FUTURES \
--symbol BTCUSDT --leverage 10 --marginCoin USDT
# High-risk: cancel all orders (requires confirmation)
bgc order --action cancelAll --category SPOT --symbol BTCUSDT --confirm
# Pipe to jq for processing
bgc market --action tickers --category SPOT --symbol BTCUSDT | jq '.data[0].lastPr'
# Explore available actions for a tool
bgc discover --tool order --action place
# Escape hatch: call any operation by ID
bgc raw --operationId getTickers --args '{"category":"SPOT","symbol":"BTCUSDT"}'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- Success → the resolved
ToolResult({ endpoint, requestTime, data }) is printed to stdout; exit code0.dryRunpreviews andconfirmationRequiredgates are normal results (stdout, exit0) — they are not errors. - Failure → a structured error payload (
{ ok: false, error: { type, category, message, suggestion, retryable }, timestamp }) is printed to stderr; exit code1.
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.
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:
Terminal AI (Claude Code / Codex / OpenClaw)
│ natural language → bgc … command
▼
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 (api.bitget.com)
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.
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
bgcwithout teaching it each command? Install the Bitget Agent Skill on top:npx @bitget-ai/bitget-agent-skill --target all
Then say "buy 0.1 BTC at market on Bitget" or "show my open futures positions" and it composes the right
bgcinvocation.
- ✅ Environment variables only: API keys read from
BITGET_API_KEY,BITGET_SECRET_KEY,BITGET_PASSPHRASE— never parsed from.envfiles, never logged, never written to disk. - ✅ Local signing: all authenticated requests are signed with HMAC-SHA256 in-process before reaching Bitget's API.
- ✅ No telemetry, no proxy: every command translates into a single signed HTTPS request straight to
api.bitget.com. No third-party server is involved.
--read-onlymode: strips all write tools at validation time. A write verb returns aValidationErrorand never reaches the network — the AI can neither see nor call order placement, transfers, or cancellations.--dry-run: previews the exact payload that would be sent. No network call.--confirmgate: high-risk operations (cancelAll,closeAll,withdraw, …) returnconfirmationRequired: trueand do nothing until--confirmis passed.--paper-trading: routes writes to Bitget's demo environment.- Client-side rate limiting: protects against accidental AI loops hitting Bitget's API limits.
- Use a Demo API Key first — create one at bitget.com/api-management and test with
--paper-trading. - Start with
--read-only— verify queries work before enabling writes. - Never commit credentials — add
BITGET_*vars to your shell profile outside the repo, or use a secrets manager. Do not put them in.envfiles committed to the project. - Rotate keys regularly — regenerate API keys every 90 days.
Cause: CLI not installed globally, or npm's global bin not on $PATH.
Fix:
npm install -g @bitget-ai/bitget-agent-cli
which bgcIf still not found, add npm's global bin to PATH:
# macOS / Linux
export PATH="$(npm config get prefix)/bin:$PATH"
# Add to ~/.bashrc or ~/.zshrcPossible causes:
- API key has insufficient permissions (needs Read + Trade for private calls).
- Passphrase is incorrect (copy exactly — it's case-sensitive).
- System clock is out of sync (HMAC requires an accurate timestamp).
Fix:
- Verify Read + Trade permissions at bitget.com/api-management.
- Double-check all three credential values.
- Sync the system clock:
sudo sntp -sS pool.ntp.org(macOS) /sudo ntpdate -s pool.ntp.org(Linux).
Cause: skill file not deployed, or the AI tool wasn't restarted after deploy.
Fix:
- Re-deploy the skill:
npx @bitget-ai/bitget-agent-skill --target all - Restart your AI tool (Claude Code / Codex CLI).
- Ask the AI: "What Bitget trading modules are available?" — it should list the domains
bgc discoverreports.
Cause: too many rapid API calls. The CLI throttles client-side, but Bitget's server-side limit can still kick in.
Fix: wait 60 seconds, then retry. Avoid asking the AI to execute hundreds of orders in a tight loop.
Cause: trying to use a module not enabled in the active config.
Fix:
# Load specific modules
bgc --modules account,trade,market ...
# Or load every module
bgc --modules all ...Update to the latest version:
npm install -g @bitget-ai/bitget-agent-cli@latest
npx @bitget-ai/bitget-agent-skill@latest --target allSee CHANGELOG.md for release history.
| Package | Purpose | Best for |
|---|---|---|
| bitget-agent-cli (this repo) | Shell CLI (bgc) — 14 intent verbs over 89 UTA v3 operations |
Claude Code, Codex CLI, OpenClaw |
| bitget-agent-mcp | MCP server — same intent surface, MCP-shaped | Claude Desktop, Cursor, Continue, Windsurf |
| bitget-agent-skill | AI reasoning guide — teaches the AI when to use bgc |
Pairs with bgc or the MCP server |
| bitget-agent-sdk | TypeScript foundation SDK | Developers building custom integrations |
| bitget-signal | Market-analysis skills (macro, on-chain, sentiment) | No API key needed |
| agent_hub | Central ecosystem entry point | Overview of all Bitget AI tools |
bitget-agent-cli is Bitget's official terminal AI trading tool, providing a command-line interface (bgc) for Claude Code, Codex CLI, OpenClaw, and other shell-based AI assistants to operate a Bitget account. Built on the Bitget Unified Trading Account (UTA / v3) API, it exposes 89 operations across 7 domains through 14 intent verbs covering market data, spot/futures trading, account, funds, subaccount, loans, and tax.
Yes. Terminal AI users should install both:
bitget-agent-cliis the execution tool — it signs requests and sends them to Bitget's API.bitget-agent-skillis the AI's instruction manual — it tells the AI when and how to compose the rightbgcinvocation.
Without the skill, your AI has the tool but won't reliably reach for it. Without the CLI, the skill has nothing to call.
No. Claude Desktop and Cursor are desktop AI tools. Install bitget-agent-mcp instead. bitget-agent-cli is designed for terminal AI (Claude Code, Codex CLI, OpenClaw).
Ask your AI: "What Bitget trading modules does bitget-agent-cli support?" If it lists the domains bgc discover reports (market, trade, account, funds, subaccount, loan, tax), the skill is active. You can also run bgc discover directly to see the live surface.
Add --read-only:
bgc --read-only market --action tickers --symbol BTCUSDTWrites are blocked at validation time — a write verb returns a ValidationError and never reaches the network.
Yes. Credentials are:
- Read from environment variables only — never parsed from
.envfiles, never logged, never written to disk. - Signed locally with HMAC-SHA256.
- Sent directly to
api.bitget.com— no third-party proxy, no telemetry.
Yes. Use paper trading:
- Create a Demo API Key on Bitget.
- Set the Demo credentials as your environment variables.
- Add
--paper-tradingto yourbgccalls.
All writes route to Bitget's sandbox environment.
bgc provides:
- 14 curated intent verbs instead of raw endpoints.
- Progressive disclosure via
discover— the agent learns the exact contract for one action without loading the whole catalog. - Automatic HMAC signing and client-side rate limiting.
- Natural-language integration via the skill file.
- Deterministic write-safety (
--dry-run,--read-only,--confirm,--paper-trading) — no interactive prompts, safe for unattended shells. - Unix-clean I/O — JSON on stdout (exit
0), structured error on stderr (exit1).
You could call the API directly, but you'd need to implement all of the above yourself.
It's the self-describing surface. Run bgc discover to list domains, bgc discover --domain trade to list a domain's verbs, bgc discover --tool order to list a verb's actions, bgc discover --tool order --action place to see the exact required/optional params for one action. The schema is derived live from the SDK — what discover says is, by construction, exactly what the CLI does.
Yes. MIT-licensed and free to use. Maintained by Bitget at no cost.
See Updates above.
Issues and pull requests welcome! Please read our Contributing Guide before submitting.
- Report bugs: GitHub Issues
- Request features: GitHub Discussions
- Security issues: Email security@bitget.com (do not post publicly)
MIT License — free for personal and commercial use. Attribution appreciated but not required.
--read-only and --paper-trading to rehearse safely before going live. Past performance does not guarantee future results.
Part of the Bitget Agent Hub ecosystem · Trading Stack · Surface.
Foundation: agent-sdk · Other surfaces: agent-mcp · agent-skill · Market signals: bitget-signal
{ "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 … */ ] }