Skills

bitmart-exchange-spot

Installation
SKILL.md

BitMart Spot Trading

Overview

# Category API Endpoint Type Description
1 Market Data GET /spot/quotation/v3/ticker READ Get single pair ticker
2 Market Data GET /spot/quotation/v3/tickers READ Get all pair tickers
3 Market Data GET /spot/quotation/v3/books READ Order book depth (max 50)
4 Market Data GET /spot/quotation/v3/trades READ Recent public trades (max 50)
5 Market Data GET /spot/quotation/v3/klines READ Historical K-line/candlestick
6 Market Data GET /spot/quotation/v3/lite-klines READ Latest K-line data
7 Market Data GET /spot/v1/symbols/details READ Trading pair details
8 Market Data GET /spot/v1/symbols READ Trading pair list
9 Market Data GET /spot/v1/currencies READ All supported currencies
10 Account GET /account/v1/wallet READ Account balance (all wallets)
11 Account GET /spot/v1/wallet READ Spot wallet balance
12 Account GET /spot/v1/trade_fee READ Actual trade fee rate
13 Account GET /spot/v1/user_fee READ Base fee rate (account tier)
14 Margin Account GET /spot/v1/margin/isolated/account READ Isolated margin account details
15 Margin Account GET /spot/v1/margin/isolated/pairs READ Borrowing rate & amount
16 Margin Account GET /spot/v1/margin/isolated/borrow_record READ Borrow record
17 Margin Account GET /spot/v1/margin/isolated/repay_record READ Repayment record
18 Trading POST /spot/v2/submit_order WRITE Place single order
19 Trading POST /spot/v1/margin/submit_order WRITE Place margin order
20 Trading POST /spot/v4/batch_orders WRITE Batch orders (max 10)
21 Trading POST /spot/v3/cancel_order WRITE Cancel single order
22 Trading POST /spot/v4/cancel_orders WRITE Cancel multiple orders
23 Trading POST /spot/v4/cancel_all WRITE Cancel all open orders
24 Order Query POST /spot/v4/query/order READ Query order by order ID
25 Order Query POST /spot/v4/query/client-order READ Query by client order ID
26 Order Query POST /spot/v4/query/open-orders READ All open orders
27 Order Query POST /spot/v4/query/history-orders READ Historical orders
28 Order Query POST /spot/v4/query/trades READ Account trade history
29 Order Query POST /spot/v4/query/order-trades READ Trades for specific order
30 Margin Loan POST /spot/v1/margin/isolated/borrow WRITE Margin borrow (isolated)
31 Margin Loan POST /spot/v1/margin/isolated/repay WRITE Margin repay (isolated)
32 Margin Loan POST /spot/v1/margin/isolated/transfer WRITE Margin asset transfer
33 System GET /system/time READ Get server time (milliseconds)
34 System GET /system/service READ Get system service status / maintenance

Skill Routing

User Intent Correct Skill
Spot buy/sell, order management, balance, fee rates bitmart-exchange-spot (this skill)
Futures/contract trading, leverage, TP/SL, plan orders bitmart-exchange-futures

Authentication

Credential Check (Before Any Private API Call)

Before calling any authenticated endpoint, verify credentials are available:

  1. Check for environment variables:
    • BITMART_API_KEY — API key
    • BITMART_API_SECRET — Secret key
    • BITMART_API_MEMO — Memo string
  2. Or check for config file: ~/.bitmart/config.toml 
    [default]
api_key = "your-api-key"
api_secret = "your-secret-key"
memo = "your-memo"
  3. If missing: STOP. Guide user to set up credentials. Do NOT proceed with any authenticated call.

Key display rules: When displaying credentials back to the user, show only the first 5 and last 4 characters (e.g., bmk12...9xyz). NEVER display full secret or memo values.

Auth Levels

Level When Headers Required
NONE Public market data (endpoints 1-9) None
KEYED Read-only private data — balances, fees, margin account, borrow/repay records (endpoints 10-17) X-BM-KEY
SIGNED Write operations and order queries (endpoints 18-32) X-BM-KEY + X-BM-SIGN + X-BM-TIMESTAMP

Signature Generation

