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>). 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.50000000000000000",
  "total_value": "9757.50000000000000000"
}

A Pro+ key sees its $25,000 baseline instead:

{
  "balance": "24745.20",
  "currency": "USD",
  "starting_balance": "25000.00",
  "unrealized_pnl": "-242.50000000000000000",
  "total_value": "24757.50000000000000000"
}

Field	Type	Description
`balance`	string	Current API wallet cash balance (available for trading)
`currency`	string	Always `USD`
`starting_balance`	string	Initial 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_pnl`	string	Total 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_value`	string	Cash 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.

Numeric & Decimal Precision: Cash fields (balance, starting_balance) are formatted to 2 decimal places. P&L-derived fields (unrealized_pnl, total_value) preserve full Decimal precision (up to 19+ decimal places) from internal position accounting. Always parse monetary fields with Decimal(str_value) (Python) or a bignumber library, never cast to IEEE-754 float.

Need a clean slate? POST /v1/account/reset-api-balance resets the API wallet to your tier baseline (Pro:

10,000; Pro+:

25,000) and closes all open API positions. On a paid tier resets are currently uncapped — the cooldown is API_RESET_COOLDOWN_DAYS, presently 0. On Free it returns 402 UPGRADE_REQUIRED; the $100 budget is non-renewable. 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>"}.

Status	`error` code	When
401	`MISSING_AUTH`	No `X-API-Key` and no `Authorization` header supplied
401	`INVALID_KEY`	API key (or Bearer-wrapped key) is unknown, deactivated, or expired
404	`ACCOUNT_NOT_FOUND`	Authenticated user has no account record

Next Steps

Positions — View open and closed positions
Portfolio — Complete portfolio overview

Getting Started

Core Concepts

Trading Guide

Market Data

Simulation

Account & Portfolio

WebSocket Feeds

Bot Development

Going Live

Balance

Balance

Authentication

Request

Response

Python Example

Errors

Next Steps

​Balance

​Authentication

​Request

​Response

​Python Example

​Errors

​Next Steps

Balance

Authentication

Request

Response

Python Example

Errors

Next Steps