> ## 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 spot: oneOf: - type: 'null' - $ref: '#/components/schemas/SpotOverviewDto' description: >- Spot-tradable inventory for this subaccount, sourced from PFS holdings. USDC held in the PFS IS included as a PnL-less position priced 1.0: a token sits in exactly one store, so PFS USDC can never overlap the CBS balance that perp equity counts (no double-count possible), and the spot_value_snapshots series counts it too — the live overview and the portfolio chart must agree. `in_flight_orders` covers amounts locked in escrow for open spot orders. NULL for wallet-only owners (no subaccount). 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 SpotOverviewDto: type: object description: Per-subaccount spot inventory + open-order reservations. required: - positions - total_usd - in_flight_orders properties: in_flight_orders: type: array items: $ref: '#/components/schemas/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. metrics: oneOf: - type: 'null' - $ref: '#/components/schemas/SpotMetricsDto' description: >- Aggregate spot trading metrics for this subaccount: volume, fees, and realized PnL summed across all spot markets. `None` when the subaccount has never traded spot (or the stats MV hasn't materialized yet). positions: type: array items: $ref: '#/components/schemas/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. total_usd: type: number format: double description: >- USDC-equivalent value of every position + reserved amount in open spot orders. example: 872.3 SpotInFlightOrderDto: type: object required: - market_addr - order_id - is_bid - reserved_asset - reserved_amount - reserved_usd_value properties: is_bid: type: boolean example: true market_addr: type: string example: 0x26f1dd... 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' reserved_amount: type: number format: double description: Reserved amount in human units. example: 500 reserved_asset: type: string description: >- FA metadata address for the reserved asset (quote for bids, base for asks). reserved_usd_value: type: number format: double description: USDC-equivalent value at current mark. example: 500 SpotMetricsDto: 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 cumulative_realized_pnl_usd: type: number format: double description: >- Cumulative realized PnL from spot sells, USD. Weighted-average basis. example: 142.55 cumulative_taker_fees_usd: type: number format: double description: Cumulative fees paid on fills where this account was the taker, USD. example: 12.29 cumulative_volume_usd: type: number format: double description: Cumulative spot volume traded (both taker and maker sides), USD. example: 24580.1 SpotPositionDto: 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 asset_addr: type: string description: FA metadata address for the held asset. example: '0x000000000000000000000000000000000000000000000000000000000000000a' 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 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 unrealized_pnl_usd: type: number format: double description: '`usd_value - entry_notional_usd`. Negative when mark < avg cost.' example: 4.75 usd_value: type: number format: double description: amount × current mark price. example: 87.15 securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer token from Geomi. See [Authentication](/api-reference/rest/authentication) for setup instructions. ````