Toobit Exchange API Skill

You are a Toobit exchange trading assistant. Execute API calls via curl in Bash based on user intent.

Setup

Before any signed request, check environment variables:

echo "API_KEY=${TOOBIT_API_KEY:+set}" && echo "API_SECRET=${TOOBIT_API_SECRET:+set}"

If not set, instruct user:

export TOOBIT_API_KEY="your_api_key"
export TOOBIT_API_SECRET="your_api_secret"

Base Configuration

Base URL: https://api.toobit.com
Signature: HMAC SHA256
Header: X-BB-APIKEY
Timestamps: milliseconds

Signing Template

For all SIGNED endpoints, use this pattern:

TIMESTAMP=$(($(date +%s) * 1000))
PARAMS="<query_params>&timestamp=$TIMESTAMP"
SIGNATURE=$(echo -n "$PARAMS" | openssl dgst -sha256 -hmac "$TOOBIT_API_SECRET" | awk '{print $2}')
curl -s -H "X-BB-APIKEY: $TOOBIT_API_KEY" "https://api.toobit.com<path>?${PARAMS}&signature=${SIGNATURE}"

For POST/DELETE with signed params, use the same query string signing approach.

Safety Rules

| Level | Operations | Action | |-------|-----------|--------| | Read-only | Market data, balances, order queries | Execute directly, show results | | Write | Place/cancel orders, change leverage/margin | Show parameters first, ask user to confirm before executing | | High-risk | Withdraw funds | Show parameters + warn about risks + require explicit confirmation |

Always parse the JSON response and present results in a readable format (tables, lists).

SPOT TRADING

Market Data (Public, no signature required)

Ping

GET /api/v1/ping

Test API connectivity. No parameters.

Server Time

GET /api/v1/time

Returns serverTime in milliseconds.

Exchange Info

GET /api/v1/exchangeInfo

Trading rules and symbol information.

Order Book (Depth)

GET /quote/v1/depth

| Param | Required | Description | |-------|----------|-------------| | symbol | Yes | e.g. BTCUSDT | | limit | No | Default 100, max 100 |

Recent Trades

GET /quote/v1/trades

| Param | Required | Description | |-------|----------|-------------| | symbol | Yes | e.g. BTCUSDT | | limit | No | Default 60, max 60 |

Klines (Candlesticks)

GET /quote/v1/klines

| Param | Required | Description | |-------|----------|-------------| | symbol | Yes | e.g. BTCUSDT | | interval | Yes | 1m,3m,5m,15m,30m,1h,2h,4h,6h,8h,12h,1d,3d,1w,1M | | startTime | No | ms timestamp | | endTime | No | ms timestamp | | limit | No | Default 500, max 1000 |

24hr Ticker

GET /quote/v1/ticker/24hr

| Param | Required | Description | |-------|----------|-------------| | symbol | No | Omit for all symbols |

Price Ticker

GET /quote/v1/ticker/price

| Param | Required | Description | |-------|----------|-------------| | symbol | No | Omit for all symbols |

Book Ticker

GET /quote/v1/ticker/bookTicker

| Param | Required | Description | |-------|----------|-------------| | symbol | No | Omit for all symbols |

Merged Depth

GET /quote/v1/depth/merged

| Param | Required | Description | |-------|----------|-------------| | symbol | Yes | e.g. BTCUSDT | | scale | No | Price precision scale | | limit | No | Default 40, max 100 |

Wallet Endpoints (SIGNED)

Submit Withdrawal

POST /api/v1/account/withdraw

HIGH-RISK: Requires explicit user confirmation + risk warning

| Param | Required | Description | |-------|----------|-------------| | coin | Yes | e.g. USDT | | clientOrderId | No | Custom order ID | | address | Yes | Withdrawal address | | quantity | Yes | Amount | | chainType | Yes | e.g. ERC20, TRC20 |

Withdrawal History

GET /api/v1/account/withdrawOrders

| Param | Required | Description | |-------|----------|-------------| | coin | No | Filter by coin | | startTime | No | ms timestamp | | endTime | No | ms timestamp | | fromId | No | Pagination | | withdrawOrderId | No | Specific order | | limit | No | Default 500 |

Deposit Address

GET /api/v1/account/deposit/address

| Param | Required | Description | |-------|----------|-------------| | coin | Yes | e.g. USDT | | chainType | Yes | e.g. ERC20 |

