> ## Documentation Index > Fetch the complete documentation index at: https://docs.decibel.trade/llms.txt > Use this file to discover all available pages before exploring further. # Account overview > User's perp account overview including equity, margin, and PnL ## AsyncAPI ````yaml api-reference/asyncapi.json accountOverview id: accountOverview title: Account overview description: User's perp account overview including equity, margin, and PnL servers: - id: testnet protocol: wss host: api.testnet.aptoslabs.com/decibel/ws bindings: [] variables: [] address: account_overview:{userAddr} parameters: - id: userAddr jsonSchema: type: string description: User wallet address (Aptos address format, e.g. 0x123...) description: User wallet address (Aptos address format, e.g. 0x123...) type: string required: true deprecated: false bindings: [] operations: - &ref_17 id: receiveaccountOverview title: Receiveaccount overview description: >- Receive updates for user's perp account overview including equity, margin, and pnl type: receive messages: - &ref_18 id: AccountOverviewMessage payload: - name: AccountOverviewMessage description: User's perp account overview including equity, margin, and PnL type: object properties: - name: account_overview type: object required: true properties: - name: all_time_return type: &ref_0 - number - 'null' required: false - name: average_cash_position type: &ref_1 - number - 'null' required: false - name: average_leverage type: &ref_2 - number - 'null' required: false - name: cross_account_leverage_ratio type: number required: true - name: cross_account_position type: &ref_3 - number - 'null' required: false - name: cross_available_to_trade type: number description: >- Total cross-margin buying power across all collateral assets (USDC + secondary). Formula: max(0, raw_free_collateral − order_margin) = max(0, cross_margin + secondary_collateral_value + min(0, uPnL − funding) − initial_margin − order_margin) Use this for "Available to Trade" display. Unlike usdc_cross_withdrawable_balance (which is capped at the USDC balance), this reflects the full buying power including DLP and other secondary collateral. required: true - name: cross_margin_ratio type: number required: true - name: fee_income type: &ref_4 - number - 'null' description: >- Non-trade fee income (vault/BLP accounts only). Protocol fee distributions recorded as CBH Fee entries but not captured in trade fee_amount. Regular users: always null (their CBH fee entries exactly match trade fee amounts). required: false - name: free_vault_equity type: &ref_5 - number - 'null' description: >- USDC value of vault shares NOT currently pledged as DLP collateral on this subaccount's perp account ("free" shares × NAV). This is the additive complement to `perp_equity_balance`: summing the two gives the subaccount's total wealth with no double-count of pledged DLP (which `perp_equity_balance` already covers via `secondary_collateral`). Equals 0.0 for users who pledge all their vault shares as collateral. The full pre-pledge total is still visible in `vault_equity` for display. NULL when not yet available (e.g., WebSocket updates before real-time vault tracking). required: false - name: liquidation_fees_paid type: &ref_6 - number - 'null' description: >- Total fees paid during margin call liquidations (always positive). Fee rate is configurable per market (default 0.5%, max 2% of notional). This is already included in realized_pnl but shown separately for transparency. Null for accounts that have never been margin called. required: false - name: liquidation_losses type: &ref_7 - number - 'null' description: >- Net collateral balance changes from liquidations (vault/BLP accounts only). Regular users: always null - their liquidation loss is in realized_pnl via BackStopLiquidation trades. Vault accounts: positive = margin received from liquidated users (profit), negative = bad debt covered when users were underwater (loss). required: false - name: maintenance_margin type: number required: true - name: margin_deficit type: number description: >- Cross-margin deficit: 0 when healthy, negative when the account has a margin hole. When negative, new deposits will partially fill this deficit before becoming available to trade. For example, deficit = -12 means a $185 deposit yields only $173 available (the first $12 fills the hole). Formula: min(0, margin_balance - margin_for_free_collateral + min(0, unrealized_pnl - funding) - order_margin) required: true - name: max_drawdown type: &ref_8 - number - 'null' required: false - name: net_deposits type: &ref_9 - number - 'null' description: >- Net deposits (total deposits - total withdrawals) in USDC. Used to verify all_time_return: all_time_return = ((equity - net_deposits) / net_deposits) * 100 required: false - name: perp_equity_balance type: number description: >- Perp equity at FULL NAV — DLP / secondary collateral counted at oracle/computed price WITHOUT the haircut discount. Intended for **display** ("your total account value"). Do NOT use this as the equity input to client-side liquidation price estimation; use `perp_equity_haircutted` instead so the estimate matches the on-chain liquidation threshold. required: true - name: perp_equity_haircutted type: number description: >- Perp equity with the haircut applied to secondary collateral. This is the value the on-chain liquidation engine uses to decide whether to liquidate. The order form's pre-trade liquidation-price estimate must consume this (not `perp_equity_balance`) to match the positions tab. Difference from `perp_equity_balance`: `perp_equity_balance - perp_equity_haircutted` equals the secondary collateral haircut discount (i.e. `sum(amount × NAV × haircut_bps/10000)`). For accounts with no secondary collateral the two fields are equal. required: true - name: pnl_90d type: &ref_10 - number - 'null' required: false - name: realized_pnl type: &ref_11 - number - 'null' required: false - name: secondary_collateral type: &ref_12 - array - 'null' description: >- Secondary (non-USDC) collateral held in cross margin. NULL when no secondary collateral exists or oracle data is unavailable. required: false - name: sharpe_ratio type: &ref_13 - number - 'null' required: false - name: total_margin type: number required: true - name: unrealized_funding_cost type: number required: true - name: unrealized_pnl type: number required: true - name: usdc_cross_withdrawable_balance type: number required: true - name: usdc_isolated_withdrawable_balance type: number required: true - name: vault_equity type: &ref_14 - number - 'null' description: >- Total USDC value of vault shares attributed to this subaccount (free shares in the subaccount's primary store **plus** shares pledged as DLP collateral on its perp account). Intended for direct display ("your total vault position is worth $X") — answers the question "what do I own in vaults?". **Do not add to `perp_equity_balance` to compute total wealth.** The pledged portion is already counted in `perp_equity_balance` via `secondary_collateral`, so summing the two double-counts pledged DLP. Use `free_vault_equity` (below) as the additive complement instead: `perp_equity_balance + free_vault_equity` gives total wealth with no overlap. NULL when not yet available (e.g., WebSocket updates before real-time vault tracking). required: false - name: volume type: &ref_15 - number - 'null' required: false - name: weekly_win_rate_12w type: &ref_16 - number - 'null' required: false - name: topic type: string required: true headers: [] jsonPayloadSchema: type: object required: - topic - account_overview properties: account_overview: type: object required: - perp_equity_balance - perp_equity_haircutted - unrealized_pnl - unrealized_funding_cost - cross_margin_ratio - maintenance_margin - cross_account_leverage_ratio - total_margin - usdc_cross_withdrawable_balance - usdc_isolated_withdrawable_balance - margin_deficit - cross_available_to_trade properties: all_time_return: type: *ref_0 format: double x-parser-schema-id: average_cash_position: type: *ref_1 format: double x-parser-schema-id: average_leverage: type: *ref_2 format: double x-parser-schema-id: cross_account_leverage_ratio: type: number format: double example: 40.99 x-parser-schema-id: cross_account_position: type: *ref_3 format: double x-parser-schema-id: cross_available_to_trade: type: number format: double description: >- Total cross-margin buying power across all collateral assets (USDC + secondary). Formula: max(0, raw_free_collateral − order_margin) = max(0, cross_margin + secondary_collateral_value + min(0, uPnL − funding) − initial_margin − order_margin) Use this for "Available to Trade" display. Unlike usdc_cross_withdrawable_balance (which is capped at the USDC balance), this reflects the full buying power including DLP and other secondary collateral. example: 4791.47 x-parser-schema-id: cross_margin_ratio: type: number format: double example: 0.01 x-parser-schema-id: fee_income: type: *ref_4 format: double description: >- Non-trade fee income (vault/BLP accounts only). Protocol fee distributions recorded as CBH Fee entries but not captured in trade fee_amount. Regular users: always null (their CBH fee entries exactly match trade fee amounts). example: 5386 x-parser-schema-id: free_vault_equity: type: *ref_5 format: double description: >- USDC value of vault shares NOT currently pledged as DLP collateral on this subaccount's perp account ("free" shares × NAV). This is the additive complement to `perp_equity_balance`: summing the two gives the subaccount's total wealth with no double-count of pledged DLP (which `perp_equity_balance` already covers via `secondary_collateral`). Equals 0.0 for users who pledge all their vault shares as collateral. The full pre-pledge total is still visible in `vault_equity` for display. NULL when not yet available (e.g., WebSocket updates before real-time vault tracking). example: 14.65 x-parser-schema-id: liquidation_fees_paid: type: *ref_6 format: double description: >- Total fees paid during margin call liquidations (always positive). Fee rate is configurable per market (default 0.5%, max 2% of notional). This is already included in realized_pnl but shown separately for transparency. Null for accounts that have never been margin called. example: 45.5 x-parser-schema-id: liquidation_losses: type: *ref_7 format: double description: >- Net collateral balance changes from liquidations (vault/BLP accounts only). Regular users: always null - their liquidation loss is in realized_pnl via BackStopLiquidation trades. Vault accounts: positive = margin received from liquidated users (profit), negative = bad debt covered when users were underwater (loss). example: -500 x-parser-schema-id: maintenance_margin: type: number format: double example: 115.29 x-parser-schema-id: margin_deficit: type: number format: double description: >- Cross-margin deficit: 0 when healthy, negative when the account has a margin hole. When negative, new deposits will partially fill this deficit before becoming available to trade. For example, deficit = -12 means a $185 deposit yields only $173 available (the first $12 fills the hole). Formula: min(0, margin_balance - margin_for_free_collateral + min(0, unrealized_pnl - funding) - order_margin) example: -12.06 x-parser-schema-id: max_drawdown: type: *ref_8 format: double x-parser-schema-id: net_deposits: type: *ref_9 format: double description: >- Net deposits (total deposits - total withdrawals) in USDC. Used to verify all_time_return: all_time_return = ((equity - net_deposits) / net_deposits) * 100 example: 30277044.96 x-parser-schema-id: perp_equity_balance: type: number format: double description: >- Perp equity at FULL NAV — DLP / secondary collateral counted at oracle/computed price WITHOUT the haircut discount. Intended for **display** ("your total account value"). Do NOT use this as the equity input to client-side liquidation price estimation; use `perp_equity_haircutted` instead so the estimate matches the on-chain liquidation threshold. example: 10064.88 x-parser-schema-id: perp_equity_haircutted: type: number format: double description: >- Perp equity with the haircut applied to secondary collateral. This is the value the on-chain liquidation engine uses to decide whether to liquidate. The order form's pre-trade liquidation-price estimate must consume this (not `perp_equity_balance`) to match the positions tab. Difference from `perp_equity_balance`: `perp_equity_balance - perp_equity_haircutted` equals the secondary collateral haircut discount (i.e. `sum(amount × NAV × haircut_bps/10000)`). For accounts with no secondary collateral the two fields are equal. example: 10054.92 x-parser-schema-id: pnl_90d: type: *ref_10 format: double x-parser-schema-id: realized_pnl: type: *ref_11 format: double example: 1250.5 x-parser-schema-id: secondary_collateral: type: *ref_12 items: type: object description: Secondary (non-USDC) collateral held in cross margin. required: - asset_type - amount - value_in_usdc - nav_per_unit - haircut_bps - withdrawable_amount properties: amount: type: number format: double description: >- Raw balance normalized to human units (balance / 10^decimals). example: 150 x-parser-schema-id: asset_type: type: string description: >- On-chain asset type address (e.g., DLP fungible asset address). example: 0x1234... x-parser-schema-id: haircut_bps: type: integer format: int64 description: >- Haircut applied to the oracle price for margin purposes (in basis points). example: 500 minimum: 0 x-parser-schema-id: nav_per_unit: type: number format: double description: >- NAV per unit in USDC terms (oracle price / 10^collateral_decimals). example: 1.05 x-parser-schema-id: value_in_usdc: type: number format: double description: >- USDC-equivalent value after applying the haircut. Formula: amount * (nav_per_unit * (10000 - haircut_bps) / 10000). example: 142.5 x-parser-schema-id: withdrawable_amount: type: number format: double description: >- Maximum amount of this secondary asset that can be withdrawn without violating margin requirements. example: 100 x-parser-schema-id: x-parser-schema-id: SecondaryCollateralDto description: >- Secondary (non-USDC) collateral held in cross margin. NULL when no secondary collateral exists or oracle data is unavailable. x-parser-schema-id: sharpe_ratio: type: *ref_13 format: double x-parser-schema-id: total_margin: type: number format: double example: 9998.72 x-parser-schema-id: unrealized_funding_cost: type: number format: double example: -87.84 x-parser-schema-id: unrealized_pnl: type: number format: double example: 154 x-parser-schema-id: usdc_cross_withdrawable_balance: type: number format: double example: 9843.79 x-parser-schema-id: usdc_isolated_withdrawable_balance: type: number format: double example: 0 x-parser-schema-id: vault_equity: type: *ref_14 format: double description: >- Total USDC value of vault shares attributed to this subaccount (free shares in the subaccount's primary store **plus** shares pledged as DLP collateral on its perp account). Intended for direct display ("your total vault position is worth $X") — answers the question "what do I own in vaults?". **Do not add to `perp_equity_balance` to compute total wealth.** The pledged portion is already counted in `perp_equity_balance` via `secondary_collateral`, so summing the two double-counts pledged DLP. Use `free_vault_equity` (below) as the additive complement instead: `perp_equity_balance + free_vault_equity` gives total wealth with no overlap. NULL when not yet available (e.g., WebSocket updates before real-time vault tracking). example: 259.73 x-parser-schema-id: volume: type: *ref_15 format: double x-parser-schema-id: weekly_win_rate_12w: type: *ref_16 format: double x-parser-schema-id: x-parser-schema-id: AccountOverviewDto topic: type: string x-parser-schema-id: x-parser-schema-id: AccountOverviewResponse title: Account overview message description: User's perp account overview including equity, margin, and PnL example: |- { "topic": "account_overview:0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "account_overview": { "perp_equity_balance": 50250.75, "perp_equity_haircutted": 50225.75, "unrealized_pnl": 1250.5, "realized_pnl": 0, "liquidation_fees_paid": 0, "liquidation_losses": 0, "fee_income": null, "unrealized_funding_cost": -125.25, "cross_margin_ratio": 0.15, "maintenance_margin": 2500, "cross_account_leverage_ratio": 500, "volume": 125000, "net_deposits": null, "all_time_return": 0.25, "pnl_90d": 5000, "sharpe_ratio": 1.8, "max_drawdown": -0.08, "weekly_win_rate_12w": 0.65, "average_cash_position": 45000, "average_leverage": 5.5, "cross_account_position": 25000, "total_margin": 10000, "usdc_cross_withdrawable_balance": 7500, "usdc_isolated_withdrawable_balance": 2500, "margin_deficit": 0, "vault_equity": null, "free_vault_equity": null, "secondary_collateral": [ { "asset_type": "0xdlp_asset_address", "amount": 500, "value_in_usdc": 475, "nav_per_unit": 1, "haircut_bps": 500, "withdrawable_amount": 400 } ], "cross_available_to_trade": 7500 } } bindings: [] extensions: - id: x-parser-unique-object-id value: AccountOverviewMessage - id: x-parser-message-name value: AccountOverviewMessage bindings: [] extensions: - id: x-parser-unique-object-id value: accountOverview sendOperations: - *ref_17 receiveOperations: [] sendMessages: - *ref_18 receiveMessages: [] extensions: - id: x-parser-unique-object-id value: accountOverview securitySchemes: [] ````