timestamp = current UTC time in milliseconds
message   = "{timestamp}#{memo}#{request_body_json}"
signature = HMAC-SHA256(secret_key, message) → hex string
  • For POST requests: request_body_json is the JSON body string.
  • For GET requests: request_body_json is an empty string "".

Required Headers (SIGNED)

Header Value
Content-Type application/json
X-BM-KEY API key
X-BM-SIGN Hex-encoded HMAC-SHA256 signature
X-BM-TIMESTAMP Current UTC timestamp in milliseconds
User-Agent bitmart-skills/spot/v2026.3.23 — identifies requests from this skill for analytics

See references/authentication.md for full setup guide and troubleshooting.

API Base

  • Base URL: https://api-cloud.bitmart.com
  • Symbol Format: BTC_USDT (base_quote, underscore separated)

Standard Response Format

Success:

{
  "code": 1000,
  "message": "OK",
  "trace": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": { ... }
}

Error:

{
  "code": 50000,
  "message": "Bad Request",
  "trace": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": null
}

Important: code == 1000 means success. Any other code is an error. Important: Spot business error codes are endpoint/version specific. Do not assume the same numeric code has the same meaning across all spot flows.

GET requests: Parameters go in the query string. POST requests: Parameters go in the JSON body.

Rate Limits

Endpoint Rate Target
GET /spot/quotation/v3/ticker 15 req/2sec IP
GET /spot/quotation/v3/tickers 10 req/2sec IP
GET /spot/quotation/v3/lite-klines 15 req/2sec IP
GET /spot/quotation/v3/klines 10 req/2sec IP
GET /spot/quotation/v3/books 15 req/2sec IP
GET /spot/quotation/v3/trades 15 req/2sec IP
GET /spot/v1/currencies 8 req/2sec IP
GET /spot/v1/symbols 8 req/2sec IP
GET /spot/v1/symbols/details 12 req/2sec IP
Balance 12 req/2sec KEY
Trade Fee / User Fee 2 req/2sec KEY
Margin Account 12 req/2sec KEY
Margin Pairs 2 req/2sec KEY
Borrow / Repay Records 150 req/2sec KEY
Place Order (spot) 40 req/2sec UID
Batch Place Orders (/spot/v4/batch_orders) 40 req/2sec UID
Place Order (margin) 20 req/1sec UID
Cancel Order 40 req/2sec UID
Cancel Multiple (/spot/v4/cancel_orders) 40 req/2sec UID
Cancel All 1 req/3sec UID
Query Order by ID 50 req/2sec KEY
Query by Client Order ID (/spot/v4/query/client-order) 50 req/2sec KEY
Open / History / Trades 12 req/2sec KEY
Order-Trades 12 req/2sec KEY
Margin Borrow / Repay / Transfer 2 req/2sec KEY
GET /system/time 10 req/sec IP
GET /system/service 10 req/sec IP

Rate limit response headers:

  • X-BM-RateLimit-Remaining — Number of requests already used in the current window
  • X-BM-RateLimit-Limit — Maximum allowed requests in the current window
  • X-BM-RateLimit-Reset — Current time window length (seconds)

Warning: If X-BM-RateLimit-Remaining >= X-BM-RateLimit-Limit, stop calling immediately and wait for reset to avoid sending one extra over-limit request.

If rate limited (HTTP 429), wait for the reset period before retrying.

Quickstart

Example 1: Get BTC price (no auth)

curl -s -H "User-Agent: bitmart-skills/spot/v2026.3.23" 'https://api-cloud.bitmart.com/spot/quotation/v3/ticker?symbol=BTC_USDT'

Example 2: Get account balance (KEYED)

curl -s -H "X-BM-KEY: $BITMART_API_KEY" \
  -H "User-Agent: bitmart-skills/spot/v2026.3.23" \
  'https://api-cloud.bitmart.com/account/v1/wallet'

Example 3: Place limit buy order (SIGNED)