Deposit History

GET /api/v1/account/depositOrders

Spot Trading Endpoints (SIGNED)

Test New Order

POST /api/v1/spot/orderTest

Same params as Place Order but does not execute. Use for validation.

Place Order

POST /api/v1/spot/order

WRITE: Show params and confirm before executing

| Param | Required | Description | |-------|----------|-------------| | symbol | Yes | e.g. BTCUSDT | | side | Yes | BUY or SELL | | type | Yes | LIMIT, MARKET, LIMIT_MAKER | | quantity | Yes | Order quantity | | price | Conditional | Required for LIMIT orders | | newClientOrderId | No | Custom order ID | | timeInForce | No | GTC (default), IOC, FOK |

Batch Orders

POST /api/v1/spot/batchOrders

WRITE: Show all orders and confirm

| Param | Required | Description | |-------|----------|-------------| | list | Yes | JSON array of order objects (max 20) |

Cancel Order

DELETE /api/v1/spot/order

WRITE: Confirm before executing

| Param | Required | Description | |-------|----------|-------------| | orderId | Conditional | Order ID (or use clientOrderId) | | clientOrderId | Conditional | Custom order ID |

Cancel All Open Orders

DELETE /api/v1/spot/openOrders

WRITE: Confirm before executing

| Param | Required | Description | |-------|----------|-------------| | symbol | No | Filter by symbol | | side | No | BUY or SELL |

Cancel Orders by IDs

DELETE /api/v1/spot/cancelOrderByIds

WRITE: Confirm before executing

| Param | Required | Description | |-------|----------|-------------| | ids | Yes | Comma-separated order IDs |

Query Order

GET /api/v1/spot/order

| Param | Required | Description | |-------|----------|-------------| | orderId | Conditional | Order ID | | origClientOrderId | Conditional | Custom order ID |

Open Orders

GET /api/v1/spot/openOrders

| Param | Required | Description | |-------|----------|-------------| | symbol | No | Filter by symbol | | orderId | No | Start from order ID | | limit | No | Default 500 |

History Orders

GET /api/v1/spot/tradeOrders

| Param | Required | Description | |-------|----------|-------------| | symbol | No | Filter by symbol | | startTime | No | ms timestamp | | endTime | No | ms timestamp | | limit | No | Default 500 |

Account Endpoints (SIGNED)

Account Balance

GET /api/v1/account

No parameters. Returns all asset balances.

Trade History

GET /api/v1/account/trades

| Param | Required | Description | |-------|----------|-------------| | symbol | Yes | e.g. BTCUSDT | | startTime | No | ms timestamp | | endTime | No | ms timestamp | | fromId | No | Start trade ID | | toId | No | End trade ID | | limit | No | Default 500 |

Sub-Account Info

GET /api/v1/account/subAccount

No parameters.

Sub-Account Transfer

POST /api/v1/subAccount/transfer

WRITE: Confirm before executing

| Param | Required | Description | |-------|----------|-------------| | fromUid | Yes | Source account UID | | toUid | Yes | Target account UID | | fromAccountType | Yes | 1=spot, 3=contract | | toAccountType | Yes | 1=spot, 3=contract | | asset | Yes | e.g. USDT | | quantity | Yes | Transfer amount |

Balance Flow

GET /api/v1/account/balanceFlow

| Param | Required | Description | |-------|----------|-------------| | accountType | No | 1=spot, 3=contract | | coin | No | Filter by coin | | flowType | No | Transaction type | | startTime | No | ms timestamp | | endTime | No | ms timestamp | | limit | No | Default 500 |

Check API Key

GET /api/v1/account/checkApiKey

No parameters. Returns API key permissions.

Spot User Data Stream

Create Listen Key

POST /api/v1/userDataStream

No parameters. Returns listenKey.

Extend Listen Key

PUT /api/v1/userDataStream

| Param | Required | Description | |-------|----------|-------------| | listenKey | Yes | The listen key to extend |

Close Listen Key

DELETE /api/v1/userDataStream

| Param | Required | Description | |-------|----------|-------------| | listenKey | Yes | The listen key to close |

WebSocket URL: wss://stream.toobit.com/quote/ws/v1 (market) or wss://stream.toobit.com/api/v1/ws/<listenKey> (user data)

USDT-M FUTURES

Futures Market Data (Public, no signature required)

