Bitkub Trading Mcp

Replace the two placeholder values with your real Bitkub key + secret. See Add your API key for how to generate them.

claude mcp add bitkub-trading-mcp \
  -e BITKUB_API_KEY=your_real_key_here \
  -e BITKUB_API_SECRET=your_real_secret_here \
  -- npx -y bitkub-trading-mcp

| Tool | Endpoint |
| ------------------- | -------------------------------------------------------- |
| bitkub_status | GET /api/status |
| bitkub_servertime | GET /api/v3/servertime (ms) |
| bitkub_symbols | GET /api/v3/market/symbols |
| bitkub_ticker | GET /api/v3/market/ticker?sym= — omit sym to fetch ALL symbols in one call |
| bitkub_bids | GET /api/v3/market/bids?sym=&lmt= |
| bitkub_asks | GET /api/v3/market/asks?sym=&lmt= |
| bitkub_depth | GET /api/v3/market/depth?sym=&lmt= |
| bitkub_trades | GET /api/v3/market/trades?sym=&lmt= |
| bitkub_tv_history | GET /tradingview/history?symbol=&resolution=&from=&to= |

Bitkub v4 is used wherever it has an equivalent; v3 endpoints are kept only where v4 has not yet shipped one. v4 uses GET with query params; v3 mostly used POST with body. Auth signing is identical for v3 and v4.

| Tool | Ver | Method | Endpoint | Args (zod-validated) |
| ----------------------------- | --- | ------ | ------------------------------------- | ------------------------------------------------------------------- |
| bitkub_balances | v4 | GET | /api/v4/wallet/balances | segment? ("funding") |
| bitkub_crypto_addresses | v4 | GET | /api/v4/crypto/addresses | page? (≥1), limit? (1–200), symbol?, network?, memo? |
| bitkub_crypto_deposits | v4 | GET | /api/v4/crypto/deposits | page?, limit? (1–200), symbol?, status?, created_start?, created_end? (ISO 8601) |
| bitkub_crypto_withdraws | v4 | GET | /api/v4/crypto/withdraws | same shape as bitkub_crypto_deposits (read-only history) |
| bitkub_fiat_accounts | v4 | GET | /api/v4/fiat/accounts | page? (1–100), limit? (1–100) — must be paired |
| bitkub_fiat_deposits | v4 | GET | /api/v4/fiat/deposit/history | page?, limit? (1–100) — must be paired |
| bitkub_fiat_withdraws | v4 | GET | /api/v4/fiat/withdraw/history | page?, limit? (1–100) — must be paired (read-only history) |
| bitkub_my_open_orders | v3 | GET | /api/v3/market/my-open-orders | sym |
| bitkub_my_order_history | v3 | GET | /api/v3/market/my-order-history | sym, p?, lmt?, start?, end? |
| bitkub_order_info | v3 | GET | /api/v3/market/order-info | sym, id, sd, hash? |
| bitkub_user_limits | v3 | POST | /api/v3/user/limits | (none) |
| bitkub_user_trading_credits | v3 | POST | /api/v3/user/trading-credits | (none) |

Auth signing (v3 and v4): X-BTK-APIKEY, X-BTK-TIMESTAMP (Unix ms), X-BTK-SIGN = HMAC-SHA256 of {ts}{METHOD}{path}{?query | body}, hex lowercase. For POSTs the exact JSON bytes sent on the wire are signed.

References: <https://github.com/bitkub/bitkub-official-api-docs/blob/master/restful-api.md> · <https://github.com/bitkub/bitkub-official-api-docs/blob/master/restful-api-v4.md>

Each call opens a WebSocket, collects events for a bounded duration, then closes. Stateless — no long-lived subscriptions, no MCP notifications.

| Tool | Stream | Auth | Default / max duration |
| ---------------------------- | ------------------------------- | -------- | ---------------------- |
| bitkub_ws_ticker_snapshot | market.ticker.<sym> (public) | none | 10 s / 60 s |
| bitkub_ws_order_updates | order_update (private) | required | 30 s / 120 s |
| bitkub_ws_match_updates | match_update (private) | required | 30 s / 120 s |

Args (every tool):

- duration_ms? — int, milliseconds. Defaults and caps as in the table above.
- bitkub_ws_ticker_snapshot.sym — required (e.g. btc_thb).
- bitkub_ws_order_updates.sym / bitkub_ws_match_updates.sym — optional post-filter on data.symbol.

Response shape:

{
  "events": [/ raw Bitkub payloads, in receive order /],
  "count": 0,
  "duration_ms_actual": 30000,
  "stream": "order_update",
  "started_at": "2026-05-10T17:00:00.000Z",
  "ended_at":   "2026-05-10T17:00:30.000Z"
}

If the WS closes before the window ends, the response also includes closed_early: true and closed_reason: "...".

Race-condition note: the private streams only deliver events that occur AFTER subscribe is sent. If you want to observe an order's full lifecycle, call bitkub_ws_order_updates in parallel with the order placement — or call bitkub_order_info afterward for the authoritative final state.

Concurrency cap: Bitkub permits at most 5 concurrent private WebSocket connections per API key. The server detects "too many concurrent" closes and surfaces them with a clear message.

Excluded streams (intentional): the public market.trade. channel (Bitkub deprecates it 2026-05-18) and the public orderbook channel (uses numeric pairing_id instead of symbol; REST bitkub_depth is a better fit).

| Workflow | Tools used (parallel) |
|---|---|
| "Show me BTC/THB depth, last 50 trades, and watch ticker for 10s. Tell me if it's a good time to buy." | bitkub_depth + bitkub_trades + bitkub_ws_ticker_snapshot |
| "Audit my last 24h: balances now, all crypto deposits since yesterday, and any open orders." | bitkub_balances + bitkub_crypto_deposits (with created_start) + bitkub_my_open_orders (per symbol) |
| "My order is stuck at 'open' in the UI. Get its REST state AND watch order_updates for 30s to see if anything moves."* | bitkub_order_info + bitkub_ws_order_updates |