BitMart Futures Trading

Overview

53 endpoints total. Table:

| # | Category | API Endpoint | Type | Description | |---|----------|-------------|------|-------------| | 1 | Market Data | GET /contract/public/details | READ | Contract specifications | | 2 | Market Data | GET /contract/public/depth | READ | Order book | | 3 | Market Data | GET /contract/public/market-trade | READ | Recent trades (max 100) | | 4 | Market Data | GET /contract/public/funding-rate | READ | Current funding rate | | 5 | Market Data | GET /contract/public/funding-rate-history | READ | Historical funding rates | | 6 | Market Data | GET /contract/public/kline | READ | K-line (steps: 1,3,5,15,30,60,120,240,360,720,1440,4320,10080) | | 7 | Market Data | GET /contract/public/markprice-kline | READ | Mark price K-line | | 8 | Market Data | GET /contract/public/open-interest | READ | Open interest | | 9 | Market Data | GET /contract/public/leverage-bracket | READ | Leverage tiers / risk limits | | 10 | Account | GET /contract/private/assets-detail | READ | Futures account balance | | 11 | Account | GET /contract/private/trade-fee-rate | READ | Trade fee rate | | 12 | Account | GET /contract/private/position | READ | Current positions | | 13 | Account | GET /contract/private/position-v2 | READ | Positions (extended info) | | 14 | Account | GET /contract/private/position-risk | READ | Position risk / liquidation | | 15 | Account | GET /contract/private/get-position-mode | READ | Current position mode | | 16 | Account | GET /contract/private/transaction-history | READ | PnL / funding / fees history | | 17 | Trading | POST /contract/private/submit-order | WRITE | Place order | | 18 | Trading | POST /contract/private/cancel-order | WRITE | Cancel order | | 19 | Trading | POST /contract/private/cancel-orders | WRITE | Batch cancel | | 20 | Trading | POST /contract/private/modify-limit-order | WRITE | Amend limit order | | 21 | Trading | POST /contract/private/cancel-all-after | WRITE | Timed cancel all | | 22 | Trading | POST /contract/private/submit-leverage | WRITE | Set leverage | | 23 | Trading | POST /contract/private/set-position-mode | WRITE | Set hedge/one-way mode | | 24 | Trading | POST /account/v1/transfer-contract | WRITE | Spot-Futures transfer | | 25 | Plan Order | POST /contract/private/submit-plan-order | WRITE | Conditional/trigger order | | 26 | Plan Order | POST /contract/private/cancel-plan-order | WRITE | Cancel plan order | | 27 | Plan Order | POST /contract/private/modify-plan-order | WRITE | Amend plan order | | 28 | TP/SL | POST /contract/private/submit-tp-sl-order | WRITE | Set take-profit/stop-loss | | 29 | TP/SL | POST /contract/private/modify-tp-sl-order | WRITE | Modify TP/SL | | 30 | TP/SL | POST /contract/private/modify-preset-plan-order | WRITE | Modify preset TP/SL on order | | 31 | Trailing | POST /contract/private/submit-trail-order | WRITE | Trailing stop order | | 32 | Trailing | POST /contract/private/cancel-trail-order | WRITE | Cancel trailing | | 33 | Order Query | GET /contract/private/order | READ | Order by ID | | 34 | Order Query | GET /contract/private/order-history | READ | Historical orders | | 35 | Order Query | GET /contract/private/get-open-orders | READ | All open orders | | 36 | Order Query | GET /contract/private/current-plan-order | READ | Active plan orders | | 37 | Order Query | GET /contract/private/trades | READ | Trade / fill history | | 38 | Order Query | POST /account/v1/transfer-contract-list | READ | Transfer records | | 39 | Sub-Account | POST /account/contract/sub-account/main/v1/sub-to-main | WRITE | Sub → Main transfer (main account) | | 40 | Sub-Account | POST /account/contract/sub-account/main/v1/main-to-sub | WRITE | Main → Sub transfer (main account) | | 41 | Sub-Account | POST /account/contract/sub-account/sub/v1/sub-to-main | WRITE | Sub → Main transfer (sub account) | | 42 | Sub-Account | GET /account/contract/sub-account/main/v1/wallet | READ | Sub-account futures balance | | 43 | Sub-Account | GET /account/contract/sub-account/main/v1/transfer-list | READ | Sub-account transfer history | | 44 | Sub-Account | GET /account/contract/sub-account/v1/transfer-history | READ | Account transfer history | | 45 | Affiliate | GET /contract/private/affiliate/rebate-list | READ | Rebate overview | | 46 | Affiliate | GET /contract/private/affiliate/trade-list | READ | Affiliate trade records | | 47 | Affiliate | GET /contract/private/affiliate/rebate-user | READ | Single user rebate data | | 48 | Affiliate | GET /contract/private/affiliate/rebate-api | READ | Single API user rebate data | | 49 | Affiliate | GET /contract/private/affiliate/invite-check | READ | Check if invited user | | 50 | Affiliate | GET /contract/private/affiliate/rebate-inviteUser | READ | Invited customer list | | 51 | Simulated | POST /contract/private/claim | WRITE | Demo account top-up (demo only) | | 52 | System | GET /system/time | READ | Get server time (milliseconds) | | 53 | System | GET /system/service | READ | Get system service status / maintenance |

