BitMart Futures Trading

Overview

53 endpoints total. Table:

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)

API Base

• Base URL: https://api-cloud-v2.bitmart.com
• Symbol Format: BTCUSDT (no separator — unlike spot which uses BTC_USDT)

Key Differences from Spot

IMPORTANT: Always use the futures base URL (api-cloud-v2) for contract endpoints. Using the spot base URL will fail.

Standard Response Format

Success:

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

Error:

{
  "code": 40035,
  "message": "Order not exist",
  "trace": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": null
}

Important: code == 1000 means success. Any other code is an error.

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

Order Side Reference

Hedge mode mapping:

• To open long: side = 1
• To close long: side = 3
• To open short: side = 4
• To close short: side = 2

One-way mode: Use side 1 (buy) or 4 (sell). The system infers whether to open or close.

Order Mode Reference

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 contract details (no auth)

curl -s 'https://api-cloud-v2.bitmart.com/contract/public/details?symbol=BTCUSDT'

Example 2: Get futures positions (KEYED)

curl -s -H "X-BM-KEY: $BITMART_API_KEY" \
  'https://api-cloud-v2.bitmart.com/contract/private/position?symbol=BTCUSDT'

Example 3: Open long BTC position (SIGNED)

TIMESTAMP=$(date +%s000)
BODY='{"symbol":"BTCUSDT","side":1,"type":"market","size":1,"leverage":"10","open_type":"cross"}'
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-v2.bitmart.com/contract/private/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"

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, positions, balance, order queries, funding rates
• WRITE operations: open/close position, set leverage, place plan order, set TP/SL, trailing stop, transfer

Step 1.5: Pre-Trade Position Check (MANDATORY for open/leverage operations)

Before executing ANY of: open position (POST /contract/private/submit-order with side 1 or 4), set leverage (POST /contract/private/submit-leverage), or change margin mode:

1. Call GET /contract/private/position-v2?symbol=<SYMBOL> to check for existing positions and current margin mode (open_type)
2. Evaluate the entire data[] array returned by position-v2 — do not assume there is only one row
3. Parse each row's current_amount as a number before comparing it. The API returns string values such as "0".
4. If any row's parsed current_amount is non-zero (existing position found):
   • You MUST inherit the relevant non-zero position row's leverage value — do NOT send a different leverage in the order
   • You MUST inherit the relevant non-zero position row's open_type (margin mode: cross or isolated) — do NOT send a different margin mode
   • If the user explicitly requested different leverage or margin mode: STOP and warn:

     "You have an existing [X]x [cross/isolated] [LONG/SHORT] position of [size] contracts. Changing leverage or margin mode while a position is open is commonly rejected by the API (for example, code 40012/40040). Please close the existing position first if you want to change these settings."

   • Do not attempt to change position_mode while any non-zero position row exists
   • Wait for user decision before proceeding
5. If every row's parsed current_amount is 0: proceed with user-specified leverage and margin mode
6. If the request becomes mode-sensitive (for example, deciding whether to switch between hedge_mode and one_way_mode, or explaining current mode-dependent behavior), call GET /contract/private/get-position-mode before making that decision. Do not treat get-position-mode as a hard prerequisite for every plain open-position flow.

Step 1.55: Pre-Mode-Switch Clean-State Check (MANDATORY when changing position mode)

position_mode is an account-wide setting. Before calling POST /contract/private/set-position-mode:

