Bitget Agent SDK

bitget-agent-sdk — Bitget 公式 AI トレーディング TypeScript SDK

Bitget Unified Trading Account（UTA / v3）REST API 向けの TypeScript 基盤 SDK です。HMAC-SHA256 署名とクライアント側のレート制限を備え、AI が呼び出せる Intent ツールとして公開します。

クイックスタート · 機能 · 使い方 · モジュール · テスト · エラー処理 · よくある質問

---

概要

@bitget-ai/bitget-agent-sdk は、Bitget Agent Hub エコシステムの基盤となる TypeScript SDKです。以下を提供します。

• 89 件の UTA 操作と完全な JSON Schema
• AI ツール利用フレームワーク向けに厳選した 14 個の Intent 動詞に加え、raw と discover のメタツール
• HMAC-SHA256 リクエスト署名とクライアント側のレート制限
• ランタイム依存関係なし — 軽量でツリーシェイク可能（"sideEffects": false）

bitget-agent-cli と bitget-agent-mcp は、どちらもこの SDK を基盤として構築されています。

開発者向け：クオンツ戦略、カスタム MCP サーバー、LLM ツール利用のパイプライン、自動トレーディングボットの構築に利用できます。 開発者ではない方へ：より高レベルのインターフェースをご利用ください。ターミナル AI には bitget-agent-cli + bitget-agent-skill、デスクトップ AI には bitget-agent-mcp、アカウント不要の市場分析には bitget-signal をお使いください。これらを直接利用するために、この SDK は必要ありません。

---

クイックスタート

インストール

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

基本的な使い方

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);

認証情報の設定

認証情報は環境変数から読み込まれます。SDK は .env ファイルを解析せず、認証情報をディスクに書き込むこともありません。

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

または、loadConfig({ apiKey, secretKey, passphrase, ... }) に直接渡すこともできます。

---

機能

どのように役立つか

機能	置き換えられるもの
89 個の UTA オペレーションと厳選された 14 個の Intent 動詞を、1 回の呼び出しであらゆる LLM フレームワークにマウントできます	エンドポイントラッパーを手作業で作成し、同期を保つ作業
safeInvoke — すべての呼び出しは例外をスローせず、{ ok, … } を返します	すべてのツール呼び出しを独自の try/catch で囲む作業
discover — サーフェスの内容をモデルに説明し、必要に応じて詳細を確認できます	プロンプト専用のツールカタログを別途管理する作業
リクエスト署名（HMAC-SHA256）＋クライアント側のレート制限＋型付きエラー	Bitget の認証仕様を独自に再実装する作業
安全モード：readOnly ＋ paperTrading。高リスクのオペレーションには明示的な confirm が必要です	ライブ注文の誤操作を防ぐガードレールを独自に作成する作業

主なエクスポート

// 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";

パッケージのルート、または @bitget-ai/bitget-agent-sdk/testing サブパスからエクスポートされるものはすべて、semver に従います。これらのパスからエクスポートされないものは内部実装であり、予告なく変更される場合があります。

---

使用方法

ツールの対象範囲と安全性を制御する

loadConfig では、次のよく使用されるオプションを指定できます。

オプション	デフォルト	効果
surface	"intent"	"intent"（デフォルト）では、厳選された動詞に加えて raw と discover を公開します。"full" では、さらに各オペレーションに 1 対 1 で対応するツールを公開します。
modules	"account,trade,market"	カンマ区切りのモジュール一覧、または "all" を指定します。公開するツールを制御します。
readOnly	false	すべての書き込みツールを除外し、読み取り専用にします。paperTrading とは併用できません。
paperTrading	false	Bitget のペーパートレーディングに注文を送信します。readOnly とは併用できません。
baseUrl	https://api.bitget.com	API のベース URL（または BITGET_API_BASE_URL）です。
timeoutMs	15000	リクエストごとのタイムアウト（ミリ秒）です（または BITGET_TIMEOUT_MS）。

