![\"Bitget](\"assets/logo.png\"){kind=logo}
\n\n \n
\n The foundation TypeScript SDK for the Bitget Unified Trading Account (UTA / v3) REST API — exposed as AI-callable Intent tools, with HMAC-SHA256 signing and client-side rate limiting.\n
\n\n\n ![\"Bitget](\"https://github.com/Bitget-AI/agent-sdk/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"Bitget](\"https://img.shields.io/npm/v/%40bitget-ai%2Fbitget-agent-sdk.svg?style=flat-square&color=6f42c1&label=npm\")
\n ![\"Bitget](\"https://img.shields.io/npm/dm/%40bitget-ai%2Fbitget-agent-sdk.svg?style=flat-square&color=026e00&label=downloads\")
\n ![\"TypeScript](\"https://img.shields.io/npm/types/%40bitget-ai%2Fbitget-agent-sdk.svg?style=flat-square\")
\n ![\"Requires](\"https://img.shields.io/badge/Node.js-%E2%89%A520-026e00?style=flat-square\"){kind=icon}
![\"Zero](\"https://img.shields.io/badge/zero%20runtime%20deps-none-lightgrey?style=flat-square\"){kind=icon}
![\"MIT](\"https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square\"){kind=icon}
\n
\n Quick Start ·\n Features ·\n Usage ·\n Modules ·\n Testing ·\n Error Handling ·\n FAQ\n
\n\n---\n\n## Overview\n\n`@bitget-ai/bitget-agent-sdk` is the **foundation TypeScript SDK** of the Bitget Agent Hub ecosystem. It provides:\n\n- **89 UTA operations** with full JSON Schema\n- **14 curated Intent verbs** for AI tool-use frameworks, plus `raw` and `discover` meta tools\n- **HMAC-SHA256 request signing** and client-side rate limiting\n- **Zero runtime dependencies** — lightweight and tree-shakeable (`\"sideEffects\": false`)\n\nBoth [`bitget-agent-cli`](https://github.com/Bitget-AI/agent-cli) and [`bitget-agent-mcp`](https://github.com/Bitget-AI/agent-mcp) are built on top of this SDK.\n\n> **For developers**: Building quant strategies, custom MCP servers, LLM tool-use pipelines, or automated trading bots.\n> **Not a developer?** Use the higher-level surfaces: `bitget-agent-cli` + `bitget-agent-skill` for terminal AI, `bitget-agent-mcp` for desktop AI, `bitget-signal` for market analysis with no account needed. None of them require this SDK directly.\n\n---\n\n## Quick Start\n\n### Install\n\n```bash\nnpm install @bitget-ai/bitget-agent-sdk\n```\n\n### Basic Usage\n\n```typescript\nimport {\n loadConfig,\n buildTools,\n BitgetRestClient,\n safeInvoke,\n} from \"@bitget-ai/bitget-agent-sdk\";\n\n// Default surface is \"intent\" (curated verbs + raw + discover).\n// Starting with readOnly is a safe default — every write tool is dropped.\nconst config = loadConfig({ modules: \"all\", readOnly: true });\nconst client = new BitgetRestClient(config);\nconst tools = buildTools(config);\nconst ctx = { config, client };\n\nconsole.log(`Loaded ${tools.length} tools`); // intent verbs + raw + discover\n\n// Public market data — no credentials required.\nconst market = tools.find((t) => t.name === \"market\")!;\nconst res = await safeInvoke(\n market,\n { action: \"tickers\", category: \"SPOT\", symbol: \"BTCUSDT\" },\n ctx,\n);\n\nif (res.ok) console.log(res.data);\nelse console.error(res.error);\n```\n\n### Set Credentials\n\nCredentials are read from environment variables — the SDK does not parse `.env` files and never writes credentials to disk:\n\n```bash\nexport BITGET_API_KEY=\"your-api-key\"\nexport BITGET_SECRET_KEY=\"your-secret-key\"\nexport BITGET_PASSPHRASE=\"your-passphrase\"\n```\n\nOr pass them inline to `loadConfig({ apiKey, secretKey, passphrase, ... })`.\n\n---\n\n## Features\n\n### What It Does for You\n\n| Feature | What It Replaces |\n|---|---|\n| **89 UTA operations** with **14 curated Intent verbs**, mountable to any LLM framework in one call | Hand-rolling endpoint wrappers and keeping them in sync |\n| **`safeInvoke`** — every call resolves to `{ ok, … }`, never throws | Wrapping every tool call in your own try/catch |\n| **`discover`** — the surface describes itself to your model, drill in on demand | Maintaining a separate tool catalog just for prompts |\n| **Request signing** (HMAC-SHA256) + client-side rate limiting + typed errors | Re-implementing Bitget's auth spec yourself |\n| **Safety modes**: `readOnly` + `paperTrading`, high-risk ops require explicit `confirm` | Writing your own guardrails against accidental live orders |\n\n### Key Exports\n\n```typescript\n// Client + tool primitives\nimport {\n BitgetRestClient,\n buildTools,\n toToolSpec,\n loadConfig,\n safeInvoke,\n toMcpTool,\n} from \"@bitget-ai/bitget-agent-sdk\";\n\n// Curated verbs, discovery, raw\nimport {\n COMPOSITE_TOOL_NAMES,\n buildDiscoverTool,\n DISCOVER_TOOL_NAME,\n RAW_TOOL_NAME,\n} from \"@bitget-ai/bitget-agent-sdk\";\n\n// The generated catalog (single source of truth)\nimport {\n CATALOG,\n CATALOG_SPEC_VERSION,\n CATALOG_OPERATION_COUNT,\n getOperation,\n} from \"@bitget-ai/bitget-agent-sdk\";\n\n// Types\nimport type {\n BitgetConfig,\n CliOptions,\n Surface,\n ToolSpec,\n ToolContext,\n ToolResult,\n SafeResult,\n ModuleId,\n} from \"@bitget-ai/bitget-agent-sdk\";\n\n// Metadata\nimport {\n SERVER_NAME,\n SERVER_VERSION,\n API_VARIANT,\n MODULES,\n DEFAULT_MODULES,\n} from \"@bitget-ai/bitget-agent-sdk\";\n\n// Errors — all subclasses of BitgetMcpError\nimport {\n BitgetMcpError,\n BitgetApiError,\n ConfigError,\n ValidationError,\n RateLimitError,\n AuthenticationError,\n NetworkError,\n toToolErrorPayload,\n} from \"@bitget-ai/bitget-agent-sdk\";\n```\n\nEverything exported from the package root or the `@bitget-ai/bitget-agent-sdk/testing` subpath follows [semver](https://semver.org). Anything not exported from those paths is internal and may change without notice.\n\n---\n\n## Usage\n\n### Control Tool Scope & Safety\n\n`loadConfig` accepts these commonly-used options:\n\n| Option | Default | Effect |\n|---|---|---|\n| `surface` | `\"intent\"` | `\"intent\"` (default) exposes the curated verbs + `raw` + `discover`. `\"full\"` additionally emits one 1:1 tool per operation. |\n| `modules` | `\"account,trade,market\"` | Comma-separated module list, or `\"all\"`. Gates which tools are surfaced. |\n| `readOnly` | `false` | Drop every write tool; reads only. Mutually exclusive with `paperTrading`. |\n| `paperTrading` | `false` | Send orders to Bitget paper trading. Mutually exclusive with `readOnly`. |\n| `baseUrl` | `https://api.bitget.com` | API base URL (or `BITGET_API_BASE_URL`). |\n| `timeoutMs` | `15000` | Per-request timeout in ms (or `BITGET_TIMEOUT_MS`). |\n\nEvery tool carries a `riskLevel` of `read` < `write` < `high`. High-risk operations self-gate: they return a `{ confirmationRequired: true }` preview until you pass `confirm`, so an agent can't fire a destructive call on its first turn. This holds on **every** path — the curated verbs, the 1:1 operation tools, and the `raw` escape hatch all flow through one safety chokepoint.\n\n### Explore at Runtime\n\n`discover` lets a model learn the surface progressively, without you shipping a separate tool catalog in the prompt:\n\n```typescript\nconst discover = tools.find((t) => t.name === \"discover\")!;\n\nawait safeInvoke(discover, {}, ctx); // domains + tool counts\nawait safeInvoke(discover, { domain: \"trade\" }, ctx); // tools in a domain\nawait safeInvoke(discover, { tool: \"market\" }, ctx); // one tool's full schema\nawait safeInvoke(discover, { tool: \"market\", action: \"tickers\" }, ctx); // one action's exact contract\nawait safeInvoke(discover, { search: \"funding\" }, ctx); // keyword search\n```\n\n### Intent Verbs (Default Surface)\n\nThe default `intent` surface exposes **14 curated verbs**, each gated on its module being enabled. These 14 cover the generally-available modules:\n\n| Verb | Module | Reaches |\n|---|---|---|\n| `market` | `market` | tickers, order book, candles, funding rate, open interest, reference reads |\n| `order` | `trade` | place / amend / cancel orders, current & historical orders, fills |\n| `position` | `trade` | open positions, leverage & margin mode, position history |\n| `strategy_order` | `trade` | trigger / TP-SL / plan orders |\n| `account_overview` | `account` | balances, assets, bills |\n| `account_config` | `account` | account mode, margin & leverage settings |\n| `transfer_funds` | `account` | internal & sub-account transfers |\n| `deposit` | `account` | deposit address & records |\n| `withdraw` | `account` | withdrawals & records |\n| `funds_records` | `account` | deposit / withdraw / transfer history |\n| `repayment` | `account` | liability repayment |\n| `subaccount` | `account` | sub-account create / list / manage |\n| `loan` | `cryptoloans` | borrow, repay, collateral, loan records |\n| `tax` | `tax` | transaction tax records |\n\nPlus two always-present meta tools:\n\n- **`raw`** — the escape hatch. Call any operation directly by `operationId` when you want the exact 1:1 contract. It routes through the **same safety gate** as the curated verbs — `readOnly`, `dryRun`, and the high-risk `confirm` requirement all still apply, so `raw` widens *reach* without ever skipping a destructive-action confirmation.\n- **`discover`** — introspect the active surface (see above). Both are available in every surface and every mode.\n\n---\n\n## Modules\n\nThe default profile loads `account` + `trade` + `market`, covering everyday trading. Load everything with `loadConfig({ modules: \"all\" })`, or pick a named subset:\n\n| Module | Operations | Default | Description |\n|---|:---:|:---:|---|\n| `account` | 39 | ✅ | Balances & assets, account settings, transfers, deposit/withdraw, funding records, sub-accounts |\n| `trade` | 17 | ✅ | Order placement & management (spot + futures), positions, fills |\n| `market` | 16 | ✅ | Public market data — tickers, order book, candles, funding rate, open interest |\n| `strategy` | 5 | — | Strategy orders — trigger, TP/SL, plan orders |\n| `cryptoloans` | 11 | — | Crypto-backed loans — borrow, repay, collateral, records |\n| `tax` | 1 | — | Transaction tax records |\n| **Total (visible)** | **89** | **72** | |\n\n> **Classic account users**: If you are on a Bitget classic account, you need to create an Agent sub-account via the API first, then use that sub-account's API key to call MCP / CLI / Skill tools. [Create Agent Sub-Account →](https://www.bitget.com/zh-CN/api-doc/classic/common/vsubaccount/Create-Agent-Subaccount)\n\n---\n\n## Testing\n\nImport an in-memory Bitget API simulator from the `@bitget-ai/bitget-agent-sdk/testing` subpath for integration tests — no real API key required:\n\n```typescript\nimport { MockServer, seedState } from \"@bitget-ai/bitget-agent-sdk/testing\";\nimport { loadConfig, BitgetRestClient } from \"@bitget-ai/bitget-agent-sdk\";\n\nconst mock = new MockServer();\nawait mock.start(); // ephemeral port\n\nconst config = loadConfig({\n modules: \"market\",\n baseUrl: mock.baseUrl,\n apiKey: \"test\",\n secretKey: \"test\",\n passphrase: \"test\",\n});\nconst client = new BitgetRestClient(config);\n\n// ... drive your tests against `client` ...\n\nawait mock.stop();\n```\n\n---\n\n## Error Handling\n\nTwo complementary layers:\n\n**1. `safeInvoke` — the recommended path.** It never throws. Branch on `.ok`:\n\n```typescript\nconst res = await safeInvoke(tool, args, ctx);\nif (res.ok) {\n // res.data, res.endpoint, res.requestTime\n} else {\n // res.error — a JSON-serialisable payload, ready for an LLM tool-use reply\n}\n```\n\n**2. Typed errors — when you call a handler directly.** Every API failure and config problem surfaces as a typed `Error` subclass you can `instanceof`-narrow:\n\n```typescript\nimport { BitgetApiError, ConfigError, RateLimitError } from \"@bitget-ai/bitget-agent-sdk\";\n\ntry {\n await tool.handler(args, ctx);\n} catch (err) {\n if (err instanceof RateLimitError) {\n // SDK applies client-side rate limiting, but Bitget can still 429 under load — back off and retry\n } else if (err instanceof BitgetApiError) {\n console.error(err.code, err.message);\n } else if (err instanceof ConfigError) {\n // Missing or invalid credentials — surface to the user\n }\n}\n```\n\nUse `toToolErrorPayload(err)` to convert any caught error into the same `{ ok: false, error: { … } }` payload `safeInvoke` produces.\n\n---\n\n## Security\n\n- **Credentials from environment variables only**: API keys are read via `export BITGET_API_KEY=...` — the SDK does not parse `.env` files and never writes credentials to disk.\n- **Signed locally**: all authenticated requests are signed in-process with HMAC-SHA256 before reaching Bitget's API — no third-party server is involved.\n- **Client-side rate limiting**: built-in throttling prevents loops from hitting Bitget's API limits.\n\n---\n\n## Compatibility\n\n| | |\n|---|---|\n| **Node.js** | ≥ 20.0.0 |\n| **Module format** | ESM only (`\"type\": \"module\"`). Tree-shaking enabled (`\"sideEffects\": false`). |\n| **TypeScript** | Types ship in the package; no `@types/...` install needed. Module resolution is `NodeNext`. |\n| **Dependencies** | Zero runtime dependencies. |\n| **Bitget API** | Bitget Unified Trading Account (UTA / v3). |\n\n---\n\n## Documentation\n\n- **In-core discovery.** The `discover` tool returns the live, config-aware tool surface and each operation's contract; no external catalog to keep in sync.\n- **Bitget API reference.** [bitget.com/api-doc](https://www.bitget.com/api-doc/common/intro)\n\n---\n\n## Related Projects\n\n| Package | Purpose |\n|---|---|\n| **[bitget-agent-cli](https://github.com/Bitget-AI/agent-cli)** | Terminal AI tool (built on SDK) |\n| **[bitget-agent-mcp](https://github.com/Bitget-AI/agent-mcp)** | Desktop AI MCP server (built on SDK) |\n| **[bitget-agent-skill](https://github.com/Bitget-AI/agent-skill)** | AI reasoning guide |\n| **[bitget-signal](https://github.com/Bitget-AI/bitget-signal)** | Market analysis skills |\n| **[agent-hub](https://github.com/Bitget-AI/agent_hub)** | Ecosystem entry point |\n\n---\n\n## FAQ\n\n### What is bitget-agent-sdk?\n\n`bitget-agent-sdk` is the official Bitget foundation TypeScript SDK — covering 89 UTA operations, with HMAC-SHA256 signing, client-side rate limiting, and a 14-verb Intent surface mountable into any LLM tool-use framework. Both `bitget-agent-cli` and `bitget-agent-mcp` are built on top of it, making it the foundational layer of the entire Bitget Agent Hub ecosystem.\n\n### What developer use cases is this SDK designed for?\n\nBuilding quantitative trading strategies, custom MCP servers, LLM tool-use pipelines, automated trading bots, and any TypeScript or JavaScript project that needs programmatic access to Bitget's UTA API.\n\n### How is this different from calling the Bitget REST API directly?\n\nThe SDK handles HMAC-SHA256 request signing, client-side rate limiting, and typed error classes. It provides 14 curated Intent verbs plus the `raw` escape hatch, all mountable into any LLM tool-use framework. `safeInvoke` gives every call a uniform `{ ok, … }` shape — no need to wrap each handler in try/catch yourself.\n\n### Does this SDK support CommonJS?\n\nNo, it is ESM-only (`\"type\": \"module\"`). Requires Node.js ≥ 20 and `NodeNext` module resolution.\n\n### How do I load only specific modules?\n\nPass a comma-separated list, e.g. `loadConfig({ modules: \"account,trade\" })`, or `loadConfig({ modules: \"all\" })` for every module.\n\n### I'm on a classic Bitget account — can I use this?\n\nYes, but classic accounts need to create an Agent sub-account first via the API, then use that sub-account's API key for MCP / CLI / Skill tools. [View the Create Agent Sub-Account API →](https://www.bitget.com/zh-CN/api-doc/classic/common/vsubaccount/Create-Agent-Subaccount)\n\n### Is it officially from Bitget and free to use?\n\nYes. It is an official open-source SDK published by Bitget under the MIT license, free to use.\n\n---\n\n## License\n\n[MIT](LICENSE) — Bitget Agent SDK\n\nOfficial Bitget Agent Hub tool · Trading Stack · Foundation layer. Surfaces built on this SDK: agent-cli · agent-mcp · agent-skill\n","readmeFilename":"README.md"}