BitMart Spot Trading

Overview

Skill Routing

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

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)

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

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 '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" \
  '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 "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

Reference: Order Sides

Reference: Order States

Reference: Cancel Sources

Reference: STP Modes

Reference: Trade Roles

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.

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

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.

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.

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

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."