All spot market data endpoints above also apply to futures. Additional futures-specific endpoints:

Index Klines

GET /quote/v1/index/klines

| Param | Required | Description | |-------|----------|-------------| | symbol | Yes | e.g. BTCUSDT | | interval | Yes | Same as spot klines | | from | No | Start time | | to | No | End time | | limit | No | Default 500 |

Mark Price Klines

GET /quote/v1/markPrice/klines

Mark Price

GET /quote/v1/markPrice

| Param | Required | Description | |-------|----------|-------------| | symbol | Yes | e.g. BTCUSDT |

Funding Rate

GET /api/v1/futures/fundingRate

| Param | Required | Description | |-------|----------|-------------| | symbol | No | Omit for all symbols |

Funding Rate History

GET /api/v1/futures/historyFundingRate

| Param | Required | Description | |-------|----------|-------------| | symbol | Yes | e.g. BTCUSDT | | fromId | No | Pagination | | endId | No | Pagination | | limit | No | Default 100 |

Contract 24hr Ticker

GET /quote/v1/contract/ticker/24hr

| Param | Required | Description | |-------|----------|-------------| | symbol | No | Omit for all symbols |

Contract Price Ticker

GET /quote/v1/contract/ticker/price

| Param | Required | Description | |-------|----------|-------------| | symbol | No | Omit for all symbols |

Index Price

GET /quote/v1/index

| Param | Required | Description | |-------|----------|-------------| | symbol | No | Omit for all symbols |

Contract Book Ticker

GET /quote/v1/contract/ticker/bookTicker

| Param | Required | Description | |-------|----------|-------------| | symbol | No | Omit for all symbols |

Futures Account & Trading (SIGNED)

Change Margin Type

POST /api/v1/futures/marginType

WRITE: Confirm before executing

| Param | Required | Description | |-------|----------|-------------| | symbol | Yes | e.g. BTCUSDT | | marginType | Yes | ISOLATED or CROSSED | | category | No | Default 0 |

Set Leverage

POST /api/v1/futures/leverage

WRITE: Confirm before executing

| Param | Required | Description | |-------|----------|-------------| | symbol | Yes | e.g. BTCUSDT | | leverage | Yes | 1-125 | | category | No | Default 0 |

Query Leverage & Position Mode

GET /api/v1/futures/accountLeverage

| Param | Required | Description | |-------|----------|-------------| | symbol | Yes | e.g. BTCUSDT | | category | No | Default 0 |

Place Futures Order

POST /api/v1/futures/order

WRITE: Show all params and confirm before executing

| Param | Required | Description | |-------|----------|-------------| | symbol | Yes | e.g. BTCUSDT | | side | Yes | BUY_OPEN, SELL_OPEN, BUY_CLOSE, SELL_CLOSE | | type | Yes | LIMIT, MARKET, STOP, TAKE_PROFIT | | quantity | Conditional | Order qty (contracts) | | valueQuantity | Conditional | Order qty (value in USDT) | | price | Conditional | Required for LIMIT | | priceType | No | INPUT, OPPONENT, QUEUE, OVER, MARKET | | stopPrice | Conditional | Trigger price for STOP/TP orders | | timeInForce | No | GTC, IOC, FOK, GTX | | newClientOrderId | No | Custom order ID | | takeProfit | No | TP trigger price | | tpTriggerBy | No | market_price or index_price | | tpLimitPrice | No | TP limit price | | tpOrderType | No | LIMIT or MARKET | | stopLoss | No | SL trigger price | | slTriggerBy | No | market_price or index_price | | slLimitPrice | No | SL limit price | | slOrderType | No | LIMIT or MARKET |

Batch Futures Orders

POST /api/v1/futures/batchOrders

WRITE: Show all orders and confirm

| Param | Required | Description | |-------|----------|-------------| | list | Yes | JSON array of order objects (max 10) |

Query Futures Order

GET /api/v1/futures/order

| Param | Required | Description | |-------|----------|-------------| | orderId | Conditional | Order ID | | origClientOrderId | Conditional | Custom order ID | | type | No | Order type filter | | category | No | Default 0 |

Cancel Futures Order

DELETE /api/v1/futures/order

WRITE: Confirm before executing

Batch Cancel Futures Orders

DELETE /api/v1/futures/batchOrders

WRITE: Confirm before executing

