Account

Get Balance

Get the user’s current API wallet balance, unrealized PnL, and total value.

Accepts both X-API-Key and Authorization: Bearer <jwt> so the website’s API-keys dashboard can render the API wallet card via the cookie session. The returned balance is always the API wallet (account.api_balance) regardless of auth source, since this is the documented API wallet endpoint — UI MAIN/SANDBOX balances live behind /v1/me/wallets instead.

Per-user 5-second cache (override via BALANCE_CACHE_TTL_S env; set to 0 to disable). Trade writes bust the cache via app.api_v1._user_cache.bust_balance_cache.

GET

account

balance

Get Balance

curl --request GET \
  --url https://api.polysimulator.com/v1/account/balance \
  --header 'X-API-Key: <api-key>'

{
  "balance": "<string>",
  "currency": "<string>",
  "unrealized_pnl": "<string>",
  "total_value": "<string>",
  "starting_balance": "<string>"
}

Authorizations

X-API-Key

string

header

required

Issue from /v1/keys (or admin-issued for enterprise tier).

Headers

authorization

string | null

X-API-Key

string | null

POLY_API_KEY

string | null

Poly-API-Key

string | null

Response

Successful Response

balance

string

required

currency

string

required

unrealized_pnl

string

required

total_value

string

required

starting_balance

string

required

Get PositionsList the user's positions with live valuations from Redis cache. Wallet scoping (2026-06-10): ``wallet_id`` accepts an integer wallet id (ownership-checked, 404 otherwise), ``all`` (cross-wallet) or ``api`` (the caller's API wallet, legacy NULL rows included). The default (param omitted) is the **API wallet**, matching /balance, /portfolio and /equity; before 2026-06-10 the default was all-wallets — pass ``wallet_id=all`` for the old behaviour. Per-user 5-second cache (override via ``POSITIONS_CACHE_TTL_S`` env). Set TTL to ``0`` to disable caching for debugging.

Get Balance

curl --request GET \
  --url https://api.polysimulator.com/v1/account/balance \
  --header 'X-API-Key: <api-key>'

{
  "balance": "<string>",
  "currency": "<string>",
  "unrealized_pnl": "<string>",
  "total_value": "<string>",
  "starting_balance": "<string>"
}