Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tiagosiebler/binance/llms.txt

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

USDMClient provides typed access to the Binance USD-M Perpetual and Delivery Futures REST API (fapi/v1, fapi/v2, fapi/v3). It handles authentication automatically when API credentials are supplied, and includes every endpoint from market data through account management, algo orders, and convert.
The exhaustive endpoint-to-function mapping, including all broker and data-download endpoints, is available in the endpointFunctionList reference on GitHub.

Installation & Instantiation

import { USDMClient } from 'binance';

// Public (market data only)
const publicClient = new USDMClient();

// Authenticated
const client = new USDMClient({
  api_key: process.env.BINANCE_API_KEY,
  api_secret: process.env.BINANCE_API_SECRET,
});

// Testnet
const testClient = new USDMClient({ testnet: true });

Market Data

These methods are public — no API key is required.
MethodHTTPEndpointDescription
testConnectivity()GETfapi/v1/pingTest server connectivity
getExchangeInfo()GETfapi/v1/exchangeInfoExchange info, symbols, and filters
getOrderBook(params)GETfapi/v1/depthOrder book depth for a symbol
getRpiOrderBook(params)GETfapi/v1/rpiDepthRPI (Retail Price Improvement) order book
getRecentTrades(params)GETfapi/v1/tradesRecent trades
getHistoricalTrades(params)GETfapi/v1/historicalTradesOlder market trades
getAggregateTrades(params)GETfapi/v1/aggTradesCompressed / aggregate trade list
getKlines(params)GETfapi/v1/klinesKline / candlestick data
getContinuousContractKlines(params)GETfapi/v1/continuousKlinesContinuous contract klines
getIndexPriceKlines(params)GETfapi/v1/indexPriceKlinesIndex price klines
getMarkPriceKlines(params)GETfapi/v1/markPriceKlinesMark price klines
getPremiumIndexKlines(params)GETfapi/v1/premiumIndexKlinesPremium index klines
getMarkPrice(params?)GETfapi/v1/premiumIndexMark price and funding rate (one or all symbols)
getFundingRateHistory(params?)GETfapi/v1/fundingRateHistorical funding rates
getFundingRates()GETfapi/v1/fundingInfoCurrent funding rates for all symbols
get24hrChangeStatistics(params?)GETfapi/v1/ticker/24hr24-hour rolling statistics
getSymbolPriceTicker(params?)GETfapi/v1/ticker/priceLatest price
getSymbolPriceTickerV2(params?)GETfapi/v2/ticker/priceLatest price (v2)
getSymbolOrderBookTicker(params?)GETfapi/v1/ticker/bookTickerBest bid/ask
getOpenInterest(params)GETfapi/v1/openInterestPresent open interest for a symbol
getOpenInterestStatistics(params)GETfutures/data/openInterestHistHistorical open interest
getTopTradersLongShortPositionRatio(params)GETfutures/data/topLongShortPositionRatioTop trader position ratio
getTopTradersLongShortAccountRatio(params)GETfutures/data/topLongShortAccountRatioTop trader account ratio
getGlobalLongShortAccountRatio(params)GETfutures/data/globalLongShortAccountRatioGlobal long/short account ratio
getTakerBuySellVolume(params)GETfutures/data/takerlongshortRatioTaker buy/sell volume
getCompositeSymbolIndex(params?)GETfapi/v1/indexInfoComposite symbol index
getIndexPriceConstituents(params)GETfapi/v1/constituentsIndex price constituents
getInsuranceFundBalance(params?)GETfapi/v1/insuranceBalanceInsurance fund balance
getTradingSchedule()GETfapi/v1/tradingScheduleExchange trading schedule
getQuarterlyContractSettlementPrices(params)GETfutures/data/delivery-priceQuarterly contract settlement prices
getBasis(params)GETfutures/data/basisBasis data

Order Management

