Skip to main content

​
Balance

GET /v1/account/balance
Returns your current API wallet balance, P&L metrics, and starting capital. API-authenticated requests always read from the API wallet — see Wallets for how API, MAIN, and SANDBOX wallets relate.

​
Authentication

This endpoint accepts either an API key (X-API-Key: <key>, or the PM-compat POLY_API_KEY / Authorization: Bearer ps_live_... aliases) or a Supabase Bearer JWT (Authorization: Bearer <jwt>), so the website’s API-keys dashboard can render the card via the cookie session. The balance returned is always the API wallet regardless of which scheme you use. (Most account endpoints — positions, portfolio, history, equity — are API-key only; balance and reset-api-balance are the exceptions that also accept the JWT.)

​
Request

curl -H "X-API-Key: $API_KEY" \
  https://api.polysimulator.com/v1/account/balance

​
Response

{
  "balance": "9745.20",
  "currency": "USD",
  "starting_balance": "10000.00",
  "unrealized_pnl": "-242.50",
  "total_value": "9757.50"
}
A Pro+ key sees its $25,000 baseline instead: 
{
  "balance": "24745.20",
  "currency": "USD",
  "starting_balance": "25000.00",
  "unrealized_pnl": "-242.50",
  "total_value": "24757.50"
}
FieldTypeDescription
balancestringCurrent API wallet cash balance (available for trading)
currencystringAlways USD
starting_balancestringInitial API wallet capital — your tier baseline (Pro: 10000.00; Pro+: 25000.00). Falls back to 10000.00 when no API wallet baseline is set.
unrealized_pnlstringTotal account P&L: total_value − starting_balance. Despite the name, this is total equity vs starting capital (cash + open-position mark-to-market), not the open-position MTM delta alone — it equals true unrealized P&L only when balance == starting_balance.
total_valuestringCash balance + market value of open API positions
Your total portfolio value = balance + market value of open positions. Use the Portfolio endpoint for a complete snapshot.
Need a clean slate? POST /v1/account/reset-api-balance resets the API wallet to your tier baseline (Pro: 10,000;Pro+:10,000; Pro+: 25,000) and closes all open API positions. Resets are free and currently uncapped — the cooldown is gated by API_RESET_COOLDOWN_DAYS (0 during the beta period, through 2026-08-31). See Wallets for the full reset semantics.

​
Python Example

import requests, os
from decimal import Decimal

BASE_URL = os.environ["POLYSIM_BASE_URL"]
headers = {"X-API-Key": os.environ["POLYSIM_API_KEY"]}

resp = requests.get(f"{BASE_URL}/v1/account/balance", headers=headers)

if resp.status_code == 200:
    data = resp.json()
    balance = Decimal(data["balance"])
    pnl = Decimal(data["total_value"]) - Decimal(data["starting_balance"])
    print(f"Balance: ${balance} | P&L: ${pnl}")
elif resp.status_code == 401:
    print("Invalid API key — check POLYSIM_API_KEY")

​
Errors

All errors return a JSON body of the shape {"error": "<CODE>", "message": "<human-readable>"}.
Statuserror codeWhen
401MISSING_AUTHNo X-API-Key and no Authorization header supplied
401INVALID_KEYAPI key (or Bearer-wrapped key) is unknown, deactivated, or expired
404ACCOUNT_NOT_FOUNDAuthenticated user has no account record

​
Next Steps