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 account endpoints on this page allow you to inspect balances, retrieve fee information, manage cross-collateral settings, and move funds between your spot and futures wallets — as well as between main and sub-accounts. All methods on this page require authentication (KEYED or SIGNED).

​
Setup

import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

​
Account Balances

​
getFuturesAccountAssets()

Returns all asset balances held in your futures account, including available balance, frozen amounts, unrealised PnL, and position deposits. Signature 
getFuturesAccountAssets(): Promise<APIResponse<FuturesAccountAsset[]>>
Response fields (FuturesAccountAsset)
FieldTypeDescription
currencystringAsset currency (e.g. USDT)
position_depositstringBalance locked as position margin
frozen_balancestringBalance frozen in open orders
available_balancestringAvailable balance for new orders
equitystringTotal account equity
unrealizedstringUnrealised PnL across all positions
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

const balances = await client.getFuturesAccountAssets();

for (const asset of balances.data) {
  console.log(`${asset.currency}: available=${asset.available_balance}, equity=${asset.equity}`);
}

​
Trade Fees

​
getFuturesTradeFeeRate(params)

Returns the personalised maker and taker fee rates for a specific futures contract. Signature 
getFuturesTradeFeeRate(params: {
  symbol: string;
}): Promise<APIResponse<{
  symbol: string;
  taker_fee_rate: string;
  maker_fee_rate: string;
}>>
​
symbol
string
required
Contract symbol (e.g. BTCUSDT).
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

const fees = await client.getFuturesTradeFeeRate({ symbol: 'BTCUSDT' });
console.log(`Maker: ${fees.data.maker_fee_rate} | Taker: ${fees.data.taker_fee_rate}`);

​
Auto Repayment

​
getFuturesAutoRepayment(params?)

Queries auto-repayment records. Defaults to the last 7 days when no time range is specified. Returns a maximum of 20 records per request. Signature 
getFuturesAutoRepayment(
  params?: FuturesAutoRepaymentRequest,
): Promise<FuturesAutoRepaymentApiResponse>
​
start_time
number
Start time as Unix timestamp (ms). Defaults to 7 days ago.
​
end_time
number
End time as Unix timestamp (ms).
​
page
number
Page number for pagination.
​
size
number
Records per page (max 20).
​
from_coin_code
string
Filter by repayment source currency.
​
type
string
Repayment type filter.
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

const repayments = await client.getFuturesAutoRepayment({ page: 1, size: 20 });

console.log(`Total records: ${repayments.data.total}`);
for (const record of repayments.data.list) {
  console.log(`${record.time}: Repaid ${record.from_amount} ${record.from_coin_code} → ${record.to_amount} ${record.to_coin_code}`);
}

​
Cross Collateral

​
getFuturesCrossCollateralInterestLog(params?)

Queries cross-margin interest accrual logs. Defaults to the last 7 days; maximum interval is 90 days. Returns at most 20 records per request. Signature 
getFuturesCrossCollateralInterestLog(
  params?: FuturesCrossCollateralInterestLogRequest,
): Promise<FuturesCrossCollateralInterestLogApiResponse>
​
start_time
number
Start time as Unix timestamp (ms).
​
end_time
number
End time as Unix timestamp (ms).
​
page
number
Page number for pagination.
​
size
number
Records per page (max 20).
​
coin_code
string
Filter by currency (e.g. USDT).
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

const interestLog = await client.getFuturesCrossCollateralInterestLog({
  coin_code: 'USDT',
  page: 1,
  size: 20,
});

console.log(`Total entries: ${interestLog.data.total}`);
for (const entry of interestLog.data.items) {
  console.log(`Interest: ${entry.interest} ${entry.coin_code} @ rate ${entry.rate}`);
}

​
Fund Transfers

​
getFuturesTransfers(params)

Returns transfer history between your spot and futures wallets. Signature 
getFuturesTransfers(params: FuturesAccountTransfersRequest): Promise<
  APIResponse<{ records: FuturesAccountTransfer[] }>
