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.

PortfolioClient provides typed access to the Binance Portfolio Margin REST API (papi/v1, papi/v2). Portfolio Margin unifies USD-M Futures (UM), COIN-M Futures (CM), and Margin positions under a single cross-margin account, enabling higher capital efficiency through shared collateral. All authenticated endpoints require API credentials with Portfolio Margin permissions enabled.
The complete endpoint-to-function mapping for PortfolioClient is available in the endpointFunctionList reference on GitHub.

Installation & Instantiation

import { PortfolioClient } from 'binance';

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

Account

MethodHTTPEndpointDescription
testConnectivity()GETpapi/v1/pingTest server connectivity
getBalance(params?)GETpapi/v1/balancePortfolio Margin account balance per asset
getAccountInfo()GETpapi/v1/accountFull Portfolio Margin account information
getMarginMaxBorrow(params)GETpapi/v1/margin/maxBorrowableMaximum borrowable amount for an asset
getMarginMaxWithdraw(params)GETpapi/v1/margin/maxWithdrawMaximum withdrawable amount for an asset
getUMAccount()GETpapi/v1/um/accountUM (USD-M) account assets and positions
getUMAccountV2()GETpapi/v2/um/accountUM account info (v2)
getCMAccount()GETpapi/v1/cm/accountCM (COIN-M) account assets and positions
getUMAccountConfig()GETpapi/v1/um/accountConfigUM account configuration
getUMSymbolConfig(params?)GETpapi/v1/um/symbolConfigUM symbol configuration
getAutoRepayFuturesStatus()GETpapi/v1/repay-futures-switchAuto-repay futures status
updateAutoRepayFuturesStatus(params)POSTpapi/v1/repay-futures-switchToggle auto-repay futures
repayFuturesNegativeBalance()POSTpapi/v1/repay-futures-negative-balanceRepay a futures negative balance
autoCollectFunds()POSTpapi/v1/auto-collectionCollect assets to Portfolio Margin account
transferAssetFuturesMargin(params)POSTpapi/v1/asset-collectionTransfer an asset to the futures margin wallet
transferBNB(params)POSTpapi/v1/bnb-transferTransfer BNB between UM and Portfolio
signTradFiPerpsContract()POSTpapi/v1/um/stock/contractSign TradFi Perps agreement

UM Orders (USD-M under Portfolio)

MethodHTTPEndpointDescription
submitNewUMOrder(params)POSTpapi/v1/um/orderPlace a new UM futures order
submitNewUMAlgoOrder(params)POSTpapi/v1/um/algo/orderPlace a new UM algo (conditional) order
modifyUMOrder(params)PUTpapi/v1/um/orderModify an existing UM order
cancelUMOrder(params)DELETEpapi/v1/um/orderCancel a specific UM order
cancelAllUMOrders(params)DELETEpapi/v1/um/allOpenOrdersCancel all open UM orders for a symbol
cancelUMAlgoOrder(params)DELETEpapi/v1/um/algo/orderCancel a specific UM algo order
cancelAllUMAlgoOpenOrders(params)DELETEpapi/v1/um/algo/allOpenOrdersCancel all UM algo open orders
getUMOrder(params)GETpapi/v1/um/orderQuery a specific UM order
getAllUMOrders(params)GETpapi/v1/um/allOrdersAll UM orders (open, cancelled, filled)
getUMOpenOrder(params)GETpapi/v1/um/openOrderQuery a specific open UM order
getAllUMOpenOrders(params)GETpapi/v1/um/openOrdersAll open UM orders
getUMAlgoOrder(params)GETpapi/v1/um/algo/algoOrderQuery a specific UM algo order
getUMAlgoOpenOrders(params?)GETpapi/v1/um/algo/openAlgoOrdersAll open UM algo orders
getAllUMAlgoOrders(params)GETpapi/v1/um/algo/allAlgoOrdersAll UM algo orders (historical)
getUMForceOrders(params)GETpapi/v1/um/forceOrdersUM forced liquidation orders
getUMOrderModificationHistory(params)GETpapi/v1/um/orderAmendmentUM order modification history
getUMTrades(params)GETpapi/v1/um/userTradesUM trade list
getUMADLQuantile(params)GETpapi/v1/um/adlQuantileUM ADL quantile estimation
getUMFeeBurnStatus()GETpapi/v1/um/feeBurnUM fee burn (BNB discount) status
toggleUMFeeBurn(params)POSTpapi/v1/um/feeBurnToggle UM fee burn status

