Toobit Trading

Trade crypto on Toobit exchange via natural language. Spot & USDT-M futures trading, market data queries, wallet management. Use when user mentions Toobit, or wants to trade/query crypto on Toobit.

xizhen@xuxizhen

Install

openclaw skills install @xuxizhen/toobit

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:

bash

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

If not set, instruct user:

text

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:

bash

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

text

GET /api/v1/ping

Test API connectivity. No parameters.

Server Time

text

GET /api/v1/time

Returns serverTime in milliseconds.

Exchange Info

text

GET /api/v1/exchangeInfo

Trading rules and symbol information.

Order Book (Depth)

text

GET /quote/v1/depth

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

Recent Trades

text

GET /quote/v1/trades

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

Klines (Candlesticks)

text

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

text

GET /quote/v1/ticker/24hr

Param	Required	Description
symbol	No	Omit for all symbols

Price Ticker

text

GET /quote/v1/ticker/price

Param	Required	Description
symbol	No	Omit for all symbols

Book Ticker

text

GET /quote/v1/ticker/bookTicker

Param	Required	Description
symbol	No	Omit for all symbols

Merged Depth

text

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

text

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

text

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

text

GET /api/v1/account/deposit/address

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

Deposit History

text

GET /api/v1/account/depositOrders

Param	Required	Description
coin	No	Filter by coin
startTime	No	ms timestamp
endTime	No	ms timestamp
fromId	No	Pagination
limit	No	Default 500

Spot Trading Endpoints (SIGNED)

Test New Order

text

POST /api/v1/spot/orderTest

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

Place Order

text

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

text

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

text

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

text

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

text

DELETE /api/v1/spot/cancelOrderByIds

WRITE: Confirm before executing

Param	Required	Description
ids	Yes	Comma-separated order IDs

Query Order

text

GET /api/v1/spot/order

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

Open Orders

text

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

text

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

text

GET /api/v1/account

No parameters. Returns all asset balances.

Trade History

text

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

text

GET /api/v1/account/subAccount

No parameters.

Sub-Account Transfer

text

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

text

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

text

GET /api/v1/account/checkApiKey

No parameters. Returns API key permissions.

Spot User Data Stream

Create Listen Key

text

POST /api/v1/userDataStream

No parameters. Returns listenKey.

Extend Listen Key

text

PUT /api/v1/userDataStream

Param	Required	Description
listenKey	Yes	The listen key to extend

Close Listen Key

text

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

text

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

text

GET /quote/v1/markPrice/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

text

GET /quote/v1/markPrice

Param	Required	Description
symbol	Yes	e.g. BTCUSDT

Funding Rate

text

GET /api/v1/futures/fundingRate

Param	Required	Description
symbol	No	Omit for all symbols

Funding Rate History

text

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

text

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

Param	Required	Description
symbol	No	Omit for all symbols

Contract Price Ticker

text

GET /quote/v1/contract/ticker/price

Param	Required	Description
symbol	No	Omit for all symbols

Index Price

text

GET /quote/v1/index

Param	Required	Description
symbol	No	Omit for all symbols

Contract Book Ticker

text

GET /quote/v1/contract/ticker/bookTicker

Param	Required	Description
symbol	No	Omit for all symbols

Futures Account & Trading (SIGNED)

Change Margin Type

text

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

text

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

text

GET /api/v1/futures/accountLeverage

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

Place Futures Order

text

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

text

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

text

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

text

DELETE /api/v1/futures/order

WRITE: Confirm before executing

Param	Required	Description
orderId	Conditional	Order ID
origClientOrderId	Conditional	Custom order ID
type	No	Order type
symbol	No	Trading pair
category	No	Default 0

Batch Cancel Futures Orders

text

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

text

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

text

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

text

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

text

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

text

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

text

GET /api/v1/futures/balance

Param	Required	Description
category	No	Default 0

Adjust Isolated Margin

text

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

text

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

text

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

text

GET /api/v1/futures/commissionRate

Param	Required	Description
symbol	Yes	e.g. BTCUSDT

Today's PnL

text

GET /api/v1/futures/todayPnl

Param	Required	Description
category	No	Default 0

Sub-Account Info

text

GET /api/v1/subAccount

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

Sub-Account Transfer

text

POST /api/v1/subAccount/transfer

WRITE: Confirm before executing

Same params as spot sub-account transfer.

Account Balance Flow

text

GET /api/v1/account/balanceFlow

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

Futures User Data Stream

Create Listen Key

text

POST /api/v1/listenKey

Param	Required	Description
category	No	Default 0

Extend Listen Key

text

PUT /api/v1/listenKey

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

Close Listen Key

text

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