すべてのツールには、read < write < high の riskLevel が設定されています。高リスクのオペレーションには安全制御が組み込まれており、confirm を渡すまでは { confirmationRequired: true } のプレビューを返します。そのため、エージェントが最初のターンで破壊的な呼び出しを実行することはありません。この仕組みはすべての経路に適用されます。厳選された動詞、1 対 1 のオペレーションツール、回避用の raw のいずれも、単一の安全制御ポイントを経由します。

実行時に探索する

discover を使うと、プロンプトに別途ツールカタログを含めなくても、モデルがサーフェスの内容を段階的に把握できます。

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 動詞（デフォルトのサーフェス）

デフォルトの intent サーフェスでは、モジュールが有効になっている場合にのみ使用できる、厳選された 14 個の動詞が公開されます。この 14 個で、一般提供されているモジュールをカバーします。

動詞	モジュール	対象
market	market	ティッカー、オーダーブック、ローソク足、資金調達率、未決済建玉、参照情報の読み取り
order	trade	注文の発注／変更／キャンセル、現在および過去の注文、約定
position	trade	オープンポジション、レバレッジと証拠金モード、ポジション履歴
strategy_order	trade	トリガー／TP-SL／プラン注文
account_overview	account	残高、資産、明細
account_config	account	アカウントモード、証拠金とレバレッジの設定
transfer_funds	account	内部振替とサブアカウント間の振替
deposit	account	入金アドレスと記録
withdraw	account	出金と記録
funds_records	account	入金／出金／振替の履歴
repayment	account	負債の返済
subaccount	account	サブアカウントの作成／一覧表示／管理
loan	cryptoloans	借入、返済、担保、ローン記録
tax	tax	取引税の記録

さらに、常に利用できるメタツールが 2 つあります。

• raw — 直接操作するためのツールです。厳密な 1:1 の契約が必要な場合は、operationId を指定して任意の操作を呼び出せます。厳選された動詞と同じ安全ゲートを通るため、readOnly、dryRun、および高リスク操作に対する confirm の要件はすべて引き続き適用されます。つまり、raw は対象範囲を広げますが、破壊的操作の確認を省略することはありません。
• discover — アクティブなサーフェスを調べます（上記を参照）。どちらも、すべてのサーフェスとすべてのモードで利用できます。

---

モジュール

デフォルトのプロファイルでは account + trade + market が読み込まれ、日常的な取引に対応します。loadConfig({ modules: "all" }) ですべてを読み込むか、名前を指定してモジュールを選択できます。

モジュール	操作数	デフォルト	説明
account	39	✅	残高と資産、アカウント設定、振替、入金／出金、資金記録、サブアカウント
trade	17	✅	注文の発注と管理（現物＋先物）、ポジション、約定
market	16	✅	公開市場データ — ティッカー、オーダーブック、ローソク足、資金調達率、未決済建玉
strategy	5	—	ストラテジー注文 — トリガー、TP/SL、プラン注文
cryptoloans	11	—	暗号資産担保ローン — 借入、返済、担保、記録
tax	1	—	取引税の記録
合計（表示対象）	89	72

クラシックアカウントのユーザー向け：Bitget のクラシックアカウントを利用している場合、まず API 経由で Agent サブアカウントを作成し、そのサブアカウントの API キーを使って MCP／CLI／Skill ツールを呼び出す必要があります。Agent サブアカウントを作成 →

---

テスト

統合テストでは、@bitget-ai/bitget-agent-sdk/testing サブパスからメモリ内の Bitget API シミュレーターをインポートできます。実際の API キーは不要です。

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();

---

エラー処理

相互に補完する 2 つのレイヤーがあります。

1. safeInvoke — 推奨される方法です。 例外をスローしません。.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. 型付きエラー — ハンドラーを直接呼び出す場合に使用します。 API の失敗や設定の問題はすべて、instanceof で型を絞り込める型付きの Error サブクラスとして表されます。

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
  }
}

toToolErrorPayload(err) を使うと、捕捉した任意のエラーを、safeInvoke が生成するものと同じ { ok: false, error: { … } } ペイロードに変換できます。

---

セキュリティ