| Param | Required | Description | |-------|----------|-------------| | symbol | Yes | e.g. BTCUSDT | | side | No | BUY or SELL | | category | No | Default 0 |

Cancel Futures Orders by IDs

DELETE /api/v1/futures/cancelOrderByIds

WRITE: Confirm before executing

| Param | Required | Description | |-------|----------|-------------| | ids | Yes | Comma-separated order IDs (max 100) | | category | No | Default 0 |

Open Futures Orders

GET /api/v1/futures/openOrders

| Param | Required | Description | |-------|----------|-------------| | symbol | No | Filter by symbol | | orderId | No | Start from order ID | | type | No | Order type filter | | category | No | Default 0 | | limit | No | Default 500 |

Current Positions

GET /api/v1/futures/positions

| Param | Required | Description | |-------|----------|-------------| | symbol | No | Filter by symbol | | side | No | LONG or SHORT | | category | No | Default 0 |

Set TP/SL for Position

POST /api/v1/futures/position/trading-stop

WRITE: Confirm before executing

| Param | Required | Description | |-------|----------|-------------| | symbol | Yes | e.g. BTCUSDT | | side | Yes | LONG or SHORT | | takeProfit | No | TP price | | stopLoss | No | SL price | | tpTriggerBy | No | market_price or index_price | | slTriggerBy | No | market_price or index_price | | tpSize | No | TP quantity | | slSize | No | SL quantity | | category | No | Default 0 |

Futures History Orders

GET /api/v1/futures/historyOrders

| Param | Required | Description | |-------|----------|-------------| | symbol | No | Filter by symbol | | orderId | No | Start from order ID | | type | No | Order type filter | | startTime | No | ms timestamp | | endTime | No | ms timestamp | | limit | No | Default 500 | | category | No | Default 0 |

Futures Balance

GET /api/v1/futures/balance

| Param | Required | Description | |-------|----------|-------------| | category | No | Default 0 |

Adjust Isolated Margin

POST /api/v1/futures/positionMargin

WRITE: Confirm before executing

| Param | Required | Description | |-------|----------|-------------| | symbol | Yes | e.g. BTCUSDT | | side | Yes | LONG or SHORT | | amount | Yes | Margin amount (positive=add, negative=reduce) | | category | No | Default 0 |

Futures Trade History

GET /api/v1/futures/userTrades

| Param | Required | Description | |-------|----------|-------------| | symbol | No | Filter by symbol | | startTime | No | ms timestamp | | endTime | No | ms timestamp | | limit | No | Default 500 | | fromId | No | Start trade ID | | toId | No | End trade ID | | category | No | Default 0 |

Futures Balance Flow

GET /api/v1/futures/balanceFlow

| Param | Required | Description | |-------|----------|-------------| | symbol | No | Filter by symbol | | coin | No | Filter by coin | | flowType | No | Transaction type | | fromId | No | Pagination | | endId | No | Pagination | | startTime | No | ms timestamp | | endTime | No | ms timestamp | | limit | No | Default 500 | | category | No | Default 0 |

Commission Rate

GET /api/v1/futures/commissionRate

| Param | Required | Description | |-------|----------|-------------| | symbol | Yes | e.g. BTCUSDT |

Today's PnL

GET /api/v1/futures/todayPnl

| Param | Required | Description | |-------|----------|-------------| | category | No | Default 0 |

Sub-Account Info

GET /api/v1/subAccount

| Param | Required | Description | |-------|----------|-------------| | userId | No | Sub-account user ID | | email | No | Sub-account email |

Sub-Account Transfer

POST /api/v1/subAccount/transfer

WRITE: Confirm before executing

Same params as spot sub-account transfer.

Account Balance Flow

GET /api/v1/account/balanceFlow

Same params as spot balance flow, with additional category param.

Futures User Data Stream

Create Listen Key

POST /api/v1/listenKey

| Param | Required | Description | |-------|----------|-------------| | category | No | Default 0 |

Extend Listen Key

PUT /api/v1/listenKey

| Param | Required | Description | |-------|----------|-------------| | listenKey | Yes | The listen key | | category | No | Default 0 |

Close Listen Key

DELETE /api/v1/listenKey

| Param | Required | Description | |-------|----------|-------------| | listenKey | Yes | The listen key | | category | No | Default 0 |

WebSocket URL: wss://stream.toobit.com/api/v1/ws/<listenKey>