TIMESTAMP=$(date +%s000)
BODY='{"symbol":"BTC_USDT","side":"buy","type":"limit","size":"0.001","price":"60000"}'
SIGN=$(echo -n "${TIMESTAMP}#${BITMART_API_MEMO}#${BODY}" | openssl dgst -sha256 -hmac "$BITMART_API_SECRET" | awk '{print $NF}')
curl -s -X POST 'https://api-cloud.bitmart.com/spot/v2/submit_order' \
  -H "User-Agent: bitmart-skills/spot/v2026.3.23" \
  -H "Content-Type: application/json" \
  -H "X-BM-KEY: $BITMART_API_KEY" \
  -H "X-BM-SIGN: $SIGN" \
  -H "X-BM-TIMESTAMP: $TIMESTAMP" \
  -d "$BODY"

API Reference

See references/api-reference.md for full endpoint documentation with parameters, examples, and response formats. See references/scenarios.md for step-by-step execution flows for common spot tasks such as market buy, limit sell, batch orders, and cancel-replace.

Reference: Order Types

Type Description
limit Execute at specified price or better
market Execute immediately at best available price
limit_maker Post-only; rejected if it would immediately match (ensures maker fee)
ioc Immediate-or-cancel; unfilled portion is canceled immediately

Reference: Order Sides

Side Description
buy Buy base currency with quote currency
sell Sell base currency for quote currency

Reference: Order States

State Description
new Order accepted, not yet filled
partially_filled Partially executed, still open
filled Fully executed
canceled Canceled by user
partially_canceled Partially filled, then canceled

Reference: Cancel Sources

Source Description
"" (empty) Not canceled
user Canceled by user
system Canceled by system (e.g., insufficient balance)
stp Canceled by self-trade prevention

Reference: STP Modes

Mode Description
none No self-trade prevention
cancel_maker Cancel the resting (maker) order if self-trade detected
cancel_taker Cancel the incoming (taker) order if self-trade detected
cancel_both Cancel both orders if self-trade detected

Reference: Trade Roles

Role Description
taker Order matched immediately against resting order
maker Order rested on book and was matched later

Reference: Parameter Naming Convention

CRITICAL — Wrong case = silently ignored field. The API does NOT return an error for misnamed params; it simply ignores them, causing unexpected behavior or wrong results. Always verify the endpoint version before constructing any request body.

API Version Convention Examples
v1-v3 snake_case client_order_id, order_id, start_time
v4 camelCase clientOrderId, orderId, orderMode, startTime

Mixed-case exceptions (must be memorized):

  • POST /spot/v2/submit_order: stpMode (camelCase) alongside client_order_id (snake_case)
  • POST /spot/v1/margin/submit_order: clientOrderId (camelCase in a v1 endpoint)

Reference: K-Line Steps

Step (minutes) Description
1 1-minute candles
5 5-minute candles
15 15-minute candles
30 30-minute candles
60 1-hour candles
120 2-hour candles
240 4-hour candles
1440 1-day candles
10080 1-week candles
43200 1-month candles

Operation Flow

Step 0: Credential Check

Verify BITMART_API_KEY, BITMART_API_SECRET, and BITMART_API_MEMO are available via environment variables or ~/.bitmart/config.toml. If missing, STOP and guide the user to set up credentials.

Step 1: Identify User Intent

Parse user request and map to a READ or WRITE operation:

  • READ operations: market data, balance queries, order queries, fee rates
  • WRITE operations: place order, cancel order, batch orders

Timestamp Display Rules

API responses contain Unix timestamps in different units. When displaying any timestamp to the user, always convert to human-readable local time.

Field Unit Conversion
createTime, updateTime (order responses) Milliseconds ÷ 1000 → Unix seconds → local time
server_time (system time) Milliseconds ÷ 1000 → Unix seconds → local time
t (K-line candle open time) Seconds Direct → Unix seconds → local time
create_time (borrow records) Seconds Direct → Unix seconds → local time
repay_time (repay records) Seconds Direct → Unix seconds → local time

Display format: YYYY-MM-DD HH:MM:SS in the user's local timezone. Example: timestamp 1700000000000 (ms) → 2023-11-15 06:13:20 (UTC+8).

Common mistakes to avoid:

  • Do NOT treat millisecond timestamps as seconds (produces dates in year 55000+)
  • Do NOT display raw numeric timestamps — always convert to readable format
  • Do NOT assume UTC — convert to the user's local timezone