• 認証情報は環境変数からのみ取得：API キーは export BITGET_API_KEY=... を介して読み込まれます。SDK は .env ファイルを解析せず、認証情報をディスクに書き込むこともありません。
• ローカルで署名：認証が必要なすべてのリクエストは、Bitget の API に到達する前に、プロセス内で HMAC-SHA256 を使って署名されます。サードパーティのサーバーは関与しません。
• クライアント側のレート制限：組み込みのスロットリングにより、ループが Bitget の API 制限に達するのを防ぎます。

---

互換性

Node.js	≥ 20.0.0
モジュール形式	ESM のみ（"type": "module"）。ツリーシェイキングが有効です（"sideEffects": false）。
TypeScript	型定義はパッケージに同梱されているため、@types/... のインストールは不要です。モジュール解決方式は NodeNext です。
依存関係	実行時の依存関係はありません。
Bitget API	Bitget Unified Trading Account（UTA / v3）。

---

ドキュメント

• コア内ディスカバリー。 discover ツールは、実行時の設定を反映したツール群と、各操作の仕様を返します。同期を保つ外部カタログは不要です。
• Bitget API リファレンス。 bitget.com/api-doc

---

関連プロジェクト

パッケージ	用途
bitget-agent-cli	ターミナル AI ツール（SDK 上に構築）
bitget-agent-mcp	デスクトップ AI MCP サーバー（SDK 上に構築）
bitget-agent-skill	AI 推論ガイド
bitget-signal	市場分析スキル
agent-hub	エコシステムのエントリーポイント

---

FAQ

bitget-agent-sdk とは何ですか？

bitget-agent-sdk は、Bitget 公式の基盤となる TypeScript SDK です。HMAC-SHA256 署名、クライアント側のレート制限、およびあらゆる LLM ツール使用フレームワークに組み込み可能な 14 種類の動詞を備えた Intent サーフェスにより、89 種類の UTA 操作をカバーします。bitget-agent-cli と bitget-agent-mcp はどちらもこの SDK 上に構築されており、Bitget Agent Hub エコシステム全体の基盤レイヤーとなっています。

この SDK はどのような開発用途を想定していますか？

定量取引戦略、カスタム MCP サーバー、LLM ツール使用パイプライン、自動取引ボットの構築や、Bitget の UTA API へのプログラムからのアクセスを必要とするあらゆる TypeScript または JavaScript プロジェクトを想定しています。

Bitget REST API を直接呼び出す場合と何が違いますか？

この SDK は、HMAC-SHA256 リクエスト署名、クライアント側のレート制限、および型付きエラークラスを処理します。厳選された 14 種類の Intent 動詞に加えて raw のエスケープハッチを提供し、あらゆる LLM ツール使用フレームワークに組み込めます。safeInvoke により、すべての呼び出しで統一された { ok, … } 形式が得られるため、各ハンドラーを自分で try/catch で囲む必要はありません。

この SDK は CommonJS に対応していますか？

いいえ。ESM のみです（"type": "module"）。Node.js ≥ 20 と NodeNext モジュール解決方式が必要です。

特定のモジュールだけを読み込むにはどうすればよいですか？

カンマ区切りのリストを渡します。例：loadConfig({ modules: "account,trade" })。すべてのモジュールを読み込むには、loadConfig({ modules: "all" }) を使用します。

従来の Bitget アカウントを使っていますが、この SDK は利用できますか？

はい。ただし、従来のアカウントでは、まず API 経由で Agent サブアカウントを作成し、そのサブアカウントの API キーを MCP / CLI / Skill ツールに使用する必要があります。Agent サブアカウント作成 API を見る →

Bitget 公式のもので、無料で利用できますか？

はい。Bitget が MIT ライセンスのもとで公開している公式のオープンソース SDK で、無料で利用できます。

---

ライセンス

MIT — Bitget Agent SDK

_{Bitget 公式 Agent Hub ツール · Trading Stack · 基盤レイヤー。この SDK 上に構築されたサーフェス：agent-cli · agent-mcp · agent-skill}