BitMart Futures Trading
Base URL: https://api-cloud-v2.bitmart.com | Symbol: BTCUSDT (no underscore) | Success: code == 1000
53 endpoints — full details in references/bitmart-api-reference.md
Authentication
Credentials (from .env): BITMART_API_KEY, BITMART_API_SECRET, BITMART_API_MEMO
No BitMart account? Register at https://www.bitmart.com/invite/cMEArf
Verify credentials before any private call. If missing — STOP.
| Level | Endpoints | Headers |
|---|---|---|
| NONE | Public market data | — |
| KEYED | Read-only private | X-BM-KEY |
| SIGNED | Write operations | X-BM-KEY + X-BM-SIGN + X-BM-TIMESTAMP |
Signature: HMAC-SHA256(secret, "{timestamp}#{memo}#{body}") — GET body = ""
Always include X-BM-BROKER-ID: BlaveData666666 on ALL requests.
IP Whitelist: Use public IP (curl https://checkip.amazonaws.com), not private IP (10.x, 172.x, 192.168.x).
Signature Python implementation and common mistakes:
references/bitmart-signature.md
Operation Flow
Step 0: Credential Check
Verify BITMART_API_KEY, BITMART_API_SECRET, BITMART_API_MEMO. If missing — STOP.
Step 1.1: Query Positions (READ)
GET /contract/private/position-v2 (KEYED, no signature needed)
Filter current_amount != "0" → display symbol, position_side, current_amount, entry_price, leverage, open_type, liquidation_price, unrealized_pnl
Step 1.5: Pre-Trade Check (MANDATORY before open/leverage)
- Call
GET /contract/private/position-v2?symbol=<SYMBOL> - If
current_amountnon-zero → inheritleverageandopen_type, do NOT override - If user wants different values → STOP, warn to close position first
Step 1.55: Pre-Mode-Switch Check
Confirm no positions (Step 1.5) AND no open orders (GET /contract/private/get-open-orders). If either exists → STOP.
Step 1.6: TP/SL on Existing Position
POST /contract/private/submit-tp-sl-order — submit TP and SL as two separate calls
| Param | Value |
|---|---|
type | "take_profit" or "stop_loss" |
side | 3 close long / 2 close short |
trigger_price | Activation price |
executive_price | "0" for market fill |
price_type | 1 last / 2 mark |
plan_category | 2 |
Step 2: Execute
- READ → call, parse, display
- WRITE → present summary → ask "CONFIRM" → execute
submit-order rules:
| Scenario | Send | Omit |
|---|---|---|
| Open, market | symbol, side, type:"market", size, leverage, open_type | price |
| Open, limit | symbol, side, type:"limit", price, size, leverage, open_type | — |
| Close, market | symbol, side, type:"market", size | price, leverage, open_type |
| Close, limit | symbol, side, type:"limit", price, size | leverage, open_type |
Step 3: Verify
- After open:
position-v2→ report entry price, size, leverage, liquidation price - After close:
position-v2→ report realized PnL - After order:
GET /contract/private/order→ confirm status
Order Reference
Side: 1 Open Long / 2 Close Short / 3 Close Long / 4 Open Short
Mode: 1 GTC / 2 FOK / 3 IOC / 4 Maker Only
Timestamps: ms — always convert to local time for display.
Error Handling
| Code | Action |
|---|---|
| 30005 | Wrong signature → see references/bitmart-signature.md |
| 30007 | Timestamp drift → sync clock |
| 40012/40040 | Leverage/mode conflict → inherit existing position values |
| 40027/42000 | Insufficient balance → transfer from spot or reduce size |
| 429 | Rate limited → wait |
| 403/503 Cloudflare | Wait 30-60s, retry max 3× |
Spot ↔ Futures Transfer
Present summary → ask "CONFIRM" → execute.
Endpoint: POST https://api-cloud-v2.bitmart.com/account/v1/transfer-contract (SIGNED)
| Param | Value |
|---|---|
currency | USDT only |
amount | transfer amount |
type | "spot_to_contract" or "contract_to_spot" |
Rate limit: 1 req/2sec. ⚠️ /spot/v1/transfer-contract does NOT exist.
Security
- WRITE operations require "CONFIRM"
- Always show liquidation price before opening leveraged positions
- "Not financial advice. Futures trading carries significant risk of loss."
References
references/bitmart-api-reference.md— 53 endpointsreferences/bitmart-signature.md— Python signature implementationreferences/bitmart-open-position.md/bitmart-close-position.md/bitmart-plan-order.md/bitmart-tp-sl.md