Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tiagosiebler/bitmart-api/llms.txt

Use this file to discover all available pages before exploring further.

The BitMart FuturesClientV2 exposes a full suite of public market data endpoints for USD-M perpetual futures contracts. No API key is required for any of the methods on this page — instantiate the client without credentials to query prices, order books, funding rates, and historical klines.

​
Installation & Setup

import { FuturesClientV2 } from 'bitmart-api';

// Public endpoints — no credentials needed
const client = new FuturesClientV2();

// Authenticated endpoints (private methods on other pages)
const authClient = new FuturesClientV2({
  apiKey: 'YOUR_API_KEY',
  apiSecret: 'YOUR_API_SECRET',
  apiMemo: 'YOUR_API_MEMO',
});

​
System Status

​
getSystemTime()

Returns the current server timestamp in milliseconds. Use this to synchronise your local clock before placing time-sensitive requests. Signature 
getSystemTime(): Promise<APIResponse<{ server_time: number }>>

import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2();

const result = await client.getSystemTime();
console.log('Server time:', result.data.server_time);

​
getSystemStatus()

Returns the current operational status of all BitMart services. Use this to check for planned maintenance or incidents before trading. Signature 
getSystemStatus(): Promise<APIResponse<{ service: ServiceStatus[] }>>

import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2();

const status = await client.getSystemStatus();
console.log('Services:', JSON.stringify(status.data.service, null, 2));

​
Contract Information

​
getFuturesContractDetails(params?)

Returns a list of all available futures symbols with full specification data: price/volume precision, leverage range, funding rate, open interest, contract expiry, and 24-hour statistics. Signature 
getFuturesContractDetails(params?: {
  symbol?: string;
}): Promise<APIResponse<{ symbols: FuturesContractDetails[] }>>
​
symbol
string
Optional contract symbol filter (e.g. BTCUSDT). Omit to retrieve all listed contracts.
Response fields (FuturesContractDetails) 
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2();

// Fetch all contract details
const result = await client.getFuturesContractDetails();
for (const contract of result.data.symbols) {
  console.log(`${contract.symbol}: last=${contract.last_price}, funding=${contract.funding_rate}`);
}

​
getFuturesContractDepth(params)

Returns the current order book (bids and asks) for a futures contract. Each entry is [price, size, count]. Signature 
getFuturesContractDepth(params: {
  symbol: string;
}): Promise<APIResponse<FuturesContractDepth>>
​
symbol
string
required
Contract symbol (e.g. BTCUSDT).
Response fields (FuturesContractDepth)
FieldTypeDescription
timestampnumberServer timestamp (ms)
symbolstringContract symbol
asks[string, string, string][]Ask levels: [price, size, count]
bids[string, string, string][]Bid levels: [price, size, count]
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2();

const depth = await client.getFuturesContractDepth({ symbol: 'BTCUSDT' });

const topAsk = depth.data.asks[0];
const topBid = depth.data.bids[0];
console.log(`Best ask: ${topAsk[0]} | Best bid: ${topBid[0]}`);

​
getFuturesMarketTrade(params)

Returns the most recent trades executed on the order book for a given futures symbol. Signature 
getFuturesMarketTrade(params: {
  symbol: string;
  limit?: number;
}): Promise<APIResponse<FuturesMarketTrade[]>>
​
symbol
string
required
Contract symbol (e.g. BTCUSDT).
​
limit
number
Number of recent trades to return. Default 50; maximum 100.
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2();

const trades = await client.getFuturesMarketTrade({
  symbol: 'BTCUSDT',
  limit: 20,
});

for (const trade of trades.data) {
  const side = trade.is_buyer_maker ? 'SELL' : 'BUY';
  console.log(`${side} ${trade.qty} @ ${trade.price}`);
}

​
Open Interest & Funding

​
getFuturesOpenInterest(params)

Returns the current open interest for a futures contract in both contract units and USD value. Signature 
getFuturesOpenInterest(params: {
  symbol: string;
}): Promise<APIResponse<FuturesOpenInterest>>
​
symbol
string
required
Contract symbol (e.g. BTCUSDT).
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2();

const oi = await client.getFuturesOpenInterest({ symbol: 'BTCUSDT' });
console.log(`Open interest: ${oi.data.open_interest} contracts`);
console.log(`Open interest value: $${oi.data.open_interest_value}`);

​
getFuturesFundingRate(params)

Returns the current and expected next funding rate for a perpetual futures contract. Signature 
getFuturesFundingRate(params: {
  symbol: string;
}): Promise<APIResponse<FuturesFundingRate>>
​
symbol
string
required
Contract symbol (e.g. BTCUSDT).
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2();