All methods in this section require authentication.
MethodHTTPEndpointDescription
submitNewOrder(params)POSTfapi/v1/orderPlace a new futures order
testOrder(params)POSTfapi/v1/order/testTest order placement
submitMultipleOrders(orders)POSTfapi/v1/batchOrdersPlace up to 5 orders in a batch
modifyOrder(params)PUTfapi/v1/orderModify an existing LIMIT order
modifyMultipleOrders(orders)PUTfapi/v1/batchOrdersModify multiple orders in batch
getOrderModifyHistory(params)GETfapi/v1/orderAmendmentOrder modification history
cancelOrder(params)DELETEfapi/v1/orderCancel a specific order
cancelMultipleOrders(params)DELETEfapi/v1/batchOrdersCancel multiple orders
cancelAllOpenOrders(params)DELETEfapi/v1/allOpenOrdersCancel all open orders for a symbol
setCancelOrdersOnTimeout(params)POSTfapi/v1/countdownCancelAllAuto-cancel all orders after a timeout
getOrder(params)GETfapi/v1/orderQuery a specific order
getAllOrders(params)GETfapi/v1/allOrdersAll orders (open, cancelled, filled)
getAllOpenOrders(params?)GETfapi/v1/openOrdersAll current open orders
getCurrentOpenOrder(params)GETfapi/v1/openOrderQuery a single open order
getForceOrders(params?)GETfapi/v1/forceOrdersForced liquidation orders
getAccountTrades(params)GETfapi/v1/userTradesAccount trade list

Code Example — Order Management

import { USDMClient } from 'binance';

const client = new USDMClient({
  api_key: process.env.BINANCE_API_KEY,
  api_secret: process.env.BINANCE_API_SECRET,
});

// Place a LIMIT BUY order
const order = await client.submitNewOrder({
  symbol: 'BTCUSDT',
  side: 'BUY',
  type: 'LIMIT',
  timeInForce: 'GTC',
  quantity: 0.01,
  price: 50000,
});
console.log('Order ID:', order.orderId);

// Modify the order (new price)
await client.modifyOrder({
  symbol: 'BTCUSDT',
  orderId: order.orderId,
  side: 'BUY',
  quantity: 0.01,
  price: 49500,
});

// Cancel all open orders for the symbol
await client.cancelAllOpenOrders({ symbol: 'BTCUSDT' });

Position Control

MethodHTTPEndpointDescription
setLeverage(params)POSTfapi/v1/leverageSet leverage for a symbol
setMarginType(params)POSTfapi/v1/marginTypeSwitch between CROSSED and ISOLATED margin
setPositionMode(params)POSTfapi/v1/positionSide/dualToggle Hedge Mode (dual-side positions)
setMultiAssetsMode(params)POSTfapi/v1/multiAssetsMarginEnable or disable multi-assets margin mode
setIsolatedPositionMargin(params)POSTfapi/v1/positionMarginAdjust isolated position margin
getPositions(params?)GETfapi/v2/positionRiskPosition information (deprecated, use v3)
getPositionsV3(params?)GETfapi/v3/positionRiskPosition information (v3, recommended)
getPositionMarginChangeHistory(params)GETfapi/v1/positionMargin/historyIsolated margin change history
getADLQuantileEstimation(params?)GETfapi/v1/adlQuantileADL quantile estimation
getSymbolAdlRisk(params?)GETfapi/v1/symbolAdlRiskSymbol ADL risk
getCurrentPositionMode()GETfapi/v1/positionSide/dualQuery current position mode
getMultiAssetsMode()GETfapi/v1/multiAssetsMarginQuery multi-assets mode status
getNotionalAndLeverageBrackets(params?)GETfapi/v1/leverageBracketNotional and leverage brackets

Account

