bitmart-exchange-futures

name	bitmart-exchange-futures
description	Use when the user asks about BitMart futures or contract trading or Futures WebSocket streams, including opening/closing positions, setting leverage, placing plan (conditional) orders, take-profit/stop-loss, trailing orders, checking futures positions, managing futures account, sub-account transfers, affiliate/rebate queries, simulated trading, or streaming real-time futures ticker/book ticker/trades/depth/funding-rate/private order/private position updates. Do NOT use for spot trading (use bitmart-exchange-spot).
homepage	https://www.bitmart.com
metadata	{"author":"bitmart","version":"2026.5.26","sdk_version":"1.4.0","updated":"2026-05-26"}

BitMart Futures Trading

Overview

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

WebSocket coverage: Public real-time channels and private push channels are documented in references/websocket.md, including futures book ticker, funding-rate push, depth speed suffixes, private order position_mode, and private position position_mode.

---

Skill Routing

User Intent	Correct Skill
Futures/contract trading, leverage, TP/SL, plan orders, trailing stops, sub-account transfers, affiliate/rebate/deposit-withdrawal/invited-user asset queries, simulated trading	bitmart-exchange-futures (this skill)
Futures real-time ticker, book ticker, trades, depth, funding-rate push, private order/position push	bitmart-exchange-futures (this skill, WebSocket reference)
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:

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 and system status (endpoints 1-10, 57-58)	None
KEYED	Read-only private data — balances, positions, orders, affiliate, collateral / repayment logs (endpoints 11-17, 34-38, 43-55)	X-BM-KEY
SIGNED	Write operations — trading, leverage, transfers, sub-account transfers, demo claim (endpoints 18-33, 39-42, 56)	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/futures/v2026.5.26 — SDK source identifier for analytics

---

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: For standard Futures endpoints, String(code) == "1000" means success and any other code is an error. Two collateral / repayment endpoints (GET /contract/private/cross_collateral/interest_log and GET /contract/private/auto_repayment) use the alternate response shape {"errno":"OK","message":"Success","success":true,...} and may omit code; treat success == true as success for those endpoints. GET /contract/private/affiliate/aff-customer-info may return "code":"1000" as a string, so do not require a numeric-only comparison.

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 (40-42)	8/2sec	KEY
Sub-Account Wallet (43)	12/2sec	KEY
Sub-Account History (44-45)	8/2sec	KEY
Affiliate Endpoints (46-51)	24/2sec	KEY
Affiliate Deposit / Withdrawal and Account Info (52-53)	24/2sec	KEY
Cross-Collateral Interest / Auto Repayment (54-55)	2/2sec	UID
GET /system/time	10/sec	IP
GET /system/service	10/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 contract details (no auth)

curl -s -H "User-Agent: bitmart-skills/futures/v2026.5.26" '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" \
  -H "User-Agent: bitmart-skills/futures/v2026.5.26" \
  '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 "User-Agent: bitmart-skills/futures/v2026.5.26" \
  -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
• STREAM operations: real-time futures ticker/book ticker/trades/depth/funding rate, private order push, private position push

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:

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 / 2 Position TP/SL order (default)	For existing-position TP/SL, use 2. Omitting the field currently defaults to 2, but sending 2 explicitly is clearer.

Before submitting or modifying TP/SL, call GET /contract/public/details?symbol=<SYMBOL> and truncate both trigger_price and executive_price to the symbol's price_precision tick size. The API rejects over-precise TP/SL prices with errors such as 40053.

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, cross-collateral / auto-repayment query filters, 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.

• STREAM: Use references/websocket.md. Subscribe to the matching WebSocket channel; for private channels, access/login first with the WebSocket signature payload timestamp#memo#bitmart.WebSocket.

• 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.
  • Futures price precision: truncate every order price field to the contract's price_precision tick size from GET /contract/public/details, including limit price, plan trigger_price, TP/SL trigger_price / executive_price, and trailing-stop activation_price.

  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 58 endpoints with full parameters, examples, and response fields
• WebSocket Reference — Real-time Futures WebSocket channels, login signing, subscription formats, and changelog-only 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

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 signed contract flows that expose recvWindow, 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
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
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/futures/v2026.5.26 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 + 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
6	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