account_balance
Retrieve asset balances, available amounts, and remaining funds from your OKX cryptocurrency trading account to monitor portfolio holdings and liquidity.
Instructions
Retrieve a list of assets (with non-zero balance), remaining balance, and available amount in the OKX trading account
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ccy | No | Single currency or multiple currencies (no more than 20) separated with comma, e.g. BTC or BTC,ETH.Optional, all by default if not passed |
Implementation Reference
- mcp_okx/account.py:92-182 (handler)The core handler function for the 'account_balance' tool. It fetches the account balance from the OKX API using ACCOUNT.get_account_balance(), handles error codes, attaches a detailed response schema, and returns the response.def account_balance( ccy: str = Field("", description="Single currency or multiple currencies (no more than 20) separated with comma, e.g. BTC or BTC,ETH." "Optional, all by default if not passed"), ): resp = ACCOUNT.get_account_balance(ccy) or {} if int(resp.get("code", 0)): return resp resp["_response_schema"] = """ totalEq: The total amount of equity in USD isoEq: Isolated margin equity in USD. Applicable to Futures mode/Multi-currency margin/Portfolio margin adjEq: Adjusted / Effective equity in USD. The net fiat value of the assets in the account that can provide margins for spot, expiry futures, perpetual futures and options under the cross-margin mode. In multi-ccy or PM mode, the asset and margin requirement will all be converted to USD value to process the order check or liquidation. Due to the volatility of each currency market, our platform calculates the actual USD value of each currency based on discount rates to balance market risks. Applicable to Spot mode/Multi-currency margin and Portfolio margin availEq: Account level available equity, excluding currencies that are restricted due to the collateralized borrowing limit. Applicable to Multi-currency margin/Portfolio margin ordFroz: Cross margin frozen for pending orders in USD. Only applicable to Spot mode/Multi-currency margin/Portfolio margin imr: Initial margin requirement in USD. The sum of initial margins of all open positions and pending orders under cross-margin mode in USD. Applicable to Spot mode/Multi-currency margin/Portfolio margin mmr: Maintenance margin requirement in USD. The sum of maintenance margins of all open positions and pending orders under cross-margin mode in USD. Applicable to Spot mode/Multi-currency margin/Portfolio margin borrowFroz: Potential borrowing IMR of the account in USD. Only applicable to Spot mode/Multi-currency margin/Portfolio margin. It is "" for other margin modes. mgnRatio: Maintenance margin ratio in USD. Applicable to Spot mode/Multi-currency margin/Portfolio margin notionalUsd: Notional value of positions in USD. Applicable to Spot mode/Multi-currency margin/Portfolio margin notionalUsdForBorrow: Notional value for Borrow in USD. Applicable to Spot mode/Multi-currency margin/Portfolio margin notionalUsdForSwap: Notional value of positions for Perpetual Futures in USD. Applicable to Multi-currency margin/Portfolio margin notionalUsdForFutures: Notional value of positions for Expiry Futures in USD. Applicable to Multi-currency margin/Portfolio margin notionalUsdForOption: Notional value of positions for Option in USD. Applicable to Spot mode/Multi-currency margin/Portfolio margin upl: Cross-margin info of unrealized profit and loss at the account level in USD. Applicable to Multi-currency margin/Portfolio margin details: Detailed asset information in all currencies details.ccy: Currency details.eq: Equity of currency details.cashBal: Cash balance details.disEq: Discount equity of currency in USD. Applicable to Spot mode(enabled spot borrow)/Multi-currency margin/Portfolio margin details.fixedBal: Frozen balance for Dip Sniper and Peak Sniper details.availBal: Available balance of currency details.frozenBal: Frozen balance of currency details.ordFrozen: Margin frozen for open orders. Applicable to Spot mode/Futures mode/Multi-currency margin details.liab: Liabilities of currency. It is a positive value, e.g. 21625.64; Applicable to Spot mode/Multi-currency margin/Portfolio margin details.uplLiab: Liabilities due to Unrealized loss of currency. Applicable to Multi-currency margin/Portfolio margin details.crossLiab: Cross liabilities of currency. Applicable to Spot mode/Multi-currency margin/Portfolio margin details.rewardBal: Trial fund balance details.isoLiab: Isolated liabilities of currency. Applicable to Multi-currency margin/Portfolio margin details.interest: Accrued interest of currency. It is a positive value, e.g. 9.01; Applicable to Spot mode/Multi-currency margin/Portfolio margin details.twap: Risk indicator of forced repayment. Divided into multiple levels from 0 to 5, the larger the number, the more likely the forced repayment will be triggered. Applicable to Spot mode/Multi-currency margin/Portfolio margin details.frpType: Forced repayment (FRP) type. 0: no FRP; 1: user based FRP; 2: platform based FRP; Return 1/2 when twap is >= 1, applicable to Spot mode/Multi-currency margin/Portfolio margin details.maxLoan: Max loan of currency. Applicable to cross of Spot mode/Multi-currency margin/Portfolio margin details.eqUsd: Equity in USD of currency details.borrowFroz: Potential borrowing IMR of currency in USD. Applicable to Multi-currency margin/Portfolio margin. It is "" for other margin modes. details.notionalLever: Leverage of currency. Applicable to Futures mode details.stgyEq: Strategy equity details.isoUpl: Isolated unrealized profit and loss of currency. Applicable to Futures mode/Multi-currency margin/Portfolio margin details.spotInUseAmt: Spot in use amount. Applicable to Portfolio margin details.clSpotInUseAmt: User-defined spot risk offset amount. Applicable to Portfolio margin details.maxSpotInUse: Max possible spot risk offset amount. Applicable to Portfolio margin details.spotIsoBal: Spot isolated balance. Applicable to copy trading. Applicable to Spot mode/Futures mode. details.smtSyncEq: Smart sync equity. The default is "0", only applicable to copy trader details.spotCopyTradingEq: Spot smart sync equity. The default is "0", only applicable to copy trader. details.spotBal: Spot balance. The unit is currency, e.g. BTC details.openAvgPx: Spot average cost price. The unit is USD details.accAvgPx: Spot accumulated cost price. The unit is USD details.spotUpl: Spot unrealized profit and loss. The unit is USD details.spotUplRatio: Spot unrealized profit and loss ratio details.totalPnl: Spot accumulated profit and loss. The unit is USD details.totalPnlRatio: Spot accumulated profit and loss ratio details.colRes: Platform level collateral restriction status. 0: The restriction is not enabled. 1: The restriction is not enabled. But the crypto is close to the platform's collateral limit. 2: The restriction is enabled. This crypto can't be used as margin for your new orders. This may result in failed orders. But it will still be included in the account's adjusted equity and doesn't impact margin ratio. details.colBorrAutoConversion: Risk indicator of auto conversion. Divided into multiple levels from 1-5, the larger the number, the more likely the repayment will be triggered. The default will be 0, indicating there is no risk currently. 5 means this user is undergoing auto conversion now, 4 means this user will undergo auto conversion soon whereas 1/2/3 indicates there is a risk for auto conversion. Applicable to Spot mode/Futures mode/Multi-currency margin/Portfolio margin. When the total liability for each crypto set as collateral exceeds a certain percentage of the platform's total limit, the auto-conversion mechanism may be triggered. This may result in the automatic sale of excess collateral crypto if you've set this crypto as collateral and have large borrowings. To lower this risk, consider reducing your use of the crypto as collateral or reducing your liabilities. details.collateralEnabled: true: Collateral enabled; false: Collateral disabled. Applicable to Multi-currency margin details.autoLendStatus: Auto lend status unsupported: auto lend is not supported by this currency off: auto lend is supported but turned off pending: auto lend is turned on but pending matching active: auto lend is turned on and matched details.autoLendMtAmt: Auto lend currency matched amount. Return "0" when autoLendStatus is unsupported/off/pending. Return matched amount when autoLendStatus is active """ return resp
- mcp_okx/__init__.py:25-25 (registration)Registers all account-related tools, including 'account_balance', by calling account.add_tools(mcp) on the FastMCP instance.account.add_tools(mcp)
- mcp_okx/account.py:93-182 (schema)Input schema defined via Pydantic Field for the 'ccy' parameter. Output schema provided as a documentation string attached to the response.ccy: str = Field("", description="Single currency or multiple currencies (no more than 20) separated with comma, e.g. BTC or BTC,ETH." "Optional, all by default if not passed"), ): resp = ACCOUNT.get_account_balance(ccy) or {} if int(resp.get("code", 0)): return resp resp["_response_schema"] = """ totalEq: The total amount of equity in USD isoEq: Isolated margin equity in USD. Applicable to Futures mode/Multi-currency margin/Portfolio margin adjEq: Adjusted / Effective equity in USD. The net fiat value of the assets in the account that can provide margins for spot, expiry futures, perpetual futures and options under the cross-margin mode. In multi-ccy or PM mode, the asset and margin requirement will all be converted to USD value to process the order check or liquidation. Due to the volatility of each currency market, our platform calculates the actual USD value of each currency based on discount rates to balance market risks. Applicable to Spot mode/Multi-currency margin and Portfolio margin availEq: Account level available equity, excluding currencies that are restricted due to the collateralized borrowing limit. Applicable to Multi-currency margin/Portfolio margin ordFroz: Cross margin frozen for pending orders in USD. Only applicable to Spot mode/Multi-currency margin/Portfolio margin imr: Initial margin requirement in USD. The sum of initial margins of all open positions and pending orders under cross-margin mode in USD. Applicable to Spot mode/Multi-currency margin/Portfolio margin mmr: Maintenance margin requirement in USD. The sum of maintenance margins of all open positions and pending orders under cross-margin mode in USD. Applicable to Spot mode/Multi-currency margin/Portfolio margin borrowFroz: Potential borrowing IMR of the account in USD. Only applicable to Spot mode/Multi-currency margin/Portfolio margin. It is "" for other margin modes. mgnRatio: Maintenance margin ratio in USD. Applicable to Spot mode/Multi-currency margin/Portfolio margin notionalUsd: Notional value of positions in USD. Applicable to Spot mode/Multi-currency margin/Portfolio margin notionalUsdForBorrow: Notional value for Borrow in USD. Applicable to Spot mode/Multi-currency margin/Portfolio margin notionalUsdForSwap: Notional value of positions for Perpetual Futures in USD. Applicable to Multi-currency margin/Portfolio margin notionalUsdForFutures: Notional value of positions for Expiry Futures in USD. Applicable to Multi-currency margin/Portfolio margin notionalUsdForOption: Notional value of positions for Option in USD. Applicable to Spot mode/Multi-currency margin/Portfolio margin upl: Cross-margin info of unrealized profit and loss at the account level in USD. Applicable to Multi-currency margin/Portfolio margin details: Detailed asset information in all currencies details.ccy: Currency details.eq: Equity of currency details.cashBal: Cash balance details.disEq: Discount equity of currency in USD. Applicable to Spot mode(enabled spot borrow)/Multi-currency margin/Portfolio margin details.fixedBal: Frozen balance for Dip Sniper and Peak Sniper details.availBal: Available balance of currency details.frozenBal: Frozen balance of currency details.ordFrozen: Margin frozen for open orders. Applicable to Spot mode/Futures mode/Multi-currency margin details.liab: Liabilities of currency. It is a positive value, e.g. 21625.64; Applicable to Spot mode/Multi-currency margin/Portfolio margin details.uplLiab: Liabilities due to Unrealized loss of currency. Applicable to Multi-currency margin/Portfolio margin details.crossLiab: Cross liabilities of currency. Applicable to Spot mode/Multi-currency margin/Portfolio margin details.rewardBal: Trial fund balance details.isoLiab: Isolated liabilities of currency. Applicable to Multi-currency margin/Portfolio margin details.interest: Accrued interest of currency. It is a positive value, e.g. 9.01; Applicable to Spot mode/Multi-currency margin/Portfolio margin details.twap: Risk indicator of forced repayment. Divided into multiple levels from 0 to 5, the larger the number, the more likely the forced repayment will be triggered. Applicable to Spot mode/Multi-currency margin/Portfolio margin details.frpType: Forced repayment (FRP) type. 0: no FRP; 1: user based FRP; 2: platform based FRP; Return 1/2 when twap is >= 1, applicable to Spot mode/Multi-currency margin/Portfolio margin details.maxLoan: Max loan of currency. Applicable to cross of Spot mode/Multi-currency margin/Portfolio margin details.eqUsd: Equity in USD of currency details.borrowFroz: Potential borrowing IMR of currency in USD. Applicable to Multi-currency margin/Portfolio margin. It is "" for other margin modes. details.notionalLever: Leverage of currency. Applicable to Futures mode details.stgyEq: Strategy equity details.isoUpl: Isolated unrealized profit and loss of currency. Applicable to Futures mode/Multi-currency margin/Portfolio margin details.spotInUseAmt: Spot in use amount. Applicable to Portfolio margin details.clSpotInUseAmt: User-defined spot risk offset amount. Applicable to Portfolio margin details.maxSpotInUse: Max possible spot risk offset amount. Applicable to Portfolio margin details.spotIsoBal: Spot isolated balance. Applicable to copy trading. Applicable to Spot mode/Futures mode. details.smtSyncEq: Smart sync equity. The default is "0", only applicable to copy trader details.spotCopyTradingEq: Spot smart sync equity. The default is "0", only applicable to copy trader. details.spotBal: Spot balance. The unit is currency, e.g. BTC details.openAvgPx: Spot average cost price. The unit is USD details.accAvgPx: Spot accumulated cost price. The unit is USD details.spotUpl: Spot unrealized profit and loss. The unit is USD details.spotUplRatio: Spot unrealized profit and loss ratio details.totalPnl: Spot accumulated profit and loss. The unit is USD details.totalPnlRatio: Spot accumulated profit and loss ratio details.colRes: Platform level collateral restriction status. 0: The restriction is not enabled. 1: The restriction is not enabled. But the crypto is close to the platform's collateral limit. 2: The restriction is enabled. This crypto can't be used as margin for your new orders. This may result in failed orders. But it will still be included in the account's adjusted equity and doesn't impact margin ratio. details.colBorrAutoConversion: Risk indicator of auto conversion. Divided into multiple levels from 1-5, the larger the number, the more likely the repayment will be triggered. The default will be 0, indicating there is no risk currently. 5 means this user is undergoing auto conversion now, 4 means this user will undergo auto conversion soon whereas 1/2/3 indicates there is a risk for auto conversion. Applicable to Spot mode/Futures mode/Multi-currency margin/Portfolio margin. When the total liability for each crypto set as collateral exceeds a certain percentage of the platform's total limit, the auto-conversion mechanism may be triggered. This may result in the automatic sale of excess collateral crypto if you've set this crypto as collateral and have large borrowings. To lower this risk, consider reducing your use of the crypto as collateral or reducing your liabilities. details.collateralEnabled: true: Collateral enabled; false: Collateral disabled. Applicable to Multi-currency margin details.autoLendStatus: Auto lend status unsupported: auto lend is not supported by this currency off: auto lend is supported but turned off pending: auto lend is turned on but pending matching active: auto lend is turned on and matched details.autoLendMtAmt: Auto lend currency matched amount. Return "0" when autoLendStatus is unsupported/off/pending. Return matched amount when autoLendStatus is active """ return resp