Step 2: Execute

  • READ: Call the API endpoint, parse response, format data for user display.

  • WRITE: Follow these sub-steps strictly in order:

    2a. Parameter naming check (prevents silent failures):

    • Identify the API version of the target endpoint
    • v4 endpoints (/spot/v4/...): ALL params must be camelCase (clientOrderId, orderId, orderMode, startTime)
    • v1–v3 endpoints: ALL params must be snake_case (client_order_id, order_id, start_time)
    • Special exception: POST /spot/v2/submit_order uses mixed — client_order_id (snake_case) + stpMode (camelCase)
    • The API does NOT return an error for wrong-case params — it silently ignores them, causing wrong orders or failed queries

    2b. Order type rules — params, precision, minimum validation:

    First call GET /spot/v1/symbols/details, locate the symbol in data.symbols[], extract: price_max_precision, quote_increment, min_buy_amount, min_sell_amount.

    Then branch:

    type=market, side=buy — Market buy:

    • Send only notional (USDT/quote amount). Do NOT send size or price — silently ignored and causes error 50021.
    • Validate: float(notional) >= min_buy_amount. If not, STOP — suggest "notional":"<min_buy_amount>". API returns 51012 otherwise.
    • Body: {"symbol":"XRP_USDT","side":"buy","type":"market","notional":"5"}

    type=market, side=sell — Market sell:

    • Send only size (base currency quantity, e.g. XRP amount). Do NOT send price or notional.
    • Truncate size to quote_increment precision.
    • Estimate value: size * current_last_price. If estimated value < min_sell_amount, STOP and warn user.
    • Body: {"symbol":"XRP_USDT","side":"sell","type":"market","size":"10"}

    type=limit — Limit order:

    • Send size + price. Truncate price to price_max_precision, size to quote_increment.
    • Note: If price exceeds price_max_precision, the API silently truncates the extra decimals instead of returning an error. Always truncate client-side to ensure the submitted price matches the intended price.
    • Calculate order_value = size * price. If order_value < min_buy_amount (buy) or < min_sell_amount (sell), STOP.
    • If user requested "buy all" / "use full balance": size = floor(balance / price) at precision, re-verify minimum.
    • No hidden risk — order sits on the book until filled or canceled.

    type=limit_maker — Post-only (maker-only):

    • Same params as limit (size + price). Same precision/minimum rules.
    • CRITICAL behavioral note: The server auto-cancels the order (no error) if the price would immediately match:
      • Buy limit_maker: if price >= best_ask, order is silently canceled. Price must be below best ask.
      • Sell limit_maker: if price <= best_bid, order is silently canceled. Price must be above best bid.
    • Inform user of this risk when setting an aggressive limit_maker price.

    type=ioc — Immediate-or-Cancel:

    • Same params as limit (size + price). Same precision/minimum rules.
    • Behavioral note: Fills whatever quantity is available immediately at the given price; the unfilled remainder is immediately canceled. User may receive a partial fill or no fill at all.

    2c. Confirm and execute:

    • Present order summary based on type:
      • market buy: symbol, side=buy, type=market, notional amount
      • market sell: symbol, side=sell, type=market, size (quantity)
      • limit/limit_maker/ioc: symbol, side, type, size, price, estimated order value
    • For limit_maker: include a reminder that the order will be auto-canceled if the price crosses the spread.
    • Ask for explicit "CONFIRM" before executing. Only proceed after user confirms.

Step 3: Verify (WRITE only)

  • After placing an order: Call POST /spot/v4/query/order with {"orderId":"..."} to confirm order status.
  • After canceling an order: Call POST /spot/v4/query/open-orders to verify the order is no longer open.
  • Report the verified result to the user.

Cross-Skill Workflows

Workflow 1: Check Price → Check Balance → Buy

  1. bitmart-exchange-spot → GET /spot/quotation/v3/ticker?symbol=BTC_USDT — Get current price
  2. bitmart-exchange-spot → GET /account/v1/wallet — Check available balance
  3. bitmart-exchange-spot → POST /spot/v2/submit_order — Place buy order (after user CONFIRM)
  4. bitmart-exchange-spot → POST /spot/v4/query/order — Verify order execution

Error Handling

Spot business error codes are endpoint/version specific. Use the table below for authentication / transport issues and common current spot order-query behavior. For margin borrow / repay / transfer flows, see the margin-only notes after the table.

