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.
| Method | HTTP | Endpoint | Description |
|---|
testConnectivity() | GET | fapi/v1/ping | Test server connectivity |
getExchangeInfo() | GET | fapi/v1/exchangeInfo | Exchange info, symbols, and filters |
getOrderBook(params) | GET | fapi/v1/depth | Order book depth for a symbol |
getRpiOrderBook(params) | GET | fapi/v1/rpiDepth | RPI (Retail Price Improvement) order book |
getRecentTrades(params) | GET | fapi/v1/trades | Recent trades |
getHistoricalTrades(params) | GET | fapi/v1/historicalTrades | Older market trades |
getAggregateTrades(params) | GET | fapi/v1/aggTrades | Compressed / aggregate trade list |
getKlines(params) | GET | fapi/v1/klines | Kline / candlestick data |
getContinuousContractKlines(params) | GET | fapi/v1/continuousKlines | Continuous contract klines |
getIndexPriceKlines(params) | GET | fapi/v1/indexPriceKlines | Index price klines |
getMarkPriceKlines(params) | GET | fapi/v1/markPriceKlines | Mark price klines |
getPremiumIndexKlines(params) | GET | fapi/v1/premiumIndexKlines | Premium index klines |
getMarkPrice(params?) | GET | fapi/v1/premiumIndex | Mark price and funding rate (one or all symbols) |
getFundingRateHistory(params?) | GET | fapi/v1/fundingRate | Historical funding rates |
getFundingRates() | GET | fapi/v1/fundingInfo | Current funding rates for all symbols |
get24hrChangeStatistics(params?) | GET | fapi/v1/ticker/24hr | 24-hour rolling statistics |
getSymbolPriceTicker(params?) | GET | fapi/v1/ticker/price | Latest price |
getSymbolPriceTickerV2(params?) | GET | fapi/v2/ticker/price | Latest price (v2) |
getSymbolOrderBookTicker(params?) | GET | fapi/v1/ticker/bookTicker | Best bid/ask |
getOpenInterest(params) | GET | fapi/v1/openInterest | Present open interest for a symbol |
getOpenInterestStatistics(params) | GET | futures/data/openInterestHist | Historical open interest |
getTopTradersLongShortPositionRatio(params) | GET | futures/data/topLongShortPositionRatio | Top trader position ratio |
getTopTradersLongShortAccountRatio(params) | GET | futures/data/topLongShortAccountRatio | Top trader account ratio |
getGlobalLongShortAccountRatio(params) | GET | futures/data/globalLongShortAccountRatio | Global long/short account ratio |
getTakerBuySellVolume(params) | GET | futures/data/takerlongshortRatio | Taker buy/sell volume |
getCompositeSymbolIndex(params?) | GET | fapi/v1/indexInfo | Composite symbol index |
getIndexPriceConstituents(params) | GET | fapi/v1/constituents | Index price constituents |
getInsuranceFundBalance(params?) | GET | fapi/v1/insuranceBalance | Insurance fund balance |
getTradingSchedule() | GET | fapi/v1/tradingSchedule | Exchange trading schedule |
getQuarterlyContractSettlementPrices(params) | GET | futures/data/delivery-price | Quarterly contract settlement prices |
getBasis(params) | GET | futures/data/basis | Basis data |
Order Management
All methods in this section require authentication.
| Method | HTTP | Endpoint | Description |
|---|
submitNewOrder(params) | POST | fapi/v1/order | Place a new futures order |
testOrder(params) | POST | fapi/v1/order/test | Test order placement |
submitMultipleOrders(orders) | POST | fapi/v1/batchOrders | Place up to 5 orders in a batch |
modifyOrder(params) | PUT | fapi/v1/order | Modify an existing LIMIT order |
modifyMultipleOrders(orders) | PUT | fapi/v1/batchOrders | Modify multiple orders in batch |
getOrderModifyHistory(params) | GET | fapi/v1/orderAmendment | Order modification history |
cancelOrder(params) | DELETE | fapi/v1/order | Cancel a specific order |
cancelMultipleOrders(params) | DELETE | fapi/v1/batchOrders | Cancel multiple orders |
cancelAllOpenOrders(params) | DELETE | fapi/v1/allOpenOrders | Cancel all open orders for a symbol |
setCancelOrdersOnTimeout(params) | POST | fapi/v1/countdownCancelAll | Auto-cancel all orders after a timeout |
getOrder(params) | GET | fapi/v1/order | Query a specific order |
getAllOrders(params) | GET | fapi/v1/allOrders | All orders (open, cancelled, filled) |
getAllOpenOrders(params?) | GET | fapi/v1/openOrders | All current open orders |
getCurrentOpenOrder(params) | GET | fapi/v1/openOrder | Query a single open order |
getForceOrders(params?) | GET | fapi/v1/forceOrders | Forced liquidation orders |
getAccountTrades(params) | GET | fapi/v1/userTrades | Account 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
| Method | HTTP | Endpoint | Description |
|---|
setLeverage(params) | POST | fapi/v1/leverage | Set leverage for a symbol |
setMarginType(params) | POST | fapi/v1/marginType | Switch between CROSSED and ISOLATED margin |
setPositionMode(params) | POST | fapi/v1/positionSide/dual | Toggle Hedge Mode (dual-side positions) |
setMultiAssetsMode(params) | POST | fapi/v1/multiAssetsMargin | Enable or disable multi-assets margin mode |
setIsolatedPositionMargin(params) | POST | fapi/v1/positionMargin | Adjust isolated position margin |
getPositions(params?) | GET | fapi/v2/positionRisk | Position information (deprecated, use v3) |
getPositionsV3(params?) | GET | fapi/v3/positionRisk | Position information (v3, recommended) |
getPositionMarginChangeHistory(params) | GET | fapi/v1/positionMargin/history | Isolated margin change history |
getADLQuantileEstimation(params?) | GET | fapi/v1/adlQuantile | ADL quantile estimation |
getSymbolAdlRisk(params?) | GET | fapi/v1/symbolAdlRisk | Symbol ADL risk |
getCurrentPositionMode() | GET | fapi/v1/positionSide/dual | Query current position mode |
getMultiAssetsMode() | GET | fapi/v1/multiAssetsMargin | Query multi-assets mode status |
getNotionalAndLeverageBrackets(params?) | GET | fapi/v1/leverageBracket | Notional and leverage brackets |
Account
| Method | HTTP | Endpoint | Description |
|---|
getBalanceV3() | GET | fapi/v3/balance | Account balance (recommended) |
getBalance() | GET | fapi/v2/balance | Account balance (deprecated, use v3) |
getAccountInformationV3() | GET | fapi/v3/account | Account information (recommended) |
getAccountInformation() | GET | fapi/v2/account | Account information (deprecated, use v3) |
getAccountCommissionRate(params) | GET | fapi/v1/commissionRate | Commission rates for a symbol |
getFuturesAccountConfig() | GET | fapi/v1/accountConfig | Futures account configuration |
getFuturesSymbolConfig(params) | GET | fapi/v1/symbolConfig | Symbol configuration |
getIncomeHistory(params?) | GET | fapi/v1/income | Income / PnL history |
getApiQuantitativeRulesIndicators(params?) | GET | fapi/v1/apiTradingStatus | API quantitative trading rules indicators |
getUserForceOrders() | GET | fapi/v1/rateLimit/order | Order count against rate limits |
setBNBBurnEnabled(params) | POST | fapi/v1/feeBurn | Enable or disable BNB fee discount |
getBNBBurnStatus() | GET | fapi/v1/feeBurn | BNB 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.
| Method | HTTP | Endpoint | Description |
|---|
submitNewAlgoOrder(params) | POST | fapi/v1/algoOrder | Place a new algo (conditional) order |
cancelAlgoOrder(params) | DELETE | fapi/v1/algoOrder | Cancel a specific algo order |
cancelAllAlgoOpenOrders(params) | DELETE | fapi/v1/algoOpenOrders | Cancel all open algo orders for a symbol |
getAlgoOrder(params) | GET | fapi/v1/algoOrder | Query a specific algo order |
getOpenAlgoOrders(params?) | GET | fapi/v1/openAlgoOrders | All open algo orders |
getAllAlgoOrders(params) | GET | fapi/v1/allAlgoOrders | All algo orders (historical) |
Convert
| Method | HTTP | Endpoint | Description |
|---|
getAllConvertPairs(params?) | GET | fapi/v1/convert/exchangeInfo | All supported futures convert pairs |
submitConvertQuoteRequest(params) | POST | fapi/v1/convert/getQuote | Request a convert quote |
acceptConvertQuote(params) | POST | fapi/v1/convert/acceptQuote | Accept a convert quote |
getConvertOrderStatus(params) | GET | fapi/v1/convert/orderStatus | Convert order status |
User Data Stream
| Method | HTTP | Endpoint | Description |
|---|
getFuturesUserDataListenKey() | POST | fapi/v1/listenKey | Start a user data stream |
keepAliveFuturesUserDataListenKey() | PUT | fapi/v1/listenKey | Keep-alive a user data stream |
closeFuturesUserDataListenKey() | DELETE | fapi/v1/listenKey | Close 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.