MethodHTTPEndpointDescription
getBalanceV3()GETfapi/v3/balanceAccount balance (recommended)
getBalance()GETfapi/v2/balanceAccount balance (deprecated, use v3)
getAccountInformationV3()GETfapi/v3/accountAccount information (recommended)
getAccountInformation()GETfapi/v2/accountAccount information (deprecated, use v3)
getAccountCommissionRate(params)GETfapi/v1/commissionRateCommission rates for a symbol
getFuturesAccountConfig()GETfapi/v1/accountConfigFutures account configuration
getFuturesSymbolConfig(params)GETfapi/v1/symbolConfigSymbol configuration
getIncomeHistory(params?)GETfapi/v1/incomeIncome / PnL history
getApiQuantitativeRulesIndicators(params?)GETfapi/v1/apiTradingStatusAPI quantitative trading rules indicators
getUserForceOrders()GETfapi/v1/rateLimit/orderOrder count against rate limits
setBNBBurnEnabled(params)POSTfapi/v1/feeBurnEnable or disable BNB fee discount
getBNBBurnStatus()GETfapi/v1/feeBurnBNB fee discount status

Algo Orders

Conditional orders migrated to the Algo Service effective 2025-12-02. Use submitNewAlgoOrder and the related algo endpoints going forward.
MethodHTTPEndpointDescription
submitNewAlgoOrder(params)POSTfapi/v1/algoOrderPlace a new algo (conditional) order
cancelAlgoOrder(params)DELETEfapi/v1/algoOrderCancel a specific algo order
cancelAllAlgoOpenOrders(params)DELETEfapi/v1/algoOpenOrdersCancel all open algo orders for a symbol
getAlgoOrder(params)GETfapi/v1/algoOrderQuery a specific algo order
getOpenAlgoOrders(params?)GETfapi/v1/openAlgoOrdersAll open algo orders
getAllAlgoOrders(params)GETfapi/v1/allAlgoOrdersAll algo orders (historical)

Convert

MethodHTTPEndpointDescription
getAllConvertPairs(params?)GETfapi/v1/convert/exchangeInfoAll supported futures convert pairs
submitConvertQuoteRequest(params)POSTfapi/v1/convert/getQuoteRequest a convert quote
acceptConvertQuote(params)POSTfapi/v1/convert/acceptQuoteAccept a convert quote
getConvertOrderStatus(params)GETfapi/v1/convert/orderStatusConvert order status

User Data Stream

MethodHTTPEndpointDescription
getFuturesUserDataListenKey()POSTfapi/v1/listenKeyStart a user data stream
keepAliveFuturesUserDataListenKey()PUTfapi/v1/listenKeyKeep-alive a user data stream
closeFuturesUserDataListenKey()DELETEfapi/v1/listenKeyClose a user data stream

Full Usage Example

import { USDMClient } from 'binance';

const client = new USDMClient({
  api_key: process.env.BINANCE_API_KEY,
  api_secret: process.env.BINANCE_API_SECRET,
});

async function main() {
  // --- Market data ---
  const markPrice = await client.getMarkPrice({ symbol: 'BTCUSDT' });
  console.log('Mark price:', (markPrice as any).markPrice);

  const fundingHistory = await client.getFundingRateHistory({
    symbol: 'BTCUSDT',
    limit: 5,
  });
  console.log('Latest funding rate:', fundingHistory[0].fundingRate);

  // --- Account ---
  const balances = await client.getBalanceV3();
  const usdtBal = balances.find((b) => b.asset === 'USDT');
  console.log('USDT balance:', usdtBal?.availableBalance);

  // --- Position setup ---
  await client.setLeverage({ symbol: 'BTCUSDT', leverage: 10 });
  await client.setMarginType({ symbol: 'BTCUSDT', marginType: 'ISOLATED' });

  // --- Positions ---
  const positions = await client.getPositionsV3({ symbol: 'BTCUSDT' });
  console.log('Position amt:', positions[0]?.positionAmt);

  // --- Income history ---
  const income = await client.getIncomeHistory({
    symbol: 'BTCUSDT',
    incomeType: 'REALIZED_PNL',
    limit: 10,
  });
  console.log('Recent PnL entries:', income.length);
}

main();
Use getPositionsV3() (fapi/v3) and getBalanceV3() (fapi/v3) in all new code. The v2 variants are deprecated and may be removed in a future API update.

Build docs developers (and LLMs) love