Code Example — UM Orders

import { PortfolioClient } from 'binance';

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

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

// Cancel it
await client.cancelUMOrder({
  symbol: 'BTCUSDT',
  orderId: order.orderId,
});

CM Orders (COIN-M under Portfolio)

MethodHTTPEndpointDescription
submitNewCMOrder(params)POSTpapi/v1/cm/orderPlace a new CM futures order
submitNewCMConditionalOrder(params)POSTpapi/v1/cm/conditional/orderPlace a new CM conditional order
modifyCMOrder(params)PUTpapi/v1/cm/orderModify an existing CM order
cancelCMOrder(params)DELETEpapi/v1/cm/orderCancel a specific CM order
cancelAllCMOrders(params)DELETEpapi/v1/cm/allOpenOrdersCancel all open CM orders
cancelCMConditionalOrder(params)DELETEpapi/v1/cm/conditional/orderCancel a specific CM conditional order
cancelAllCMConditionalOrders(params)DELETEpapi/v1/cm/conditional/allOpenOrdersCancel all CM conditional orders
getCMOrder(params)GETpapi/v1/cm/orderQuery a specific CM order
getAllCMOrders(params)GETpapi/v1/cm/allOrdersAll CM orders (open, cancelled, filled)
getCMOpenOrder(params)GETpapi/v1/cm/openOrderQuery a specific open CM order
getAllCMOpenOrders(params)GETpapi/v1/cm/openOrdersAll open CM orders
getCMOpenConditionalOrders(params)GETpapi/v1/cm/conditional/openOrdersAll open CM conditional orders
getCMOpenConditionalOrder(params)GETpapi/v1/cm/conditional/openOrderQuery a single CM conditional order
getAllCMConditionalOrders(params)GETpapi/v1/cm/conditional/allOrdersAll CM conditional orders
getCMConditionalOrderHistory(params)GETpapi/v1/cm/conditional/orderHistoryCM conditional order history
getCMForceOrders(params)GETpapi/v1/cm/forceOrdersCM forced liquidation orders
getCMOrderModificationHistory(params)GETpapi/v1/cm/orderAmendmentCM order modification history
getCMTrades(params)GETpapi/v1/cm/userTradesCM trade list
getCMADLQuantile(params)GETpapi/v1/cm/adlQuantileCM ADL quantile estimation

Margin Orders

MethodHTTPEndpointDescription
submitNewMarginOrder(params)POSTpapi/v1/margin/orderPlace a new margin order
submitNewMarginOCO(params)POSTpapi/v1/margin/order/ocoPlace a margin OCO order
submitMarginLoan(params)POSTpapi/v1/marginLoanBorrow margin assets
submitMarginRepay(params)POSTpapi/v1/repayLoanRepay margin loan
repayMarginDebt(params)POSTpapi/v1/margin/repay-debtRepay margin debt
cancelMarginOrder(params)DELETEpapi/v1/margin/orderCancel a margin order
cancelMarginOCO(params)DELETEpapi/v1/margin/orderListCancel a margin OCO order list
cancelAllMarginOrders(params)DELETEpapi/v1/margin/allOpenOrdersCancel all open margin orders
getMarginOrder(params)GETpapi/v1/margin/orderQuery a specific margin order
getMarginOpenOrders(params)GETpapi/v1/margin/openOrdersAll open margin orders
getAllMarginOrders(params)GETpapi/v1/margin/allOrdersAll margin orders
getMarginOCO(params)GETpapi/v1/margin/orderListQuery a specific margin OCO
getAllMarginOCO(params)GETpapi/v1/margin/allOrderListAll margin OCO order lists
getMarginOpenOCO()GETpapi/v1/margin/openOrderListAll open margin OCO order lists
getMarginForceOrders(params)GETpapi/v1/margin/forceOrdersMargin forced liquidation records
getMarginTrades(params)GETpapi/v1/margin/myTradesMargin trade list
getMarginLoanRecords(params)GETpapi/v1/margin/marginLoanMargin loan records
getMarginRepayRecords(params)GETpapi/v1/margin/repayLoanMargin repay records
getMarginInterestHistory(params?)GETpapi/v1/margin/marginInterestHistoryMargin interest history

Position & Leverage