Code Description Action
1000 Success Process response normally
30002 X-BM-KEY not found Check that API key is set correctly
30005 X-BM-SIGN is wrong Verify signature generation (timestamp, memo, body format)
30006 X-BM-TIMESTAMP is wrong Ensure X-BM-TIMESTAMP is present and is a Unix timestamp in milliseconds
30007 Timestamp/recvWindow validation failed Sync system clock (NTP), send X-BM-TIMESTAMP as Unix milliseconds, and ensure (serverTime - timestamp) <= recvWindow; recvWindow must be Long in (0,60000], default 5000 (max 60000). For current signed v4 flows, rely on recvWindow as the effective request-validity window.
30010 IP forbidden Check API key IP whitelist settings
30013 Rate limit exceeded Wait for rate limit window to reset, then retry
50005 Order Id not found / query returned no data On POST /spot/v4/query/order, a missing orderId / clientOrderId currently returns this code
50021 param error For market buy, use notional (USDT amount) — do NOT use size; size is silently ignored and causes this error
51011 param not match : size * price >= X Read symbol constraints from GET /spot/v1/symbols/details; enforce side-specific minimum notional (min_buy_amount/min_sell_amount)
51012 below minimum order amount notional (for market buy) or size * price (for limit) is below min_buy_amount; increase order value to at least the symbol minimum
52000 Unsupported OrderMode Type On current v4 query endpoints, use a valid orderMode (spot / iso_margin) or omit the field to query all modes
40044 Invalid order size Call GET /spot/v1/symbols/details; use symbol precision/increment fields and truncate (not round) size and price
50023 Operation is limited Pair may not support API trading; use a different pair
429 HTTP rate limit Back off exponentially, check X-BM-RateLimit-Reset header
418 IP banned Stop all requests immediately; wait before retrying

Margin-only business codes (do not treat as global spot codes):

  • 51003 — Account Limit. Use in margin borrow / repay / transfer context; do not use as the generic “order not found” code for v4 order-query flows.
  • 51006 — Exceeds the amount to be repaid. Use for isolated margin repay flows.
  • 51007 — order_mode not found in the official business-code table. Do not use this as guidance for current v4 query endpoints; invalid orderMode requests currently return 52000. | 403 | Cloudflare WAF block | Check IP reputation (VPN/cloud IPs are commonly challenged); wait 30-60 seconds and retry; do not auto-retry more than 3 times | | 503 | Cloudflare challenge / origin unavailable | Same as 403; if response body contains "Cloudflare" or "cf-", it is a Cloudflare interception, not a BitMart error; check network environment |

Cloudflare Handling

BitMart API is behind Cloudflare CDN. If you receive HTTP 403/503 and the response body contains "Cloudflare", "cf-", or an HTML challenge page (instead of JSON):

  1. This is a Cloudflare interception, not a BitMart API error — do not parse as JSON
  2. Check if too many requests were sent in a short window (Cloudflare WAF has its own rules independent of API rate limits)
  3. Wait 30-60 seconds before retrying
  4. If running from a cloud server or VPN, the IP may have low reputation — try from a different network
  5. Do not auto-retry more than 3 times — inform the user if the issue persists

Cloudflare 1010: Non-curl HTTP clients with default bot-like User-Agent strings (e.g., Python-urllib, Go-http-client) may receive HTTP 403 / error 1010. Always send the User-Agent: bitmart-skills/spot/v2026.3.23 header from your HTTP library — do not rely on the library default.

Security Notes

  • Never display full API keys or secrets. Show first 5 + last 4 characters only (e.g., bmk12...9xyz).
  • All WRITE operations require explicit user confirmation before execution. Present a clear summary of the action and wait for "CONFIRM".
  • Recommend IP whitelist on API keys for additional security.
  • Recommend minimum permissions: Read-Only + Spot-Trade only (no Withdraw permission).
  • All trading outputs include disclaimer: "Not financial advice. You are solely responsible for your investment decisions."
Related skills

More from bitmartexchange/bitmart-skills

Installs
12
Repository
bitmartexchange…t-skills
GitHub Stars
30
First Seen
Mar 11, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykWarn