🚀 Enhanced - Account State Endpoint

Improved Risk & Market Data

The /account_state/{account} endpoint now provides significantly more detailed information to support advanced trading strategies and risk management.

Breaking Changes

Response Structure Flattened: The summary wrapper object has been removed. Account state fields are now directly accessible at the root level of each margin account.

Before:

{
  "margin_accounts": [
    {
      "pair": "ETH_USDC",
      "summary": {
        "equity": 10500.0,
        "im": 2000.0,
        "mm": 1500.0,
        "pnl": 500.0
      },
      "positions": [...]
    }
  ]
}

After:

{
  "margin_accounts": [
    {
      "pair": "ETH_USDC",
      "timestamp": 1677721600000,
      "margin_account": 12345,
      "equity": 10500.0,
      "im": 2000.0,
      "mm": 1500.0,
      "unrealised_pnl": 500.0,
      // ... additional fields
      "positions": [...]
    }
  ]
}

New Response Fields

timestamp: Unix timestamp when the account state was calculated
margin_account: Unique margin account identifier
matrix_risk: Portfolio risk matrix component for comprehensive risk assessment
delta_risk: Delta risk component measuring directional exposure
roll_risk: Roll risk component for near-expiry option positions
portfolio_greeks: Portfolio-level Greeks aggregation
- delta: Portfolio delta exposure
- gamma: Portfolio gamma exposure
- vega: Portfolio vega exposure
- theta: Portfolio theta (time decay)
- rho: Portfolio rho (interest rate sensitivity)

Enhanced Position Data

Positions now include real-time market data and risk metrics:

For Options:

instrument_type: Always "option" for option positions
mark_price: Current mark price of the option
mark_iv: Mark implied volatility
mark_interest: Mark interest rate used in pricing
position_greeks: Position-level Greeks
- delta, gamma, theta, vega, rho

For Perpetuals:

instrument_type: Always "perp" for perpetual positions
mark_price: Current mark price of the perpetual
current_funding_rate: Current funding rate
position_greeks: Position-level Greeks
- delta

Migration Guide

Update your code to access account state fields directly:

// Before
const equity = accountState.margin_accounts[0].summary.equity;
const im = accountState.margin_accounts[0].summary.im;

// After
const equity = accountState.margin_accounts[0].equity;
const im = accountState.margin_accounts[0].im;

// New capabilities
const portfolioGreeks = accountState.margin_accounts[0].portfolio_greeks;
const riskBreakdown = {
  matrix: accountState.margin_accounts[0].matrix_risk,
  delta: accountState.margin_accounts[0].delta_risk,
  roll: accountState.margin_accounts[0].roll_risk,
};

Benefits

Better Risk Management: Detailed risk component breakdown enables more sophisticated risk monitoring
Real-time Market Data: Position-level mark prices and Greeks for accurate P&L calculation
Reduced API Calls: Mark prices and Greeks available directly without additional requests
Enhanced Analytics: Portfolio-level Greeks aggregation for portfolio analysis
Streamlined Integration: Simplified response structure reduces parsing complexity

For questions or support, please contact our development team or visit our documentation.

Changelog

v1.1.1 - 2025-01-09

🔧 Fixed - API Header Standardization

v1.1.0 - 2025-01-04

🚀 Enhanced - Account State Endpoint