>
​
page
number
required
Page number (1-indexed).
​
limit
number
required
Number of records per page.
​
currency
string
Filter by currency (e.g. USDT).
​
time_start
number
Start time as Unix timestamp (ms).
​
time_end
number
End time as Unix timestamp (ms).
​
recvWindow
number
Request validity window in milliseconds.
Response fields (FuturesAccountTransfer)
FieldTypeDescription
transfer_idstringUnique transfer ID
currencystringTransferred currency
amountstringTransfer amount
typestringspot_to_contract or contract_to_spot
statestringPROCESSING, FINISHED, or FAILED
timestampnumberTransfer time (Unix ms)
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

const transfers = await client.getFuturesTransfers({
  currency: 'USDT',
  page: 1,
  limit: 20,
});

for (const record of transfers.data.records) {
  console.log(`${record.type}: ${record.amount} ${record.currency} — ${record.state}`);
}

​
submitFuturesTransfer(params)

Moves funds between your spot wallet and futures wallet. Only USDT is currently supported. Transfer amount must be between 0.01 and 10,000,000,000. Signature 
submitFuturesTransfer(
  params: SubmitFuturesTransferRequest,
): Promise<APIResponse<FuturesTransferSubmitResult>>
​
currency
string
required
Currency to transfer. Only USDT is supported.
​
amount
string
required
Amount to transfer. Allowed range: 0.01 to 10,000,000,000.
​
type
string
required
Transfer direction:
  • spot_to_contract — Move funds from spot to futures
  • contract_to_spot — Move funds from futures to spot
​
recvWindow
number
Request validity window in milliseconds. Allowed range: (0, 60000]. Default: 5000.
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

const result = await client.submitFuturesTransfer({
  currency: 'USDT',
  amount: '500',
  type: 'spot_to_contract',
});

console.log(`Transferred: ${result.data.amount} ${result.data.currency}`);

​
Sub-Account Management

The following methods allow a main account to move futures funds to and from sub-accounts, and to inspect sub-account balances and transfer history.
Sub-account endpoints use separate API paths depending on whether the initiating party is the main account or a sub-account. Choose the correct method for your use case.

​
submitFuturesSubToMainTransferFromMain(params)

Initiated by the main account: pulls funds from a sub-account’s futures wallet into the main account. Signature 
submitFuturesSubToMainTransferFromMain(
  params: TransferFuturesAssetsRequest,
): Promise<APIResponse<any>>
​
requestNo
string
required
UUID unique identifier for idempotency. Max length 64.
​
amount
string
required
Transfer amount.
​
currency
string
required
Currency. Currently only USDT is supported.
​
subAccount
string
required
Sub-account username.
import { FuturesClientV2 } from 'bitmart-api';
import { randomUUID } from 'crypto';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

await client.submitFuturesSubToMainTransferFromMain({
  requestNo: randomUUID(),
  amount: '100',
  currency: 'USDT',
  subAccount: 'my_sub_account',
});

​
submitFuturesMainToSubTransferFromMain(params)

Initiated by the main account: pushes funds from the main account’s futures wallet to a sub-account. Signature 
submitFuturesMainToSubTransferFromMain(
  params: TransferFuturesAssetsRequest,
): Promise<APIResponse<any>>
Accepts the same TransferFuturesAssetsRequest params as submitFuturesSubToMainTransferFromMain. 
import { FuturesClientV2 } from 'bitmart-api';
import { randomUUID } from 'crypto';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

await client.submitFuturesMainToSubTransferFromMain({
  requestNo: randomUUID(),
  amount: '200',
  currency: 'USDT',
  subAccount: 'my_sub_account',
});

​
submitFuturesSubToMainSubFromSub(params)

Initiated by a sub-account: transfers funds from the sub-account’s futures wallet to the main account. No subAccount field is needed as the authenticated key belongs to the sub-account itself. Signature 
submitFuturesSubToMainSubFromSub(
  params: SubmitFuturesSubToMainSubFromSubRequest,
): Promise<APIResponse<any>>
​
requestNo
string
required
UUID unique identifier. Max length 64.
​
amount
string
required
Transfer amount.
​
currency
string
required
Currency. Only USDT is supported.
import { FuturesClientV2 } from 'bitmart-api';
import { randomUUID } from 'crypto';

// Client authenticated as the sub-account
const subClient = new FuturesClientV2({
  apiKey: process.env.SUB_API_KEY!,
  apiSecret: process.env.SUB_API_SECRET!,
  apiMemo: process.env.SUB_API_MEMO!,
});