MethodHTTPEndpointDescription
getUMPosition(params?)GETpapi/v1/um/positionRiskUM open positions
getCMPosition(params?)GETpapi/v1/cm/positionRiskCM open positions
updateUMLeverage(params)POSTpapi/v1/um/leverageSet leverage for a UM symbol
updateCMLeverage(params)POSTpapi/v1/cm/leverageSet leverage for a CM symbol
updateUMPositionMode(params)POSTpapi/v1/um/positionSide/dualToggle UM Hedge Mode
updateCMPositionMode(params)POSTpapi/v1/cm/positionSide/dualToggle CM Hedge Mode
getUMPositionMode()GETpapi/v1/um/positionSide/dualQuery UM position mode
getCMPositionMode()GETpapi/v1/cm/positionSide/dualQuery CM position mode
getUMLeverageBrackets(params?)GETpapi/v1/um/leverageBracketUM leverage brackets
getCMLeverageBrackets(params?)GETpapi/v1/cm/leverageBracketCM leverage brackets
getUMCommissionRate(params)GETpapi/v1/um/commissionRateUM maker/taker commission rates
getCMCommissionRate(params)GETpapi/v1/cm/commissionRateCM maker/taker commission rates
getUMTradingStatus(params?)GETpapi/v1/um/apiTradingStatusUM API trading status / rules indicators

Income & History

MethodHTTPEndpointDescription
getUMIncomeHistory(params?)GETpapi/v1/um/incomeUM income history (PnL, funding, etc.)
getCMIncomeHistory(params?)GETpapi/v1/cm/incomeCM income history
getPortfolioNegativeBalanceInterestHistory(params?)GETpapi/v1/portfolio/interest-historyNegative balance interest history
getUMTradeHistoryDownloadId(params)GETpapi/v1/um/trade/asynGet download ID for UM trade history
getUMTradeDownloadLink(params)GETpapi/v1/um/trade/asyn/idGet download link for UM trade history
getUMOrderHistoryDownloadId(params)GETpapi/v1/um/order/asynGet download ID for UM order history
getUMOrderDownloadLink(params)GETpapi/v1/um/order/asyn/idGet download link for UM order history
getUMTransactionHistoryDownloadId(params)GETpapi/v1/um/income/asynGet download ID for UM transaction history
getUMTransactionDownloadLink(params)GETpapi/v1/um/income/asyn/idGet download link for UM transaction history

User Data Stream

MethodHTTPEndpointDescription
getPMUserDataListenKey()POSTpapi/v1/listenKeyStart a Portfolio Margin user data stream
keepAlivePMUserDataListenKey()PUTpapi/v1/listenKeyKeep a Portfolio Margin user data stream alive
closePMUserDataListenKey()DELETEpapi/v1/listenKeyClose a Portfolio Margin user data stream

Full Usage Example

import { PortfolioClient } from 'binance';

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

async function main() {
  // --- Account overview ---
  const account = await client.getAccountInfo();
  console.log('uniMMR:', account.uniMMR); // Unified Maintenance Margin Ratio

  const balances = await client.getBalance();
  console.log('Account balances:', balances.length, 'assets');

  // --- UM positions ---
  const umPositions = await client.getUMPosition({ symbol: 'BTCUSDT' });
  console.log('BTC UM position:', umPositions[0]?.positionAmt);

  // --- Set leverage ---
  await client.updateUMLeverage({ symbol: 'BTCUSDT', leverage: 10 });

  // --- Place a UM order ---
  const order = await client.submitNewUMOrder({
    symbol: 'BTCUSDT',
    side: 'BUY',
    type: 'MARKET',
    quantity: '0.001',
  });
  console.log('UM Order status:', order.status);

  // --- Place a Margin order ---
  const marginOrder = await client.submitNewMarginOrder({
    symbol: 'ETHUSDT',
    side: 'BUY',
    type: 'LIMIT',
    timeInForce: 'GTC',
    quantity: '0.1',
    price: '2000',
  });
  console.log('Margin Order ID:', marginOrder.orderId);

  // --- UM income ---
  const income = await client.getUMIncomeHistory({
    symbol: 'BTCUSDT',
    incomeType: 'REALIZED_PNL',
    limit: 5,
  });
  console.log('Recent UM PnL:', income.map((i) => i.income));
}

main();
Portfolio Margin’s uniMMR (Unified Maintenance Margin Ratio) is the key risk metric for the whole account. Monitor it via getAccountInfo(). If uniMMR drops below 1.0, the account may face liquidation across all sub-positions simultaneously.

Build docs developers (and LLMs) love