bitget-agent-sdk — Official Bitget AI Trading TypeScript SDK

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.

Quick Start · Features · Usage · Modules · Testing · Error Handling · FAQ

Overview

@bitget-ai/bitget-agent-sdk is the foundation TypeScript SDK of the Bitget Agent Hub ecosystem. It provides:

• 89 UTA operations with full JSON Schema
• 14 curated Intent verbs for AI tool-use frameworks, plus raw and discover meta tools
• HMAC-SHA256 request signing and client-side rate limiting
• Zero runtime dependencies — lightweight and tree-shakeable ("sideEffects": false)

Both bitget-agent-cli and bitget-agent-mcp are built on top of this SDK.

For developers: Building quant strategies, custom MCP servers, LLM tool-use pipelines, or automated trading bots. 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.

Quick Start

Install

npm install @bitget-ai/bitget-agent-sdk

Basic Usage

import {
  loadConfig,
  buildTools,
  BitgetRestClient,
  safeInvoke,
} from "@bitget-ai/bitget-agent-sdk";

// Default surface is "intent" (curated verbs + raw + discover).
// Starting with readOnly is a safe default — every write tool is dropped.
const config = loadConfig({ modules: "all", readOnly: true });
const client = new BitgetRestClient(config);
const tools = buildTools(config);
const ctx = { config, client };

console.log(`Loaded ${tools.length} tools`); // intent verbs + raw + discover

// Public market data — no credentials required.
const market = tools.find((t) => t.name === "market")!;
const res = await safeInvoke(
  market,
  { action: "tickers", category: "SPOT", symbol: "BTCUSDT" },
  ctx,
);

if (res.ok) console.log(res.data);
else console.error(res.error);

Set Credentials

Credentials are read from environment variables — the SDK does not parse .env files and never writes credentials to disk:

export BITGET_API_KEY="your-api-key"
export BITGET_SECRET_KEY="your-secret-key"
export BITGET_PASSPHRASE="your-passphrase"

Or pass them inline to loadConfig({ apiKey, secretKey, passphrase, ... }).

Features

What It Does for You

Key Exports

// Client + tool primitives
import {
  BitgetRestClient,
  buildTools,
  toToolSpec,
  loadConfig,
  safeInvoke,
  toMcpTool,
} from "@bitget-ai/bitget-agent-sdk";

// Curated verbs, discovery, raw
import {
  COMPOSITE_TOOL_NAMES,
  buildDiscoverTool,
  DISCOVER_TOOL_NAME,
  RAW_TOOL_NAME,
} from "@bitget-ai/bitget-agent-sdk";

// The generated catalog (single source of truth)
import {
  CATALOG,
  CATALOG_SPEC_VERSION,
  CATALOG_OPERATION_COUNT,
  getOperation,
} from "@bitget-ai/bitget-agent-sdk";

// Types
import type {
  BitgetConfig,
  CliOptions,
  Surface,
  ToolSpec,
  ToolContext,
  ToolResult,
  SafeResult,
  ModuleId,
} from "@bitget-ai/bitget-agent-sdk";

// Metadata
import {
  SERVER_NAME,
  SERVER_VERSION,
  API_VARIANT,
  MODULES,
  DEFAULT_MODULES,
} from "@bitget-ai/bitget-agent-sdk";

// Errors — all subclasses of BitgetMcpError
import {
  BitgetMcpError,
  BitgetApiError,
  ConfigError,
  ValidationError,
  RateLimitError,
  AuthenticationError,
  NetworkError,
  toToolErrorPayload,
} from "@bitget-ai/bitget-agent-sdk";

Everything exported from the package root or the @bitget-ai/bitget-agent-sdk/testing subpath follows semver. Anything not exported from those paths is internal and may change without notice.

Usage

Control Tool Scope & Safety

loadConfig accepts these commonly-used options:

Every 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.

Explore at Runtime

discover lets a model learn the surface progressively, without you shipping a separate tool catalog in the prompt:

const discover = tools.find((t) => t.name === "discover")!;

await safeInvoke(discover, {}, ctx);                                    // domains + tool counts
await safeInvoke(discover, { domain: "trade" }, ctx);                   // tools in a domain
await safeInvoke(discover, { tool: "market" }, ctx);                    // one tool's full schema
await safeInvoke(discover, { tool: "market", action: "tickers" }, ctx); // one action's exact contract
await safeInvoke(discover, { search: "funding" }, ctx);                 // keyword search

Intent Verbs (Default Surface)

The default intent surface exposes 14 curated verbs, each gated on its module being enabled. These 14 cover the generally-available modules:

Plus two always-present meta tools:

• 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.
• discover — introspect the active surface (see above). Both are available in every surface and every mode.

Modules

The default profile loads account + trade + market, covering everyday trading. Load everything with loadConfig({ modules: "all" }), or pick a named subset:

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 →

Testing

Import an in-memory Bitget API simulator from the @bitget-ai/bitget-agent-sdk/testing subpath for integration tests — no real API key required:

import { MockServer, seedState } from "@bitget-ai/bitget-agent-sdk/testing";
import { loadConfig, BitgetRestClient } from "@bitget-ai/bitget-agent-sdk";

const mock = new MockServer();
await mock.start(); // ephemeral port

const config = loadConfig({
  modules: "market",
  baseUrl: mock.baseUrl,
  apiKey: "test",
  secretKey: "test",
  passphrase: "test",
});
const client = new BitgetRestClient(config);

// ... drive your tests against `client` ...

await mock.stop();

Error Handling

Two complementary layers:

1. safeInvoke — the recommended path. It never throws. Branch on .ok:

const res = await safeInvoke(tool, args, ctx);
if (res.ok) {
  // res.data, res.endpoint, res.requestTime
} else {
  // res.error — a JSON-serialisable payload, ready for an LLM tool-use reply
}

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:

import { BitgetApiError, ConfigError, RateLimitError } from "@bitget-ai/bitget-agent-sdk";

try {
  await tool.handler(args, ctx);
} catch (err) {
  if (err instanceof RateLimitError) {
    // SDK applies client-side rate limiting, but Bitget can still 429 under load — back off and retry
  } else if (err instanceof BitgetApiError) {
    console.error(err.code, err.message);
  } else if (err instanceof ConfigError) {
    // Missing or invalid credentials — surface to the user
  }
}

Use toToolErrorPayload(err) to convert any caught error into the same { ok: false, error: { … } } payload safeInvoke produces.

Security

• 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.
• Signed locally: all authenticated requests are signed in-process with HMAC-SHA256 before reaching Bitget's API — no third-party server is involved.
• Client-side rate limiting: built-in throttling prevents loops from hitting Bitget's API limits.

Compatibility

Documentation

• 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.
• Bitget API reference. bitget.com/api-doc

Related Projects

FAQ

What is bitget-agent-sdk?

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.

What developer use cases is this SDK designed for?

Building 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.

How is this different from calling the Bitget REST API directly?

The 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.

Does this SDK support CommonJS?

No, it is ESM-only ("type": "module"). Requires Node.js ≥ 20 and NodeNext module resolution.

How do I load only specific modules?

Pass a comma-separated list, e.g. loadConfig({ modules: "account,trade" }), or loadConfig({ modules: "all" }) for every module.

I'm on a classic Bitget account — can I use this?

Yes, 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 →

Is it officially from Bitget and free to use?

Yes. It is an official open-source SDK published by Bitget under the MIT license, free to use.

License

MIT — Bitget Agent SDK

_{Official Bitget Agent Hub tool · Trading Stack · Foundation layer. Surfaces built on this SDK: agent-cli · agent-mcp · agent-skill}