await subClient.submitFuturesSubToMainSubFromSub({
  requestNo: randomUUID(),
  amount: '50',
  currency: 'USDT',
});

​
getFuturesSubWallet(params?)

Returns the futures wallet balances for a sub-account. Must be called from the main account. Signature 
getFuturesSubWallet(params?: FuturesSubWalletRequest): Promise<
  APIResponse<{ wallet: AccountCurrencyBalanceV1[] }>
>
​
subAccount
string
required
Sub-account username.
​
currency
string
Optional currency filter (e.g. USDT).
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

const wallet = await client.getFuturesSubWallet({
  subAccount: 'my_sub_account',
  currency: 'USDT',
});

for (const balance of wallet.data.wallet) {
  console.log(`${balance.currency}: ${balance.available}`);
}

​
getFuturesSubTransfers(params)

Returns the futures transfer list for a specific sub-account (called from the main account). Signature 
getFuturesSubTransfers(
  params: FuturesSubTransfersRequest,
): Promise<APIResponse<FuturesAccountSubTransfer[]>>
​
subAccount
string
required
Sub-account username.
​
limit
number
required
Number of records to return. Range: [1, 100].
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

const transfers = await client.getFuturesSubTransfers({
  subAccount: 'my_sub_account',
  limit: 50,
});

for (const t of transfers.data) {
  console.log(`${t.fromAccount} → ${t.toAccount}: ${t.amount} ${t.currency}`);
}

​
getFuturesSubTransferHistory(params)

Returns the authenticated sub-account’s own transfer history. Call this using the sub-account’s API credentials. Signature 
getFuturesSubTransferHistory(params: {
  limit: number;
}): Promise<APIResponse<FuturesAccountSubTransfer[]>>
​
limit
number
required
Number of records to return. Range: [1, 100].
import { FuturesClientV2 } from 'bitmart-api';

// Authenticated as the sub-account
const subClient = new FuturesClientV2({
  apiKey: process.env.SUB_API_KEY!,
  apiSecret: process.env.SUB_API_SECRET!,
  apiMemo: process.env.SUB_API_MEMO!,
});

const history = await subClient.getFuturesSubTransferHistory({ limit: 20 });

for (const record of history.data) {
  console.log(`From: ${record.fromAccount} To: ${record.toAccount} — ${record.amount} ${record.currency}`);
}

​
Affiliate Endpoints

The following methods are available for BitMart futures affiliates to query rebate and trade data for their referred users. All affiliate endpoints require KEYED authentication.

​
getFuturesAffiliateRebates(params)

Returns a paginated list of rebate records for affiliate-referred users over a specified time range. Signature 
getFuturesAffiliateRebates(
  params: FuturesAffiliateRebatesRequest,
): Promise<APIResponse<any>>
​
page
number
required
Page number for pagination.
​
size
number
required
Number of records per page.
​
currency
string
required
Rebate currency (e.g. USDT).
​
user_id
number
Optional filter by referred user ID.
​
rebate_start_time
number
Rebate period start time (Unix ms).
​
rebate_end_time
number
Rebate period end time (Unix ms).
​
register_start_time
number
Filter by user registration start time (Unix ms).
​
register_end_time
number
Filter by user registration end time (Unix ms).
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

const rebates = await client.getFuturesAffiliateRebates({
  page: 1,
  size: 20,
  currency: 'USDT',
});

console.log('Affiliate rebates:', JSON.stringify(rebates.data, null, 2));

​
getFuturesAffiliateTrades(params)

Returns a paginated list of trade records for affiliate-referred users over a specified time range. Signature 
getFuturesAffiliateTrades(
  params: FuturesAffiliateTradesRequest,
): Promise<APIResponse<any>>
​
page
number
required
Page number for pagination.
​
size
number
required
Number of records per page.
​
type
number
required
Trade type: 1 = open, 2 = close.
​
start_time
number
required
Query period start time (Unix ms).
​
end_time
number
required
Query period end time (Unix ms).
​
user_id
number
Optional filter by referred user ID.
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

const trades = await client.getFuturesAffiliateTrades({
  page: 1,
  size: 20,
  type: 1,
  start_time: Date.now() - 7 * 86400_000,
  end_time: Date.now(),
});

console.log('Affiliate trades:', JSON.stringify(trades.data, null, 2));

Build docs developers (and LLMs) love

Get started for freeTalk to us