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 is the REST client for Binance’s Portfolio Margin programme — a unified margin model that combines Spot (cross-margin), USD-M Futures (UM), and COIN-M Futures (CM) positions into a single account. Under Portfolio Margin, margin requirements are calculated across all three product groups simultaneously, allowing positions to offset each other and potentially reducing overall margin consumption. All Portfolio Margin API calls target the papi base URL key and route through papi.binance.com.

What is Portfolio Margin?

Portfolio Margin (PM) is an advanced risk-management framework available to qualified Binance users. Instead of siloing your Spot, USD-M Futures, and COIN-M Futures margin separately, Portfolio Margin aggregates them into one unified margin calculation:
  • Unified collateral — USDT, BNB, BTC and other approved assets contribute to a single margin pool.
  • Cross-product netting — A long BTC Spot position can partially offset a short BTC USD-M Futures position, reducing net margin requirements.
  • Three sub-accounts — UM (USD-M Futures), CM (COIN-M Futures), and Margin sub-accounts operate under the same unified margin umbrella.
Portfolio Margin requires account qualification. Check your eligibility and apply through the Binance Portfolio Margin page before using PortfolioClient. See Binance Portfolio Margin docs for details.

Installation

1

Install the package

npm install binance
2

Import PortfolioClient

import { PortfolioClient } from 'binance';
// CommonJS: const { PortfolioClient } = require('binance');
3

Instantiate the client

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

Constructor Options

const client = new PortfolioClient(
  restClientOptions,  // RestClientOptions (optional)
  requestOptions,     // AxiosRequestConfig (optional)
);
api_key
string
Your Binance API key. Required for all Portfolio Margin endpoints — the API is entirely private.
api_secret
string
Your Binance API secret. Supports HMAC, RSA, and Ed25519 — key type is detected automatically.
beautifyResponses
boolean
default:"false"
When true, numeric strings in responses are parsed into JavaScript numbers for well-known fields.
testnet
boolean
default:"false"
Routes requests to the Binance testnet environment when available. Portfolio Margin endpoints use the papi base URL key.
demoTrading
boolean
default:"false"
Routes requests to Binance’s Demo Trading environment. Uses real market data with simulated order execution — the preferred option for testing Portfolio Margin strategies.

Base URL

KeyProduction URL
papihttps://papi.binance.com

Method Categories

Account & Balance

MethodEndpointDescription
testConnectivity()GET papi/v1/pingTest API connectivity
getAccountInfo()GET papi/v1/accountFull Portfolio Margin account information
getBalance(params?)GET papi/v1/balanceBalance for a specific or all assets
getUMAccount()GET papi/v1/um/accountUSD-M Futures sub-account details
getCMAccount()GET papi/v1/cm/accountCOIN-M Futures sub-account details
getUMAccountConfig()GET papi/v1/um/accountConfigUM account-level configuration
getUMSymbolConfig(params?)GET papi/v1/um/symbolConfigUM symbol configuration

UM (USD-M Futures) Orders

MethodEndpointDescription
submitNewUMOrder(params)POST papi/v1/um/orderPlace a UM futures order
submitNewUMAlgoOrder(params)POST papi/v1/um/algo/orderPlace a UM algo order (TWAP/VP)
cancelUMOrder(params)DELETE papi/v1/um/orderCancel a UM order
cancelAllUMOrders(params)DELETE papi/v1/um/allOpenOrdersCancel all open UM orders for a symbol
cancelUMAlgoOrder(params)DELETE papi/v1/um/algo/orderCancel a UM algo order
cancelAllUMAlgoOpenOrders(params)DELETE papi/v1/um/algo/allOpenOrdersCancel all open UM algo orders
modifyUMOrder(params)PUT papi/v1/um/orderModify an existing UM order
getUMOrder(params)GET papi/v1/um/orderQuery a specific UM order
getAllUMOrders(params)GET papi/v1/um/allOrdersFull UM order history
getUMOpenOrder(params)GET papi/v1/um/openOrderQuery a specific open UM order
getAllUMOpenOrders(params?)GET papi/v1/um/openOrdersAll open UM orders
getAllUMAlgoOrders(params)GET papi/v1/um/algo/allAlgoOrdersAll UM algo orders
getUMAlgoOpenOrders(params?)GET papi/v1/um/algo/openAlgoOrdersOpen UM algo orders
getUMAlgoOrder(params)GET papi/v1/um/algo/algoOrderQuery a specific UM algo order
getUMTrades(params)GET papi/v1/um/userTradesUM trade history
getUMForceOrders(params)GET papi/v1/um/forceOrdersUM liquidation orders
getUMOrderModificationHistory(params)GET papi/v1/um/orderAmendmentUM order modification history

CM (COIN-M Futures) Orders

MethodEndpointDescription
submitNewCMOrder(params)POST papi/v1/cm/orderPlace a CM futures order
submitNewCMConditionalOrder(params)POST papi/v1/cm/conditional/orderPlace a CM conditional order
cancelCMOrder(params)DELETE papi/v1/cm/orderCancel a CM order
cancelAllCMOrders(params)DELETE papi/v1/cm/allOpenOrdersCancel all open CM orders
cancelCMConditionalOrder(params)DELETE papi/v1/cm/conditional/orderCancel a CM conditional order
modifyCMOrder(params)PUT papi/v1/cm/orderModify an existing CM order
getCMOrder(params)GET papi/v1/cm/orderQuery a specific CM order
getAllCMOrders(params)GET papi/v1/cm/allOrdersFull CM order history
getCMOpenOrder(params)GET papi/v1/cm/openOrderQuery a specific open CM order
getAllCMOpenOrders(params?)GET papi/v1/cm/openOrdersAll open CM orders
getCMTrades(params)GET papi/v1/cm/userTradesCM trade history
getCMForceOrders(params)GET papi/v1/cm/forceOrdersCM liquidation orders
getCMOrderModificationHistory(params)GET papi/v1/cm/orderAmendmentCM order modification history

