# Agent Hub

**No need to open the exchange — say one sentence, and AI executes it directly in Claude, Cursor, or Codex on your Bitget account to trade stocks and crypto.**

Runs as a local process on your device · API Key signed locally with HMAC-SHA256, never leaves your machine · MIT open source

:::info{title="Latest version"}
This document may not reflect the latest version. For the most recent changes, see the [GitHub repository](https://github.com/Bitget-AI/agent_hub).
:::

[GitHub](https://github.com/Bitget-AI/agent_hub) · [Get API Key](https://www.bitget.com/account/newapi) · [Telegram](https://telegram.me/+o1tYqQ_lXxllYjgy)

## Table of Contents

```text
Bitget AgentHub
│
├── What it does
├── Choose your install path
│
├── Installation guides
│   ├── MCP Server    ← Claude Desktop / Cursor / Windsurf / Codex
│   ├── CLI · bgc     ← Claude Code / Codex CLI / OpenClaw
│   ├── Skill         ← Works with CLI, teaches AI when and how to call Bitget
│   ├── Signal        ← Real-time data + AI analysis, no account needed
│   └── SDK           ← For developers building custom integrations
│
├── Safety
└── FAQ
```

## What it does

:::tip{title="Who it's for"}
AgentHub is built for anyone who wants to use AI to trade crypto and tokenized stocks: read charts · analyze markets · execute trades · manage accounts · build strategies · do research.
:::

The frustrating part of using AI for trading isn't the strategy — it's the constant switching between AI and your exchange. Ask AI, then manually place the order. Check the chart, then switch back to chat. AgentHub removes that gap: say it once in your AI, and it handles the rest.

| You say to AI | What happens |
|-|-|
| "Buy 0.1 BTC at market" · "Open BTC long 10x leverage" | Spot / futures order |
| "Check balance" · "Transfer 500 USDT to futures" | Account query & fund transfer |
| "BTC price" · "4h candles" · "Funding rate" | Live market data (no API Key needed) |
| "Fear or greed right now?" · "Any big news today?" | Market analysis (no account needed) |

:::warning{title="Risk"}
AI can make mistakes. You are responsible for all orders placed. Always test with paper trading first.
:::

## Choose Your Install Path

Select based on the AI tool you use:

:::info{title="Overview"}
The install steps within each path are universal for all listed tools. For example, the CLI install command is identical for Claude Code, Codex CLI, and OpenClaw — it auto-detects which tools you have installed and deploys to all of them.
:::

| I use… | Go to | One-line install |
|-|-|-|
| Claude Desktop · Cursor · Windsurf · ChatGPT Desktop · Codex | MCP Server | `npx -y @bitget-ai/bitget-agent-mcp` |
| Claude Code · Codex CLI · OpenClaw | CLI · bgc | `npx @bitget-ai/bitget-agent-installer upgrade-all --target all` |
| Market analysis only, no trading | Signal | `npx @bitget-ai/bitget-signal --target all` |
| Not sure / want everything | Full suite | `npx @bitget-ai/bitget-agent-installer upgrade-all --target all` |

:::tip{title="Note"}
The MCP Server one-line command only starts the MCP process — it does not automatically write to your AI tool's config file. You still need to manually (or let AI) edit the config file. See the MCP Server section below for steps.
:::

**Prerequisite**: [Node.js ≥ 20](https://nodejs.org/) (run `node -v` to confirm)

## MCP Server

:::info{title="When to use"}
If you use a GUI-based AI tool (Claude Desktop, Cursor, Windsurf, ChatGPT Desktop, Codex), this is your path. Every instruction you give in the chat is translated into a real operation on your Bitget account.
:::

The install steps below work for all supported tools. The core command `npx -y @bitget-ai/bitget-agent-mcp` never changes — the only difference is where you put the config file. Find your tool in the Step 1 table.

### Let AI Configure It For You (Recommended)

Paste the following directly into your AI and it will complete the setup automatically:

```text title="Prompt for your AI"
Please configure the Bitget MCP Server for me (requires Node.js 20+):
First ask which AI tool I'm using (Claude Desktop / Cursor / Windsurf / ChatGPT Desktop),
then add a server launched with `npx -y @bitget-ai/bitget-agent-mcp` to that tool's MCP config,
and fill in my BITGET_API_KEY, BITGET_SECRET_KEY, and BITGET_PASSPHRASE.
Once done, confirm that the Bitget tools have loaded (I should see market, order, discover, etc.).
```

### Manual Setup

**Step 1** — Open your AI tool's config file:

| Tool | Config file path |
|-|-|
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Cursor | Settings → MCP → Add New Server |
| Windsurf / Continue | Refer to each tool's MCP documentation |

**Step 2** — Add the following config (no API Key yet? Go to [API Management](https://www.bitget.com/en/api-management) → Create API Key → enable **Read + Trade** permissions. Start with a **Demo Key** for paper trading):

```json title="mcp config"
{
  "mcpServers": {
    "bitget": {
      "command": "npx",
      "args": ["-y", "@bitget-ai/bitget-agent-mcp"],
      "env": {
        "BITGET_API_KEY": "your-api-key",
        "BITGET_SECRET_KEY": "your-secret-key",
        "BITGET_PASSPHRASE": "your-passphrase"
      }
    }
  }
}
```

**Step 3** — Fully quit and restart your AI tool.

**Step 4** — Type `What's the current BTC price?` in your AI. If you get market data, the setup worked.

### Adjust Mode As Needed

Append parameters to `args` to switch modes:

| Scenario | Append to args | Notes |
|-|-|-|
| Start with paper trading | `"--paper-trading"` | Uses Demo Key, no real funds |
| Query only, no orders | `"--read-only"` | Blocks all orders and transfers |
| Market data only, no API Key | `"--modules", "market"` | No API Key required |

Example — read-only mode:

```json title="Read-only mode"
"args": ["-y", "@bitget-ai/bitget-agent-mcp", "--read-only"]
```

:::tip{title="Cursor users"}
Cursor supports ~40 MCP tools total. Bitget uses ~14 by default. If tools don't load fully, disable other MCPs or use `--modules market` to load only the market module.
:::

### Proxy Setup (If Needed)

If you need to route traffic through a VPN or proxy, add these variables to the `env` block in your MCP config (fill in your own proxy address):

```json title="Proxy config"
"env": {
  "BITGET_API_KEY": "your-api-key",
  "BITGET_SECRET_KEY": "your-secret-key",
  "BITGET_PASSPHRASE": "your-passphrase",
  "HTTPS_PROXY": "your-proxy-address",
  "NODE_USE_ENV_PROXY": "1"
}
```

:::info{title="Why NODE_USE_ENV_PROXY"}
`NODE_USE_ENV_PROXY=1` ensures Node.js network requests also route through the proxy — without it, some requests may bypass it.
:::

### What AI Can Do After Setup

| Module | Loaded by default | Operations covered | API Key required |
|-|-|-|-|
| `market` | ✅ | Prices · candles · funding rate · order book · open interest | No |
| `trade` | ✅ | Place · cancel · amend orders · positions · strategy orders | Yes |
| `account` | ✅ | Balances · transfers · deposits · withdrawals · sub-accounts | Yes |
| `strategy` | On demand | Trigger orders · TP/SL · plan orders | Yes |
| `cryptoloans` | On demand | Borrow · repay · crypto-backed loans | Yes |
| `tax` | On demand | Tax record queries | Yes |

Load all modules: `"args": ["-y", "@bitget-ai/bitget-agent-mcp", "--modules", "all"]`

### Try These

```text
What's the current BTC price?
Show my USDT balance and open futures positions
Open a BTC long on paper trading, 10x leverage, 0.01 BTC
Check BTC price, then place a limit buy 2% below current price
```

## CLI · bgc

:::info{title="When to use"}
If you use a terminal-based AI tool (Claude Code, Codex CLI, OpenClaw), or want to run commands directly in the terminal, this is your path.
:::

The install steps below are universal for all supported tools. After running the install command, it auto-detects which tools you have and deploys to each — no need to repeat the process per tool.

### Install

Paste into your terminal AI, or run directly in your terminal:

```text title="Prompt for your terminal AI"
Please run the following command to install the Bitget Agent Hub terminal tools (requires Node.js 20+):
npx @bitget-ai/bitget-agent-installer upgrade-all --target all
Once done, verify by running `bgc --version` and `bgc discover`, and show me the output.
```

```bash
npx @bitget-ai/bitget-agent-installer upgrade-all --target all
```

This installs `bgc` CLI, the trading Skill, and the market analysis Skill, and deploys them to Claude Code / Codex / OpenClaw.

### Set Up API Key

No API Key yet? Go to [API Management](https://www.bitget.com/en/api-management) → Create API Key → enable **Read + Trade** permissions. Save all three values: API Key, Secret Key, Passphrase. Start with a **Demo Key** and use `--paper-trading` before going live.

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

:::tip{title="Tip"}
Add these three lines to `~/.zshrc` or `~/.bashrc` so you don't have to set them each session. Public market data requires no Key; account operations and trading require all three.
:::

### Verify Install

```bash
bgc --version         # check version
bgc discover          # list all available operations
bgc market --action tickers --category SPOT --symbol BTCUSDT   # test market data, no Key needed
```

### Full Tool List

`bgc` covers all operations through 14 intent verbs:

| Verb | What it does | Example |
|-|-|-|
| `market` | Prices · candles · funding rate (public) | `bgc market --action tickers --symbol BTCUSDT` |
| `order` | Place · cancel · amend · query orders | `bgc order --action place --side buy --qty 0.1` |
| `position` | View positions · close · set leverage | `bgc position --action info --category linear` |
| `strategy_order` | Trigger orders · TP/SL | `bgc strategy_order --action open` |
| `account_overview` | Account snapshot (assets + positions) | `bgc account_overview --coin USDT` |
| `transfer_funds` | Move funds between accounts | `bgc transfer_funds --fromType spot --amount 100` |
| `deposit` | Deposit address & history | `bgc deposit --action address --coin USDT` |
| `withdraw` | Withdraw (high-risk, needs `--confirm`) | `bgc withdraw --coin USDT --amount 100 --confirm` |
| `loan` | Borrow · repay crypto loans | `bgc loan --action borrow --coin USDT` |
| `subaccount` | Manage sub-accounts | `bgc subaccount --action list` |
| `tax` | Tax records | `bgc tax --action history --year 2024` |
| `discover` | Explore all available operations | `bgc discover --domain trade` |

### Common Commands

```bash
# Check account balance
bgc account_overview --coin USDT

# Preview an order (--dry-run won't actually send it)
bgc order --action place --category SPOT --symbol BTCUSDT \
  --side buy --orderType market --qty 0.001 --dry-run

# View futures positions
bgc position --category linear

# Preview a fund transfer
bgc transfer_funds --action transfer --fromType spot --toType mix_usdt \
  --amount 100 --coin USDT --dry-run
```

**Safety flags:**

| Flag | Effect |
|-|-|
| `--dry-run` | Preview the request, don't send it |
| `--read-only` | Block all write operations |
| `--paper-trading` | Route to Bitget's demo environment |
| `--confirm` | Required for high-risk ops like withdraw |

### Proxy Setup

If you need to route traffic through a VPN or proxy:

```bash
export HTTPS_PROXY="your-proxy-address"
```

Or override the API base URL:

```bash
export BITGET_API_BASE_URL="https://api.bitget.com"
```

### Try These

```text
What's the current BTC price?
Check my USDT balance and transfer 500 USDT to my futures account
Open a BTC long on paper trading, 10x leverage, 0.01 BTC
Check my BTC positions — if I have none, open a 10x long on paper trading
```

## Skill

:::info{title="When to use"}
Works with CLI · bgc. For Claude Code · Codex CLI · OpenClaw.
:::

Skill is an instruction file installed into your AI tool that tells it when to call `bgc`, how to build the command, and how to prompt you for confirmation before any write operation. Without Skill, AI has the tool but doesn't know how to use it.

Skill is included automatically when you install via `upgrade-all`. To deploy separately:

```bash
npx @bitget-ai/bitget-agent-skill --target all
```

| `--target` | Deploys to |
|-|-|
| `claude` | Claude Code |
| `codex` | Codex CLI |
| `openclaw` | OpenClaw |
| `all` | All of the above |

Restart your AI tool after deploying.

## Signal (No Account Needed)

No Bitget account. No API Key. Installation deploys 5 Skill files locally and registers a remote public MCP data service (`https://datahub.noxiaohao.com/mcp`) as the data source — AI analysis is based on real-time data returned by this service, not generated from thin air.

Five data directions:

| You can ask… | Data source & capability |
|-|-|
| "How does Fed policy affect BTC?" | `macro-analyst` — live macro data, rates · yield curve · cross-asset correlation |
| "Are whales moving funds on-chain?" | `market-intel` — on-chain flows · ETF net inflows · DeFi TVL |
| "What's the market sentiment right now?" | `sentiment-analyst` — Fear & Greed Index · funding rates · long/short ratio |
| "Is BTC RSI overbought?" | `technical-analysis` — pulls candle data and calculates 23 indicators |
| "Any major crypto news today?" | `news-briefing` — aggregates 44 sources in real time (media · community · announcements) |

### Install

Paste into your AI, or run directly in your terminal:

```text title="Prompt for your AI"
Please run `npx @bitget-ai/bitget-signal --target all` (requires Node.js 20+),
install the Bitget market analysis Skills, then remind me to restart my AI tool.
```

```bash
npx @bitget-ai/bitget-signal --target all
```

Restart your AI tool after installing, then ask away.

:::tip{title="Technical analysis requires Python dependencies"}
The `technical-analysis` Skill depends on pandas and numpy. To use technical indicator features, run:
:::

```bash
pip install pandas numpy
```

## SDK (For Developers)

:::info{title="When to use"}
If you're a developer building custom Bitget integrations — a custom MCP server, quant strategy, LLM tool-use pipeline, or automated trading bot — use the SDK directly.
:::

### Install

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

**Requirements**: Node.js ≥ 20 · ESM only · zero runtime dependencies · TypeScript types included

### Quick Start

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

// Start read-only — safe default
const config = loadConfig({ modules: "all", readOnly: true });
const client = new BitgetRestClient(config);
const tools = buildTools(config);
const ctx = { config, client };

// Query public market data — no API Key needed
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);
```

### Config Options

| Option | Default | Description |
|-|-|-|
| `surface` | `"intent"` | `"intent"` curated verbs; `"full"` exposes all 1:1 ops |
| `modules` | `"account,trade,market"` | Comma-separated module names, or `"all"` |
| `readOnly` | `false` | Removes all write tools — AI cannot place orders |
| `paperTrading` | `false` | Routes to Bitget Demo environment, no real funds |
| `baseUrl` | `https://api.bitget.com` | Can be overridden via `BITGET_API_BASE_URL` env var |

### Runtime Discovery

No need to memorize operation lists — use `discover` at runtime:

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

await safeInvoke(discover, {}, ctx);                                     // list all domains and tool counts
await safeInvoke(discover, { domain: "trade" }, ctx);                    // tools in the trade domain
await safeInvoke(discover, { tool: "market", action: "tickers" }, ctx);  // exact contract for one action
await safeInvoke(discover, { search: "funding" }, ctx);                  // keyword search
```

### Error Handling

Use `safeInvoke` — never throws:

```typescript
const res = await safeInvoke(tool, args, ctx);
if (res.ok) {
  // res.data
} else {
  // res.error — ready to use as an LLM tool-call error response
}
```

For fine-grained control, use typed errors:

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

try {
  await tool.handler(args, ctx);
} catch (err) {
  if (err instanceof RateLimitError) { /* back off and retry */ }
  else if (err instanceof BitgetApiError) { console.error(err.code, err.message); }
  else if (err instanceof ConfigError) { /* missing or invalid credentials */ }
}
```

### Integration Testing

The SDK includes a built-in MockServer — no real API calls needed:

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

const mock = new MockServer();
await mock.start();

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

// write your tests against client ...

await mock.stop();
```

More: [agent-sdk](https://github.com/Bitget-AI/agent-sdk)

## Safety

AgentHub is designed so your credentials never leave your machine: API Keys are read only from environment variables, all requests are signed locally with HMAC-SHA256 and sent directly to `api.bitget.com` — no middleware, no telemetry, no log uploads.

AgentHub has four built-in protection layers:

| Mechanism | Description |
|-|-|
| **Paper trading** | `--paper-trading` routes all requests to Bitget's Demo environment — no real funds |
| **Read-only mode** | `--read-only` removes all write tools at startup — AI physically cannot place orders or transfer funds |
| **Dry-run mode** | `--dry-run` builds the full request but doesn't send it — verify parameters before executing |
| **High-risk gate** | Withdrawals and cancel-all require explicit `--confirm` to prevent accidental AI triggers |

Start with paper trading, verify everything behaves as expected, then switch to live. When creating an API Key, follow least-privilege: don't enable withdrawals unless you need them.

## FAQ

**Q: My AI tool isn't in the list — can I still use it?**

**A:** Any client that supports the MCP protocol can connect via the MCP Server path. Any terminal AI that supports external command calls can use the `bgc` CLI.

**Q: Does querying market data require an API Key?**

**A:** No. Only account operations (checking balance, placing orders, transferring funds) require a Key.

**Q: Will my API Key be exposed to the AI?**

**A:** No. Keys are read only from local environment variables — they never appear in the conversation context and are never uploaded to any server.

**Q: Bitget tools aren't fully loading in Cursor?**

**A:** Cursor has a total limit of ~40 MCP tools. Disable other MCPs, or add `--modules market` to only load the market module.

**Q: Will AI ask for confirmation before placing an order?**

**A:** Yes. Skill guides AI to show a `[CAUTION]` prompt before any write operation and waits for your confirmation. High-risk operations like withdrawals also require the `--confirm` flag.

**Q: Is it free?**

**A:** AgentHub itself is MIT open source and free. Trading fees follow your Bitget account tier.

**Q: Where do I report issues?**

**A:** [GitHub Issues](https://github.com/Bitget-AI/agent_hub/issues) · For security vulnerabilities, email [security@bitget.com](mailto:security@bitget.com) — do not post publicly.

## Links

| Resource | URL |
|-|-|
| Agent Hub (main) | https://github.com/Bitget-AI/agent_hub |
| MCP Server | https://github.com/Bitget-AI/agent-mcp |
| CLI (bgc) | https://github.com/Bitget-AI/agent-cli |
| Skill | https://github.com/Bitget-AI/agent-skill |
| Signal | https://github.com/Bitget-AI/bitget-signal |
| SDK (developers) | https://github.com/Bitget-AI/agent-sdk |
| Bitget API Docs | https://www.bitget.com/api-doc/common/intro |
| API Key Management | https://www.bitget.com/en/api-management |
| Telegram | https://telegram.me/+o1tYqQ_lXxllYjgy |

:::warning{title="Risk disclaimer"}
Crypto and tokenized-stock trading carries substantial risk. AI can make mistakes. You must verify all information yourself and accept full responsibility for outcomes. This tool does not constitute investment advice.
:::