Skip to main content
GET
/
api
/
v1
/
account_overviews
Get account overview
curl --request GET \
  --url https://api.mainnet.aptoslabs.com/decibel/api/v1/account_overviews \
  --header 'Authorization: Bearer <token>'
{
  "cross_account_leverage_ratio": 40.99,
  "cross_available_to_trade": 4791.47,
  "cross_margin_ratio": 0.01,
  "maintenance_margin": 115.29,
  "margin_deficit": -12.06,
  "perp_equity_balance": 10064.88,
  "perp_equity_haircutted": 10054.92,
  "total_margin": 9998.72,
  "unrealized_funding_cost": -87.84,
  "unrealized_pnl": 154,
  "usdc_cross_withdrawable_balance": 9843.79,
  "usdc_isolated_withdrawable_balance": 0,
  "all_time_return": 123,
  "average_cash_position": 123,
  "average_leverage": 123,
  "cross_account_position": 123,
  "fee_income": 5386,
  "free_vault_equity": 14.65,
  "liquidation_fees_paid": 45.5,
  "liquidation_losses": -500,
  "max_drawdown": 123,
  "net_deposits": 30277044.96,
  "pnl_90d": 123,
  "realized_pnl": 1250.5,
  "secondary_collateral": [
    {
      "amount": 150,
      "asset_type": "0x1234...",
      "haircut_bps": 500,
      "nav_per_unit": 1.05,
      "value_in_usdc": 142.5,
      "withdrawable_amount": 100
    }
  ],
  "sharpe_ratio": 123,
  "vault_equity": 259.73,
  "volume": 123,
  "weekly_win_rate_12w": 123
}

Authorizations

​
Authorization
string
header
required

Bearer token from Geomi. See Authentication for setup instructions.

Query Parameters

​
account
string
required

User account address (user query alias is also accepted)

​
volume_window
enum<string>

Volume time window (e.g., "7d", "14d", "30d", "90d"). Omit to exclude volume data. Time window for volume queries

Available options:
7d,
14d,
30d,
90d
​
include_performance
boolean
default:false

Include performance metrics

​
performance_lookback_days
integer<int32>
default:90

Performance lookback window in days.

Required range: x >= 0

Response

Account overview retrieved successfully

​
cross_account_leverage_ratio
number<double>
required
Example:

40.99

​
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.

Example:

4791.47

​
cross_margin_ratio
number<double>
required
Example:

0.01

​
maintenance_margin
number<double>
required
Example:

115.29

​
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)

Example:

-12.06

​
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.

Example:

10064.88

​
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.

Example:

10054.92

​
total_margin
number<double>
required
Example:

9998.72

​
unrealized_funding_cost
number<double>
required
Example:

-87.84

​
unrealized_pnl
number<double>
required
Example:

154

​
usdc_cross_withdrawable_balance
number<double>
required
Example:

9843.79

​
usdc_isolated_withdrawable_balance
number<double>
required
Example:

0

​
all_time_return
number<double> | null
​
average_cash_position
number<double> | null
​
average_leverage
number<double> | null
​
cross_account_position
number<double> | null
​
fee_income
number<double> | null

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
number<double> | null

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
number<double> | null

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
number<double> | null

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

​
max_drawdown
number<double> | null
​
net_deposits
number<double> | null

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

​
pnl_90d
number<double> | null
​
realized_pnl
number<double> | null
Example:

1250.5

​
secondary_collateral
object[] | null

Secondary (non-USDC) collateral held in cross margin. NULL when no secondary collateral exists or oracle data is unavailable.

​
sharpe_ratio
number<double> | null
​
vault_equity
number<double> | null

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
number<double> | null
​
weekly_win_rate_12w
number<double> | null