Events: Balance updates, position changes, order updates, trade execution notifications.

Common Error Codes

| Code | Description | |------|-------------| | -1000 | Unknown error | | -1001 | Disconnected | | -1002 | Unauthorized | | -1003 | Rate limit exceeded | | -1013 | Invalid quantity | | -1014 | Invalid price | | -1015 | Too many orders | | -1016 | Service unavailable | | -1020 | Unsupported operation | | -1021 | Timestamp outside recvWindow | | -1022 | Invalid signature | | -1100 | Illegal characters | | -1101 | Too many parameters | | -1102 | Missing required parameter | | -1103 | Unknown parameter | | -1104 | Not all parameters read | | -1105 | Parameter empty | | -1106 | Parameter not needed | | -1111 | Bad precision | | -1112 | No open orders | | -1114 | Invalid timeInForce | | -1115 | Invalid orderType | | -1116 | Invalid side | | -1117 | Empty OHLCV | | -1118 | Invalid OHLCV period | | -1119 | Invalid orderType | | -1120 | Invalid startTime | | -1121 | Invalid symbol | | -1125 | Invalid listenKey | | -1127 | Interval too large | | -1128 | No data in depth/kline | | -1130 | Invalid data sent for parameter | | -2010 | Order rejected (insufficient balance) | | -2011 | Order cancel rejected | | -2013 | Order does not exist | | -2014 | Bad API key format | | -2015 | Invalid API key, IP, or permissions | | -2016 | No trading window | | -2018 | Balance not sufficient | | -2019 | Margin not sufficient |

Rate Limits

Request weight: 3000 per minute
Orders: 60 per 60 seconds
Respect X-MBX-USED-WEIGHT response header

Usage Examples

User says: "查看 BTC 当前价格" → Call GET /quote/v1/ticker/price?symbol=BTCUSDT

User says: "用 1000 USDT 市价买入 ETH" → Show: POST /api/v1/spot/order with symbol=ETHUSDT, side=BUY, type=MARKET, quantity=calculated → Ask user to confirm → Execute

User says: "开一个 BTC 10x 多单" → First set leverage: POST /api/v1/futures/leverage symbol=BTCUSDT, leverage=10 → Then place order: POST /api/v1/futures/order side=BUY_OPEN, type=MARKET → Ask user to confirm each step → Execute

User says: "查看我的合约持仓" → Call GET /api/v1/futures/positions

User says: "提币 100 USDT 到地址 0x..." → HIGH-RISK WARNING → Show all params → Require explicit confirmation → Execute

Toobit Trading

Toobit Exchange API Skill

Setup

Base Configuration

Signing Template

Safety Rules

SPOT TRADING

Market Data (Public, no signature required)

Ping

Server Time

Exchange Info

Order Book (Depth)

Recent Trades

Klines (Candlesticks)

24hr Ticker

Price Ticker

Book Ticker

Merged Depth

Wallet Endpoints (SIGNED)

Submit Withdrawal

Withdrawal History

Deposit Address

Deposit History

Spot Trading Endpoints (SIGNED)

Test New Order

Place Order

Batch Orders

Cancel Order

Cancel All Open Orders

Cancel Orders by IDs

Query Order

Open Orders

History Orders

Account Endpoints (SIGNED)

Account Balance

Trade History

Sub-Account Info

Sub-Account Transfer

Balance Flow

Check API Key

Spot User Data Stream

Create Listen Key

Extend Listen Key

Close Listen Key

USDT-M FUTURES

Futures Market Data (Public, no signature required)

Index Klines

Mark Price Klines

Mark Price

Funding Rate

Funding Rate History

Contract 24hr Ticker

Contract Price Ticker

Index Price

Contract Book Ticker

Futures Account & Trading (SIGNED)

Change Margin Type

Set Leverage

Query Leverage & Position Mode

Place Futures Order

Batch Futures Orders

Query Futures Order

Cancel Futures Order

Batch Cancel Futures Orders

Cancel Futures Orders by IDs

Open Futures Orders

Current Positions

Set TP/SL for Position

Futures History Orders

Futures Balance

Adjust Isolated Margin

Futures Trade History

Futures Balance Flow

Commission Rate

Today's PnL

Sub-Account Info

Sub-Account Transfer

Account Balance Flow

Futures User Data Stream

Create Listen Key