> ## 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: spot type: object required: false properties: - name: in_flight_orders type: array description: >- One row per open spot order for this subaccount. `reserved_asset` is the side that the user must have paid to enter the order (USDC for bids, base for asks). USD-equivalent computed at current mark. required: true properties: - name: is_bid type: boolean required: true - name: market_addr type: string required: true - name: order_id type: string description: >- Numeric on-chain order id for regular orders. Bulk-order ladders are folded into ONE aggregate entry per (market, side) whose `order_id` is the literal string `"bulk"` ([`BULK_AGGREGATE_ORDER_ID`]); clients must not parse it as a number or use it for cancellation. required: true - name: reserved_amount type: number description: Reserved amount in human units. required: true - name: reserved_asset type: string description: >- FA metadata address for the reserved asset (quote for bids, base for asks). required: true - name: reserved_usd_value type: number description: USDC-equivalent value at current mark. required: true - name: metrics type: object required: false properties: - name: cumulative_maker_fees_usd type: number description: >- Cumulative fees paid on fills where this account was the maker, USD. required: true - name: cumulative_realized_pnl_usd type: number description: >- Cumulative realized PnL from spot sells, USD. Weighted-average basis. required: true - name: cumulative_taker_fees_usd type: number description: >- Cumulative fees paid on fills where this account was the taker, USD. required: true - name: cumulative_volume_usd type: number description: >- Cumulative spot volume traded (both taker and maker sides), USD. required: true - name: positions type: array description: >- Assets held in this subaccount's PFS (base assets + USDC). Each row is one asset held; balance × mark_price = usd_value. Mark resolution per market follows the shared spot rule (all_spot_mids / asset_contexts / spot_value_snapshots): mid of a TWO-SIDED book, else last trade price, else 0. USDC is marked 1.0 by definition. required: true properties: - name: amount type: number description: >- Balance normalized to human units (raw_balance / 10^decimals). required: true - name: asset_addr type: string description: FA metadata address for the held asset. required: true - name: asset_symbol type: string description: >- Human-readable symbol from the spot market (e.g., "APT"). Best-effort from `spot_markets` metadata; empty when the asset isn't currently a base of any registered market. required: true - name: entry_notional_usd type: number description: >- Weighted-average cost basis for the currently-held amount, in USD terms. Analogue of Hyperliquid `spotClearinghouseState.entryNtl`. Computed as `(cumulative_bought_quote_usd / cumulative_bought_amount) * amount`. `0.0` when the asset was acquired without an on-book spot trade (e.g., external FA transfer into the subaccount) — the MV only sees fills. required: true - name: unrealized_pnl_usd type: number description: >- `usd_value - entry_notional_usd`. Negative when mark < avg cost. required: true - name: usd_value type: number description: amount × current mark price. required: true - name: total_usd type: number description: >- USDC-equivalent value of every position + reserved amount in open spot orders. required: true - 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: spot: oneOf: - type: 'null' x-parser-schema-id: - type: object description: Per-subaccount spot inventory + open-order reservations. required: - positions - total_usd - in_flight_orders properties: in_flight_orders: type: array items: type: object required: - market_addr - order_id - is_bid - reserved_asset - reserved_amount - reserved_usd_value properties: is_bid: type: boolean example: true x-parser-schema-id: market_addr: type: string example: 0x26f1dd... x-parser-schema-id: order_id: type: string description: >- Numeric on-chain order id for regular orders. Bulk-order ladders are folded into ONE aggregate entry per (market, side) whose `order_id` is the literal string `"bulk"` ([`BULK_AGGREGATE_ORDER_ID`]); clients must not parse it as a number or use it for cancellation. example: '1234' x-parser-schema-id: reserved_amount: type: number format: double description: Reserved amount in human units. example: 500 x-parser-schema-id: reserved_asset: type: string description: >- FA metadata address for the reserved asset (quote for bids, base for asks). x-parser-schema-id: reserved_usd_value: type: number format: double description: USDC-equivalent value at current mark. example: 500 x-parser-schema-id: x-parser-schema-id: SpotInFlightOrderDto description: >- One row per open spot order for this subaccount. `reserved_asset` is the side that the user must have paid to enter the order (USDC for bids, base for asks). USD-equivalent computed at current mark. x-parser-schema-id: metrics: oneOf: - type: 'null' x-parser-schema-id: - type: object description: >- Aggregate spot trading metrics for a subaccount, summed across all assets. Fees are split per side using the on-chain settlement's re-keying (for a taker bid, `base_fee` is the taker's fee and `quote_fee` the maker's; reversed on asks — see `spot_fees_manager::deduct_and_collect`). Realized PnL uses lifetime-weighted-average cost basis and is exact when the user only accumulates + fully liquidates each position; small drift otherwise (see `spot_account_asset_stats_latest.sql`). required: - cumulative_volume_usd - cumulative_taker_fees_usd - cumulative_maker_fees_usd - cumulative_realized_pnl_usd properties: cumulative_maker_fees_usd: type: number format: double description: >- Cumulative fees paid on fills where this account was the maker, USD. example: 4.1 x-parser-schema-id: cumulative_realized_pnl_usd: type: number format: double description: >- Cumulative realized PnL from spot sells, USD. Weighted-average basis. example: 142.55 x-parser-schema-id: cumulative_taker_fees_usd: type: number format: double description: >- Cumulative fees paid on fills where this account was the taker, USD. example: 12.29 x-parser-schema-id: cumulative_volume_usd: type: number format: double description: >- Cumulative spot volume traded (both taker and maker sides), USD. example: 24580.1 x-parser-schema-id: x-parser-schema-id: SpotMetricsDto x-parser-schema-id: positions: type: array items: type: object required: - asset_addr - asset_symbol - amount - usd_value - entry_notional_usd - unrealized_pnl_usd properties: amount: type: number format: double description: >- Balance normalized to human units (raw_balance / 10^decimals). example: 10 x-parser-schema-id: asset_addr: type: string description: FA metadata address for the held asset. example: >- 0x000000000000000000000000000000000000000000000000000000000000000a x-parser-schema-id: asset_symbol: type: string description: >- Human-readable symbol from the spot market (e.g., "APT"). Best-effort from `spot_markets` metadata; empty when the asset isn't currently a base of any registered market. example: APT x-parser-schema-id: entry_notional_usd: type: number format: double description: >- Weighted-average cost basis for the currently-held amount, in USD terms. Analogue of Hyperliquid `spotClearinghouseState.entryNtl`. Computed as `(cumulative_bought_quote_usd / cumulative_bought_amount) * amount`. `0.0` when the asset was acquired without an on-book spot trade (e.g., external FA transfer into the subaccount) — the MV only sees fills. example: 82.4 x-parser-schema-id: unrealized_pnl_usd: type: number format: double description: >- `usd_value - entry_notional_usd`. Negative when mark < avg cost. example: 4.75 x-parser-schema-id: usd_value: type: number format: double description: amount × current mark price. example: 87.15 x-parser-schema-id: x-parser-schema-id: SpotPositionDto description: >- Assets held in this subaccount's PFS (base assets + USDC). Each row is one asset held; balance × mark_price = usd_value. Mark resolution per market follows the shared spot rule (all_spot_mids / asset_contexts / spot_value_snapshots): mid of a TWO-SIDED book, else last trade price, else 0. USDC is marked 1.0 by definition. x-parser-schema-id: total_usd: type: number format: double description: >- USDC-equivalent value of every position + reserved amount in open spot orders. example: 872.3 x-parser-schema-id: x-parser-schema-id: SpotOverviewDto 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, "spot": null } } 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: [] ````