const fr = await client.getFuturesFundingRate({ symbol: 'BTCUSDT' });
console.log(`Current rate: ${fr.data.rate_value}`);
console.log(`Expected rate: ${fr.data.expected_rate}`);

​
getFuturesFundingRateV2(params?)

Enhanced funding rate endpoint returning additional fields including the scheduled funding time and rate caps/floors for one or all contracts. Signature 
getFuturesFundingRateV2(
  params?: FuturesFundingRateV2Request,
): Promise<APIResponse<FuturesFundingRateV2Response>>
​
symbol
string
Optional contract symbol. Omit to retrieve funding rates for all contracts.
Additional response fields vs V1
FieldDescription
funding_timeUnix timestamp of the next scheduled funding settlement
funding_upper_limitMaximum funding rate cap
funding_lower_limitMinimum funding rate floor
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2();

const result = await client.getFuturesFundingRateV2({ symbol: 'BTCUSDT' });
const rate = result.data.list[0];
console.log(`Next funding @ ${new Date(rate.funding_time * 1000).toISOString()}: ${rate.rate_value}`);

​
getFuturesFundingRateHistory(params)

Returns historical funding rate settlements for a contract. Signature 
getFuturesFundingRateHistory(params: {
  symbol: string;
  limit?: string;
}): Promise<APIResponse<{ list: FuturesFundingRateHistory[] }>>
​
symbol
string
required
Contract symbol (e.g. BTCUSDT).
​
limit
string
Number of historical records to return (passed as a string).
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2();

const history = await client.getFuturesFundingRateHistory({
  symbol: 'BTCUSDT',
  limit: '50',
});

for (const record of history.data.list) {
  console.log(`${record.funding_time}: ${record.funding_rate}`);
}

​
Klines (Candlesticks)

​
getFuturesKlines(params)

Returns OHLCV candlestick data for a futures contract over a specified time range. Signature 
getFuturesKlines(
  params: FuturesKlinesRequest,
): Promise<APIResponse<FuturesKline[]>>
​
symbol
string
required
Contract symbol (e.g. BTCUSDT).
​
start_time
number
required
Start of the time range as a Unix timestamp (seconds).
​
end_time
number
required
End of the time range as a Unix timestamp (seconds).
​
step
number
Candle interval in minutes. Common values:
stepInterval
11 minute
33 minutes
55 minutes
1515 minutes
3030 minutes
601 hour
1202 hours
2404 hours
4808 hours
72012 hours
14401 day
100801 week
432001 month
Response fields (FuturesKline)
FieldTypeDescription
timestampnumberCandle open time (Unix seconds)
open_pricestringOpen price
close_pricestringClose price
high_pricestringHigh price
low_pricestringLow price
volumestringVolume in contracts
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2();

const klines = await client.getFuturesKlines({
  symbol: 'BTCUSDT',
  start_time: 1709130476,
  end_time: 1709131476,
  step: 1,  // 1-minute candles
});

for (const k of klines.data) {
  console.log(`O:${k.open_price} H:${k.high_price} L:${k.low_price} C:${k.close_price} V:${k.volume}`);
}

​
getFuturesMarkPriceKlines(params)

Returns mark price OHLCV candlestick data. Mark price is used for PnL calculation and liquidation, and is typically smoother than last price. Accepts the same parameters as getFuturesKlines. Signature 
getFuturesMarkPriceKlines(
  params: FuturesKlinesRequest,
): Promise<APIResponse<FuturesKline[]>>
Mark price klines use the same FuturesKlinesRequest and FuturesKline types as regular klines. Use these candles to analyse liquidation risk rather than market price action.
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2();

const now = Math.floor(Date.now() / 1000);

const markKlines = await client.getFuturesMarkPriceKlines({
  symbol: 'BTCUSDT',
  start_time: now - 3600,
  end_time: now,
  step: 5,  // 5-minute candles
});

console.log(`Mark price klines: ${markKlines.data.length}`);

​
Leverage Brackets

​
getFuturesLeverageBracket(params?)

Returns the leverage risk bracket rules for futures contracts, showing maintenance margin ratios at each notional size tier. Signature 
getFuturesLeverageBracket(params?: {
  symbol?: string;
}): Promise<APIResponse<{ rules: FuturesLeverageBracketRule[] }>>
​
symbol
string
Optional contract symbol. Omit to retrieve brackets for all contracts.
Response fields 
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2();

const brackets = await client.getFuturesLeverageBracket({ symbol: 'BTCUSDT' });

for (const rule of brackets.data.rules) {
  console.log(`${rule.symbol} has ${rule.brackets.length} leverage brackets`);
  for (const b of rule.brackets) {
    console.log(`  Bracket ${b.bracket}: max ${b.initial_leverage}x, MMR ${b.maint_margin_ratio}`);
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us