---
title: "Get account overview"
method: GET
path: "/api/v1/account_overviews"
tags: ["Account"]
---

# Get account overview

`GET /api/v1/account_overviews`

Retrieve comprehensive account information including equity, realized/unrealized PnL, margin utilization,
and optional performance metrics. Use `include_performance=true` to get historical return metrics.

## Query parameters

- `account` string, required
- `volume_window` '7d' | '14d' | '30d' | '90d' — Time window for volume queries
- `include_performance` boolean
- `performance_lookback_days` integer

## Response `200`

Account overview retrieved successfully

- AccountOverviewDto
  - `all_time_return` number, double, nullable
  - `average_cash_position` number, double, nullable
  - `average_leverage` number, double, nullable
  - `cross_account_leverage_ratio` number, double, required
  - `cross_account_position` number, double, nullable
  - `cross_available_to_trade` number, double, required — 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.
  - `cross_margin_ratio` number, double, required
  - `fee_income` number, double, nullable — 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).
  - `free_vault_equity` number, double, nullable — 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).
  - `liquidation_fees_paid` number, double, nullable — 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.
  - `liquidation_losses` number, double, nullable — 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).
  - `maintenance_margin` number, double, required
  - `margin_deficit` number, double, required — 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)
  - `max_drawdown` number, double, nullable
  - `net_deposits` number, double, nullable — Net deposits (total deposits - total withdrawals) in USDC. Used to verify all_time_return: all_time_return = ((equity - net_deposits) / net_deposits) * 100
  - `perp_equity_balance` number, double, required — 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.
  - `perp_equity_haircutted` number, double, required — 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.
  - `pnl_90d` number, double, nullable
  - `realized_pnl` number, double, nullable
  - `secondary_collateral` SecondaryCollateralDto[], nullable — Secondary (non-USDC) collateral held in cross margin. NULL when no secondary collateral exists or oracle data is unavailable.
    - `amount` number, double, required — Raw balance normalized to human units (balance / 10^decimals).
    - `asset_type` string, required — On-chain asset type address (e.g., DLP fungible asset address).
    - `haircut_bps` integer, required — Haircut applied to the oracle price for margin purposes (in basis points).
    - `nav_per_unit` number, double, required — NAV per unit in USDC terms (oracle price / 10^collateral_decimals).
    - `value_in_usdc` number, double, required — USDC-equivalent value after applying the haircut. Formula: amount * (nav_per_unit * (10000 - haircut_bps) / 10000).
    - `withdrawable_amount` number, double, required — Maximum amount of this secondary asset that can be withdrawn without violating margin requirements.
  - `sharpe_ratio` number, double, nullable
  - `total_margin` number, double, required
  - `unrealized_funding_cost` number, double, required
  - `unrealized_pnl` number, double, required
  - `usdc_cross_withdrawable_balance` number, double, required
  - `usdc_isolated_withdrawable_balance` number, double, required
  - `vault_equity` number, double, nullable — 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).
  - `volume` number, double, nullable
  - `weekly_win_rate_12w` number, double, nullable

## Other responses

- `500` — Database error

---

[API](https://skmtc.net/decibel/apis/decibel-trading-api.md) · [All operations](https://skmtc.net/decibel/apis/decibel-trading-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/decibel/decibel-trading-api/versions/37a02083ff59/schema)