Bitget

Bitget Skill (Unified Trading Account / v3)

Drive the Bitget exchange through the bgc CLI — one Unified Trading Account (UTA) covering spot, margin, and futures, plus funds, sub-accounts, loans, and broker operations. The CLI is a thin shell over the Bitget Agent SDK: the SDK owns action dispatch, input validation, write-safety, and discovery, so this skill teaches you the grammar and the safe workflow, then points you at the reference docs.

Reference docs live in this skill's references/ directory (alongside this file).

Step 1: Check prerequisites

bgc --version

If not found → tell the user: npm install -g @bitget-ai/bitget-agent-cli

Public market data needs no credentials. Everything else (account, trading, transfers, withdrawals) needs API credentials as environment variables. See references/auth-setup.md.

Step 2: The grammar (this replaced the old v2 grammar)

bgc <tool> [--action <name>] [--<param> <value> ...] [global flags]

• One verb per call. There are 14 intent verbs (e.g. market, order, position, account_overview, transfer_funds, withdraw).
• --action picks the intent for an action-routed verb (bgc order --action place, bgc position --action closeAll). A few verbs take no action (e.g. account_overview is a single-shot snapshot).
• Values coerce by shape: true/false → boolean, a value starting with [ or { → JSON (e.g. --orders '[{...}]'), everything else stays a string.

The old v2 form bgc <module> <tool_name> (e.g. bgc spot spot_get_ticker) is gone. There are no separate spot/futures modules — one --category param (SPOT, MARGIN, USDT-FUTURES, COIN-FUTURES, USDC-FUTURES) selects the market.

Step 3: Discover before you assemble a call

Don't guess parameters. The CLI introspects its own live surface:

bgc discover                              # list domains + verb counts
bgc discover --domain trade               # verbs in a domain
bgc discover --tool order                 # one verb: actions + full schema
bgc discover --tool order --action place  # exact required/optional contract
bgc discover --search "funding rate"      # keyword-search the whole surface

bgc discover --tool <verb> --action <name> is the authoritative, always-current parameter contract. Read it before constructing any non-trivial command, especially for trading. Full guide: references/discover-guide.md.

A complete static catalog of every verb, action, and parameter is in references/commands.md (auto-generated from the SDK — navigate by its domain TOC).

Output contract

All output is JSON.

• Success → stdout, exit 0: { endpoint, requestTime, data } — data is the result.
• Error → stderr, exit 1: { ok: false, error: { type, category, message, suggestion, retryable }, timestamp }.
• --dry-run → stdout, exit 0: { dryRun: true, operationId, wouldSend, ... } — the would-send request, nothing sent.
• Confirmation gate → stdout, exit 0: { confirmationRequired: true, operationId, hint, ... } — a high-risk write that was NOT executed because --confirm was absent. This is a normal result, not an error.

On error, branch on error.category: auth/param → fix the request and resend; balance/risk → surface to the user (cannot self-heal); rate/network → back off and retry; config → check account mode / credentials. See references/error-codes.md.

The 14 verbs

Use discover for the actions and exact params of any verb.

Write safety: two different "confirms" — don't conflate them

Operations are graded read < write < high. There are TWO separate confirmation concepts here, and mixing them up is the single biggest source of trading mistakes:

1. Confirm with the USER — for every write. Before running ANY write (placing or cancelling orders, transfers, withdrawals, setting leverage, borrowing, repaying), summarize what it will do and get the user's go-ahead. This is your behavior, not a CLI flag. Never silently execute a write.

   Example: "This places a limit BUY of 0.01 BTC at $70,000 on BTCUSDT (SPOT). OK to send?"

2. The --confirm flag — for high-risk ops only. This is a CLI gate that ONLY four operations require: closeAllPositions, cancelAllOrders, withdrawal, brokerSubaccountWithdrawal. Without --confirm they return { confirmationRequired: true } and send nothing (a normal result, not an error).

Ordinary writes do NOT take --confirm. A plain order --action place, a single cancel, a transfer_funds, a leverage change — these execute live the moment you omit --dry-run. --confirm is not their gate and adding it changes nothing; the user's go-ahead (concept 1) is what authorizes them.

Don't guess which kind an action is — read its contract. bgc discover --tool <verb> --action <name> reports riskLevel (read|write|high) and requiresConfirm (true only for the four high-risk ops).

Safety flags:

• --dry-run — preview the would-send request without sending it (great for showing the user exactly what will happen).
• --confirm — execute a high-risk operation. No effect on an ordinary write or a read.
• --read-only — block all writes for the session.
• --paper-trading — route writes to the Bitget demo environment (see below).

Recommended patterns:

• Ordinary write: preview with --dry-run (or just summarize the effect), get the user's OK, then run it — no --confirm.
• High-risk write: --dry-run to preview → show the user the wouldSend payload → on their OK, re-run with --confirm.

Trading specifics — read before trading

Before constructing futures close / TP-SL / withdrawal commands, read references/trading-safety.md. Critical rules:

• Close ONE position at market: position --action close --symbol <PAIR>. High-risk → needs --confirm; in hedge mode add --posSide long|short. It hard-requires --symbol, so it can never flatten the whole category by omission.
• Close EVERYTHING in a category: position --action closeAll --category <CAT> (optionally narrowed by --symbol) — also high-risk, needs --confirm.
• Close at YOUR price instead of market: order --action place with the OPPOSITE side — one-way mode add --reduceOnly yes; hedge mode set --posSide to the side you're closing. (Selling to "close" a short actually opens more short — check position --action info first.)
• Limit orders require --price (market orders take none); in hedge mode --posSide is required too. discover --tool order --action place reports these under conditionalRequired.
• TP/SL: preset --takeProfit / --stopLoss on the opening order, or manage after entry via strategy_order.
• Spot market BUY qty is in quote coin (USDT), not base coin — confirm intent to avoid mis-sized orders.
• Withdrawals: always show the chain and destination address in the confirmation; wrong chain is irreversible.

Demo / paper trading

When the user wants to practice or says "demo"/"paper"/"simulated", add --paper-trading to writes (needs separate demo credentials; mutually exclusive with --read-only). Keep the whole session in one mode — never mix live and demo. See references/demo-trading.md.

Output presentation

• Prices/tickers: symbol, last price, 24h change, volume — readable summary, not raw JSON.
• Order lists: table with orderId, symbol, side, price, qty, status.
• Balances: coin, available, frozen; skip dust (< 0.0001).
• Positions: symbol, side (long/short), size, entry, mark, unrealized PnL, liquidation price, leverage. Never omit liquidation price.
• Funding rates: current rate, annualized, next settlement time.
• For raw data the user didn't ask to see: summarize, don't dump full JSON. Use --view summary (default) and --fields to trim large payloads.

Escape hatch

If no verb fronts the operation you need, reach any catalog operation by id:

bgc raw --operationId <id> --args '{"category":"SPOT","symbol":"BTCUSDT"}'