Skip to main content

Documentation Index

Fetch the complete documentation index at: https://staging-docs.orderly.network/llms.txt

Use this file to discover all available pages before exploring further.

Account snapshot with collateral, open positions, margin metrics, and PnL. Response shape depends on the parameters:
  • address + account_id (with or without broker_id) → flat object, one account
  • address (± broker_id) → object containing accounts[] with one entry per matching account
Weight: 5

​
Request

{
  "type": "accountState",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "broker_id": "orderly",
  "account_id": "0xabc..."
}
FieldTypeRequiredDefaultNotes
addressstringYes—Wallet address
broker_idstringNo—Optional broker scope
account_idstringNo—If supplied → flat response; omitted → accounts[] array

​
Account fields

FieldTypeNotes
account_typestring"main" (main account), "sub" (sub-account), or "sp" (vault strategy provider)
account_valuestring | nullMark-to-market account value: total_collateral_value + Σ unrealized_pnl across positions. null if position-calc unreachable
total_collateral_valuestringΣ_token((holding + iso_margin_total + frozen) × price); non-USDC priced via spot index price
free_collateralstring | null≈ collateral × (1 − margin_ratio)
margin_ratiostring | nullFrom position-calc
initial_margin_ratiostring | nullΣ(notional_i × IMR_i) / Σ notional_i over CROSS positions only
maintenance_margin_ratiostring | nullMinimum margin ratio required to avoid liquidation
total_unrealized_pnl, total_unsettled_pnlstring | nullBoth from position-calc
total_pnl_24_hstring | nullSum across positions

​
Position fields

FieldTypeNotes
sidestring"LONG" if position_qty > 0, "SHORT" if < 0
position_qtystringSigned
notionalstring | null`qty× mark_price`
average_open_pricestring | null`cost_position /holding`
mark_pricestring | nullLatest mark price for the symbol
imr, mmrstring | nullPosition-level (from position-calc or symbol metadata)
est_liq_pricestring | nullEstimated liquidation price
leverageint | nullEffective leverage
margin_modestring | null"CROSS" or "ISOLATED"
opened_at, updated_atint64 | nullms epoch; cached 10s

​
Notes

  • Throws ADDRESS_NOT_FOUND (404) if no accounts match
  • If the position-calc service is unavailable, all margin / PnL-derived fields are null while other fields continue to be served
  • positions[] only contains open positions (holding ≠ 0)
{
  "success": true,
  "data": {
    "address": "0x1234...",
    "broker_id": "orderly",
    "account_id": "0xabc...",
    "account_type": "main",
    "account_value": "50000.5",
    "total_collateral_value": "45000",
    "free_collateral": "30000",
    "margin_ratio": "0.25",
    "initial_margin_ratio": "0.12",
    "maintenance_margin_ratio": "0.08",
    "total_unrealized_pnl": "5000.5",
    "total_unsettled_pnl": "100.25",
    "total_pnl_24_h": "250.75",
    "positions": [
      {
        "symbol": "PERP_BTC_USDC",
        "side": "LONG",
        "position_qty": "0.5",
        "notional": "21500",
        "average_open_price": "43000",
        "mark_price": "43000",
        "unrealized_pnl": "0",
        "unsettled_pnl": "50.5",
        "pnl_24_h": "100",
        "imr": "0.05",
        "mmr": "0.025",
        "est_liq_price": "38000",
        "leverage": 10,
        "margin_mode": "CROSS",
        "opened_at": 1715000000000,
        "updated_at": 1715100000000
      }
    ]
  },
  "ts": 1779269143700
}