Margin Orders

MethodEndpointDescription
submitNewMarginOrder(params)POST papi/v1/margin/orderPlace a margin order
submitNewMarginOCO(params)POST papi/v1/margin/order/ocoPlace a margin OCO order
submitMarginLoan(params)POST papi/v1/marginLoanBorrow margin assets
submitMarginRepay(params)POST papi/v1/repayLoanRepay margin loan
cancelMarginOrder(params)DELETE papi/v1/margin/orderCancel a margin order
cancelMarginOCO(params)DELETE papi/v1/margin/orderListCancel a margin OCO order
cancelAllMarginOrders(params)DELETE papi/v1/margin/allOpenOrdersCancel all open margin orders
getMarginOrder(params)GET papi/v1/margin/orderQuery a specific margin order
getMarginOpenOrders(params)GET papi/v1/margin/openOrdersOpen margin orders for a symbol
getAllMarginOrders(params)GET papi/v1/margin/allOrdersFull margin order history
getMarginOCO(params)GET papi/v1/margin/orderListQuery a margin OCO
getAllMarginOCO(params)GET papi/v1/margin/allOrderListAll margin OCO orders
getMarginTrades(params)GET papi/v1/margin/myTradesMargin trade history
repayMarginDebt(params)POST papi/v1/margin/repay-debtRepay margin debt

Position Management

MethodEndpointDescription
getUMPosition(params?)GET papi/v1/um/positionRiskUM open positions
getCMPosition(params?)GET papi/v1/cm/positionRiskCM open positions
updateUMLeverage(params)POST papi/v1/um/leverageSet UM leverage for a symbol
updateCMLeverage(params)POST papi/v1/cm/leverageSet CM leverage for a symbol
updateUMPositionMode(params)POST papi/v1/um/positionSide/dualToggle UM one-way / hedge mode
updateCMPositionMode(params)POST papi/v1/cm/positionSide/dualToggle CM one-way / hedge mode
getUMPositionMode()GET papi/v1/um/positionSide/dualQuery UM position mode
getCMPositionMode()GET papi/v1/cm/positionSide/dualQuery CM position mode
getUMLeverageBrackets(params?)GET papi/v1/um/leverageBracketUM leverage brackets
getCMLeverageBrackets(params?)GET papi/v1/cm/leverageBracketCM leverage brackets
getUMADLQuantile(params?)GET papi/v1/um/adlQuantileUM ADL quantile
getCMADLQuantile(params?)GET papi/v1/cm/adlQuantileCM ADL quantile

Income & Transfers

MethodEndpointDescription
getUMIncomeHistory(params?)GET papi/v1/um/incomeUM income history
getCMIncomeHistory(params?)GET papi/v1/cm/incomeCM income history
autoCollectFunds()POST papi/v1/auto-collectionAuto-collect funds to PM account
transferAssetFuturesMargin(params)POST papi/v1/asset-collectionTransfer asset from futures to PM
transferBNB(params)POST papi/v1/bnb-transferTransfer BNB between UM and PM
repayFuturesNegativeBalance()POST papi/v1/repay-futures-negative-balanceRepay negative balance in futures
getAutoRepayFuturesStatus()GET papi/v1/repay-futures-switchQuery auto-repay futures status
updateAutoRepayFuturesStatus(params)POST papi/v1/repay-futures-switchToggle auto-repay futures

Code Examples

import { PortfolioClient } from 'binance';

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

async function getPortfolioOverview() {
  // Full account info — includes equity, margin ratio, unrealised P&L
  const account = await client.getAccountInfo();
  console.log('Unified margin:', account.uniMMR);
  console.log('Account equity:', account.accountEquity);

  // Balance across all assets in the PM account
  const balance = await client.getBalance();
  console.log('Portfolio balance:', balance);

  // UM positions (USD-M Futures sub-account)
  const umPositions = await client.getUMPosition();
  const openUM = umPositions.filter((p) => Number(p.positionAmt) !== 0);
  console.log(`${openUM.length} open UM positions`);

  // CM positions (COIN-M Futures sub-account)
  const cmPositions = await client.getCMPosition();
  const openCM = cmPositions.filter((p) => Number(p.positionAmt) !== 0);
  console.log(`${openCM.length} open CM positions`);
}

getPortfolioOverview().catch(console.error);

Portfolio Margin Account Structure

UM Sub-Account

Houses USD-M Futures positions. Orders placed with submitNewUMOrder() and leverage managed with updateUMLeverage().

CM Sub-Account

Houses COIN-M Futures positions. Orders placed with submitNewCMOrder() settled in the underlying cryptocurrency.

Margin Sub-Account

Cross-margin Spot trading. Orders placed with submitNewMarginOrder(). Borrow/repay via submitMarginLoan() / submitMarginRepay().
The unified margin calculation means a long Spot BTC position in the Margin sub-account can reduce the margin required for a short BTC USD-M Futures position in the UM sub-account — and vice versa. Use getAccountInfo() to inspect your current uniMMR (unified maintenance margin ratio).

Commission & Fee Burn

MethodDescription
getUMCommissionRate(params)Query maker/taker commission rates for a UM symbol
getCMCommissionRate(params)Query maker/taker commission rates for a CM symbol
toggleUMFeeBurn(params)Enable or disable BNB fee discount for UM trading
getUMFeeBurnStatus()Check whether the BNB fee discount is active

Further Reading

Build docs developers (and LLMs) love