Skip to main content

​
Endpoints

EndpointMethodDescriptionRate Limit
/v1/portfolio/positionsGETGet positions2 req/min
/v1/account/balancesGETGet balances2 req/min
Authentication: API key signature

​
Get Positions

View all open positions across all instruments. Request: 
GET /v1/portfolio/positions
X-API-Key: {api_key}
X-API-Signature: {signature}
Response: 
{
  "positions": [
    {
      "instrument_id": "inst_abc123",
      "instrument_slug": "will-btc-hit-100k-by-dec-31",
      "side": "long",
      "quantity": 150,
      "entry_price": 0.55,
      "current_price": 0.62,
      "unrealized_pnl": 10.50,
      "unrealized_pnl_percentage": 12.73
    },
    {
      "instrument_id": "inst_def456",
      "instrument_slug": "trump-win-2024",
      "side": "long",
      "quantity": 200,
      "entry_price": 0.48,
      "current_price": 0.45,
      "unrealized_pnl": -6.00,
      "unrealized_pnl_percentage": -6.25
    }
  ],
  "total_unrealized_pnl": 4.50
}

​
Position Fields

FieldTypeDescription
instrument_idstringUnique instrument identifier
instrument_slugstringHuman-readable instrument slug
sidestringPosition direction (long or short)
quantitynumberNumber of contracts held
entry_pricenumberAverage entry price
current_pricenumberCurrent market price
unrealized_pnlnumberProfit/loss if closed at current price
unrealized_pnl_percentagenumberP&L as percentage of entry value

​
Get Balances

View account balance information. Request: 
GET /v1/account/balances
X-API-Key: {api_key}
X-API-Signature: {signature}
Response: 
{
  "currency": "USD",
  "total_balance": 1000.00,
  "available_balance": 750.00,
  "reserved_balance": 250.00,
  "unrealized_pnl": 4.50,
  "positions_value": 245.50
}

​
Balance Fields

FieldTypeDescription
currencystringAccount currency (always USD)
total_balancenumberTotal account value (available + reserved + unrealized P&L)
available_balancenumberCash available for new orders
reserved_balancenumberCash locked in open orders
unrealized_pnlnumberTotal unrealized profit/loss from positions
positions_valuenumberCurrent market value of all positions

​
Understanding Your Balances

Total Balance = Available + Reserved + Unrealized P&L
Example:
  • You deposit $1000
  • You place a $200 limit order (not yet filled) → Reserved: $200, Available: $800
  • Order fills → Reserved: $0, Available: $800, Position Value: $200
  • Position increases to $220 → Unrealized P&L: +$20, Total Balance: $1020
These features will soon be available via the Retail API:
  • /v1/user-pnl - Detailed P&L breakdown
  • /v1/user-pnl/position-cost-basis - Cost basis per position
  • /v1/portfolio/activities - Activity history
In the meantime users could calculate P&L client-side using order fill data.

​
Best Practices

  • Cache balance data - Don’t poll balances every second. Use the 2 req/min wisely.
  • Subscribe to order fills - Use WebSocket to track order executions in real-time
  • Calculate P&L client-side - Track your own cost basis and realized P&L
  • Reconcile regularly - Compare your calculated balances with API responses daily