Skill Routing

| User Intent | Correct Skill | |------------|---------------| | Futures/contract trading, leverage, TP/SL, plan orders, trailing stops, sub-account transfers, affiliate/rebate queries, simulated trading | bitmart-exchange-futures (this skill) | | Spot buy/sell, order management, spot balance, fee rates | bitmart-exchange-spot |

Authentication

Credential Check (Before Any Private API Call)

Before calling any authenticated endpoint, verify credentials are available:

Check for environment variables:
- BITMART_API_KEY — API key
- BITMART_API_SECRET — Secret key
- BITMART_API_MEMO — Memo string

Or check for config file: ~/.bitmart/config.toml

[default]
api_key = "your-api-key"
api_secret = "your-secret-key"
memo = "your-memo"

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, positions, orders, affiliate (endpoints 10-16, 33-37, 42-50) | X-BM-KEY | | SIGNED | Write operations — trading, leverage, transfers, sub-account transfers, demo claim (endpoints 17-32, 38-41, 51) | 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 |

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

| Aspect | Spot | Futures | |--------|------|---------| | Base URL | api-cloud.bitmart.com | api-cloud-v2.bitmart.com | | Symbol Format | BTC_USDT (underscore) | BTCUSDT (no separator) | | Order Side | "buy" / "sell" (string) | 1 / 2 / 3 / 4 (integer) | | Leverage | N/A | Configurable per symbol | | Position Mode | N/A | hedge_mode / one_way_mode | | Margin Mode | N/A | cross / isolated |

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

| Value | Hedge Mode | One-Way Mode | |-------|------------|--------------| | 1 | Open Long (buy_open_long) | Buy | | 2 | Close Short (buy_close_short) | Buy (Reduce Only) | | 3 | Close Long (sell_close_long) | Sell (Reduce Only) | | 4 | Open Short (sell_open_short) | Sell |

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

| Value | Name | Description | |-------|------|-------------| | 1 | GTC | Good Till Cancel — order stays open until filled or canceled | | 2 | FOK | Fill or Kill — must fill entirely or cancel immediately | | 3 | IOC | Immediate or Cancel — fill what's available, cancel the rest | | 4 | Maker Only | Post Only — rejected if it would immediately match |

Rate Limits

| Endpoint | Rate | Target | |----------|------|--------| | Public Market Data (most) | 12/2sec | IP | | Open Interest | 2/2sec | IP | | Assets Detail | 12/2sec | KEY | | Trade Fee Rate | 2/2sec | KEY | | Position / Position V2 | 6/2sec | KEY | | Position Risk | 24/2sec | KEY | | Get Position Mode | 2/2sec | KEY | | Transaction History | 6/2sec | KEY | | Order Detail | 50/2sec | KEY | | Order History / Trades | 6/2sec | KEY | | Open Orders / Plan Orders | 50/2sec | KEY | | Submit Order | 24/2sec | KEY | | Cancel Order | 40/2sec | KEY | | Cancel Orders (batch) | 2/2sec | KEY | | Modify Order | 24/2sec | UID | | Plan / TP-SL / Trail Orders | 24/2sec | UID | | Cancel Plan Order | 40/2sec | UID | | Cancel All After | 4/2sec | UID | | Set Leverage | 24/2sec | KEY | | Set Position Mode | 2/2sec | KEY | | Transfer | 1/2sec | KEY | | Transfer List | 1/2sec | KEY | | Sub-Account Transfers (39-41) | 8/2sec | KEY | | Sub-Account Wallet (42) | 12/2sec | KEY | | Sub-Account History (43-44) | 8/2sec | KEY | | Affiliate Endpoints (45-50) | 24/2sec | KEY | | GET /system/time | 10/sec | IP | | GET /system/service | 10/sec | IP |

Rate limit response headers:

X-BM-RateLimit-Remaining — Requests remaining in window
X-BM-RateLimit-Limit — Total allowed requests in window
X-BM-RateLimit-Reset — Seconds until window resets

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 $2}')
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:

Call GET /contract/private/position-v2?symbol=<SYMBOL> to check for existing positions and current margin mode (open_type)
If an existing position is found (current_amount != 0):
- You MUST inherit the existing leverage value — do NOT send a different leverage in the order
- You MUST inherit the existing 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."
- Wait for user decision before proceeding
If no existing position: proceed with user-specified leverage and margin mode

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:

| Parameter | Type | Value | Notes | |-----------|------|-------|-------| | symbol | String | e.g. BTCUSDT | | | type | String | "take_profit" or "stop_loss" | NEVER "market" or "limit" | | side | Int | 3 (close long) or 2 (close short) | Must match position direction | | trigger_price | String | Activation price | Long TP: > entry; Long SL: < entry | | executive_price | String | "0" for market fill; or a limit price | | | price_type | Int | 1 last price / 2 mark price | Default: 1 | | plan_category | Int | 1 TP/SL order (default) / 2 Position TP/SL order | For existing-position TP/SL, use 2 |

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.

| Field | Unit | Conversion | |-------|------|------------| | create_time, update_time (order responses) | Milliseconds | ÷ 1000 → Unix seconds → local time | | server_time (system time) | Milliseconds | ÷ 1000 → Unix seconds → local time | | timestamp (K-line candle open time) | Seconds | Direct → Unix seconds → local time | | open_timestamp, funding_time (contract details) | Milliseconds | ÷ 1000 → Unix seconds → 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 existing position'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

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

Workflow 2: Check Spot Balance → Transfer → Open Futures

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

Error Handling

| 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) | | 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) | | 30010 | IP forbidden | Check API key IP whitelist settings | | 30013 | Rate limit exceeded | Wait for rate limit window to reset, then retry | | 40035 | Order not exist | Verify the order ID is correct and belongs to this account | | 40044 | Invalid order size | Check min/max limits via GET /contract/public/details | | 40027 | Insufficient balance | Check futures balance; may need to transfer from spot | | 42000 | Insufficient balance (margin) | Reduce order size or add margin | | 40021 | Position does not exist | Verify position is still open before trying to close | | 40040 | Invalid leverage / mode constraint | Check leverage bracket and current position state; if position exists, keep current leverage + open_type | | 40012 | Parameter/state conflict | Commonly appears when leverage/mode conflicts with current position/order state; query GET /contract/private/position-v2 and inherit existing leverage + open_type | | 429 | HTTP rate limit | Back off exponentially, check X-BM-RateLimit-Reset header | | 418 | IP banned | Stop all requests immediately; wait before retrying |

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

| Type | Description | |------|-------------| | limit | Execute at specified price or better | | market | Execute immediately at best available price |

Reference: Order Sides

| Value | Hedge Mode | One-Way Mode | |-------|------------|--------------| | 1 | Open Long | Buy | | 2 | Close Short | Buy (Reduce Only) | | 3 | Close Long | Sell (Reduce Only) | | 4 | Open Short | Sell |

Reference: Order Modes

| Value | Name | Description | |-------|------|-------------| | 1 | GTC | Good Till Cancel | | 2 | FOK | Fill or Kill | | 3 | IOC | Immediate or Cancel | | 4 | Maker Only | Post Only — rejected if it would immediately match |

Reference: Order States

| State | Code | Description | |-------|------|-------------| | Approving | 1 | Order being validated | | Pending | 2 | Order accepted, awaiting fill | | Closed | 4 | Order completed (filled or canceled) |

Reference: Open Types (Margin Mode)

| Value | Description | |-------|-------------| | cross | Cross margin — all available balance used as margin | | isolated | Isolated margin — only allocated margin is at risk |

Reference: Position Modes

| Value | Description | |-------|-------------| | hedge_mode | Can hold simultaneous long and short positions | | one_way_mode | Can hold only one direction at a time |

Reference: Plan Categories

| Value | Description | |-------|-------------| | 1 | TP/SL order — applies to a specific order quantity | | 2 | Position TP/SL — applies to the entire position (default) |

Reference: Price Types

| Value | Description | |-------|-------------| | 1 | Last price (default) — triggers based on last trade price | | 2 | Fair price (mark price) — triggers based on mark price |

Reference: Price Way (Plan Orders)

| Value | Description | |-------|-------------| | 1 | Bullish — trigger when price rises above trigger_price | | 2 | Bearish — trigger when price drops below trigger_price |

Reference: Transfer Types

| Value | Description | |-------|-------------| | spot_to_contract | Spot wallet to futures wallet | | contract_to_spot | Futures wallet to spot wallet |

Reference: Flow Types (Transaction History)

| Value | Description | |-------|-------------| | 0 | All types | | 1 | Transfer | | 2 | Realized PNL | | 3 | Funding Fee | | 4 | Commission | | 5 | Liquidation |

Reference: STP Modes (Self-Trade Prevention)

| Value | Description | |-------|-------------| | 1 | Cancel Maker (default) | | 2 | Cancel Taker | | 3 | Cancel Both |

Reference: K-Line Steps

| Step (minutes) | Description | |----------------|-------------| | 1 | 1-minute candles | | 3 | 3-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 | | 360 | 6-hour candles | | 720 | 12-hour candles | | 1440 | 1-day candles | | 4320 | 3-day candles | | 10080 | 1-week candles |