1. Ensure Step 1.5 found no existing position (every row's parsed current_amount is 0)
2. Call GET /contract/private/get-open-orders and verify there are no open orders on the account
3. If any open orders or other occupied state remain: STOP and ask the user to clear them before retrying the mode switch
4. If set-position-mode returns 40059, treat that as "account is not in a clean state for mode switching" and stop

Step 1.6: TP/SL Order Parameter Rules (MANDATORY when setting TP/SL on a position)

When the user asks to set take-profit or stop-loss on an existing futures position, use POST /contract/private/submit-tp-sl-order.

CRITICAL — Do NOT confuse these two mechanisms:

• preset_take_profit_price / preset_stop_loss_price: optional fields on submit-order to attach TP/SL at position-open time
• submit-tp-sl-order: standalone endpoint to set TP/SL on an already-open position — uses trigger_price + executive_price, NOT take_profit_price/stop_loss_price

Required parameters:

Always submit TP and SL as two separate API calls. One call for take-profit, one for stop-loss.

Long BTC TP example: {"symbol":"BTCUSDT","type":"take_profit","side":3,"trigger_price":"72000","executive_price":"0","price_type":1,"plan_category":2} Long BTC SL example: {"symbol":"BTCUSDT","type":"stop_loss","side":3,"trigger_price":"64000","executive_price":"0","price_type":1,"plan_category":2}

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.

Query parameter timestamps for futures endpoints (start_time, end_time) are endpoint-specific:

• Seconds: /contract/public/kline, /contract/public/markprice-kline, /contract/private/order-history, /contract/private/trades, and affiliate rebate endpoints (/contract/private/affiliate/...)
• Milliseconds: /contract/private/transaction-history

Do NOT assume all futures start_time / end_time are seconds — always follow the target endpoint definition.

Display format: YYYY-MM-DD HH:MM:SS in the user's local timezone. Example: timestamp 1709971200000 (ms) → 2024-03-09 16:00:00 (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 sub-steps below, then ask for "CONFIRM":

  2a. submit-order conditional param selection:

  Scenario	Send	Do NOT send
  Open position, type=limit (side=1 or 4)	symbol, side, type:"limit", price, size, leverage, open_type	—
  Open position, type=market (side=1 or 4)	symbol, side, type:"market", size, leverage, open_type	price (ignored, causes confusion)
  Close position, type=limit (side=2 or 3)	symbol, side, type:"limit", price, size	leverage, open_type (not needed for close)
  Close position, type=market (side=2 or 3)	symbol, side, type:"market", size	price, leverage, open_type

  Additional constraints:

  • leverage / open_type for open orders: if an existing position is found (Step 1.5), use the relevant non-zero position row's values — do NOT send different ones.
  • mode=4 (Maker Only): only valid with type=limit. Never combine with type=market.
  • preset_take_profit_price / preset_stop_loss_price: only valid for opening orders (side=1 or 4). For TP/SL on an already-open position, use submit-tp-sl-order (see Step 1.6).
  • size is always an integer (number of contracts). Check the minimum contract size via GET /contract/public/details.

  2b. Confirm and execute: Present a summary (symbol, side, type, price if limit, size, leverage, open_type) and ask for explicit "CONFIRM" before executing.

Step 3: Verify (WRITE only)

• After opening a position: Call GET /contract/private/position-v2 to confirm position was opened. Report entry price, size, leverage, liquidation price, margin used.
• After closing a position: Call GET /contract/private/position-v2 to confirm position was closed or reduced. Report realized PnL.
• After placing an order: Call GET /contract/private/order to confirm order status.
• After canceling an order: Call GET /contract/private/get-open-orders to verify the order is no longer open.
• Report the verified result to the user.

See references/open-position.md, references/close-position.md, references/plan-order.md, and references/tp-sl.md for detailed step-by-step workflows.

References

• API Reference — All 53 endpoints with full parameters, examples, and response fields
• Open Position — Step-by-step open position workflow
• Close Position — Step-by-step close position workflow
• Plan Orders — Conditional/trigger order workflow
• TP/SL — Take-profit/stop-loss workflow

Cross-Skill Workflows

Workflow 1: Transfer Funds → Open Position → Monitor

1. bitmart-exchange-futures → POST /account/v1/transfer-contract — Transfer USDT from spot to futures
2. bitmart-exchange-futures → POST /contract/private/submit-leverage — Set leverage
3. bitmart-exchange-futures → POST /contract/private/submit-order — Open position (after user CONFIRM)
4. bitmart-exchange-futures → GET /contract/private/position-v2 — Monitor position

Workflow 2: Check Spot Balance → Transfer → Open Futures

1. bitmart-exchange-spot → GET /account/v1/wallet — Check spot balance
2. bitmart-exchange-futures → POST /account/v1/transfer-contract — Transfer to futures
3. bitmart-exchange-futures → POST /contract/private/submit-order — Open position

Error Handling

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 + Futures-Trade only (no Withdraw permission).
• Leverage warning: Higher leverage amplifies both gains and losses. Always inform the user of the liquidation price before opening leveraged positions.
• All trading outputs include disclaimer: "Not financial advice. You are solely responsible for your investment decisions. Futures trading carries significant risk of loss."

Reference: Order Types

Reference: Order Sides

Reference: Order Modes

Reference: Order States

Reference: Open Types (Margin Mode)

Reference: Position Modes

Reference: Plan Categories

Reference: Price Types

Reference: Price Way (Plan Orders)

Reference: Transfer Types

Reference: Flow Types (Transaction History)

Reference: STP Modes (Self-Trade Prevention)

Reference: K-Line Steps