> ## 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. # Get account overview > Retrieve comprehensive perp account information including equity, realized/unrealized PnL, margin utilization, and optional performance metrics. Use `include_performance=true` to get historical return metrics. ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/account_overviews openapi: 3.1.0 info: title: Decibel Trading API description: >- RESTful API for Decibel. Provides read-only endpoints for market data, trading operations, positions, and analytics. contact: name: Decibel Team url: https://decibel.trade/ license: name: '' version: 1.0.0 servers: - url: https://api.mainnet.aptoslabs.com/decibel description: Mainnet - url: https://api.testnet.aptoslabs.com/decibel description: Testnet security: - bearerAuth: [] tags: - name: Market Data description: Market information and real-time data endpoints - name: User description: User information and account management - name: Account description: Account-specific endpoints and data - name: Trades description: Trading operations and history - name: Positions description: User position management - name: Orders description: Order management and history - name: TWAP description: Time-weighted average price orders - name: Bulk Orders description: Bulk order management - name: Vaults description: Vault operations and management - name: Analytics description: Analytics and performance metrics - name: Points description: Points-related account metrics - name: Trading Points description: Trading points endpoints - name: Trading Hz description: Trading Hz endpoints - name: Tier description: Tier information endpoints - name: Streaks description: User streak tracking endpoints - name: Predeposit Rewards description: Season 0 predeposit USDC rewards - name: Referrals description: Referral code management and tracking - name: Affiliates description: Affiliate code and earnings endpoints - name: Campaigns description: On-chain reward campaign endpoints paths: /api/v1/account_overviews: get: tags: - Account summary: Get account overview description: >- Retrieve comprehensive perp account information including equity, realized/unrealized PnL, margin utilization, and optional performance metrics. Use `include_performance=true` to get historical return metrics. operationId: handle_account_overview parameters: - name: account in: query description: User account address (`user` query alias is also accepted) required: true schema: type: string example: 0x123... - name: volume_window in: query description: >- Volume time window (e.g., "7d", "14d", "30d", "90d"). Omit to exclude volume data. required: false schema: type: string description: Time window for volume queries enum: - 7d - 14d - 30d - 90d example: 30d - name: include_performance in: query description: Include performance metrics required: false schema: type: boolean default: false example: false - name: performance_lookback_days in: query description: Performance lookback window in days. required: false schema: type: integer format: int32 default: 90 minimum: 0 example: 90 responses: '200': description: Account overview retrieved successfully content: application/json: schema: $ref: '#/components/schemas/AccountOverviewDto' '500': description: Database error components: schemas: AccountOverviewDto: 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: - number - 'null' format: double average_cash_position: type: - number - 'null' format: double average_leverage: type: - number - 'null' format: double cross_account_leverage_ratio: type: number format: double example: 40.99 cross_account_position: type: - number - 'null' format: double 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 cross_margin_ratio: type: number format: double example: 0.01 fee_income: type: - number - 'null' 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 free_vault_equity: type: - number - 'null' 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 liquidation_fees_paid: type: - number - 'null' 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 liquidation_losses: type: - number - 'null' 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 maintenance_margin: type: number format: double example: 115.29 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 max_drawdown: type: - number - 'null' format: double net_deposits: type: - number - 'null' 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 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 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 pnl_90d: type: - number - 'null' format: double realized_pnl: type: - number - 'null' format: double example: 1250.5 secondary_collateral: type: - array - 'null' items: $ref: '#/components/schemas/SecondaryCollateralDto' description: >- Secondary (non-USDC) collateral held in cross margin. NULL when no secondary collateral exists or oracle data is unavailable. sharpe_ratio: type: - number - 'null' format: double total_margin: type: number format: double example: 9998.72 unrealized_funding_cost: type: number format: double example: -87.84 unrealized_pnl: type: number format: double example: 154 usdc_cross_withdrawable_balance: type: number format: double example: 9843.79 usdc_isolated_withdrawable_balance: type: number format: double example: 0 vault_equity: type: - number - 'null' 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 volume: type: - number - 'null' format: double weekly_win_rate_12w: type: - number - 'null' format: double SecondaryCollateralDto: 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 asset_type: type: string description: On-chain asset type address (e.g., DLP fungible asset address). example: 0x1234... haircut_bps: type: integer format: int64 description: >- Haircut applied to the oracle price for margin purposes (in basis points). example: 500 minimum: 0 nav_per_unit: type: number format: double description: NAV per unit in USDC terms (oracle price / 10^collateral_decimals). example: 1.05 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 withdrawable_amount: type: number format: double description: |- Maximum amount of this secondary asset that can be withdrawn without violating margin requirements. example: 100 securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer token from Geomi. See [Authentication](/api-reference/rest/authentication) for setup instructions. ````