Health

Get Api Me

Get the authenticated user’s profile and account balance.

Accepts both X-API-Key and Authorization: Bearer <jwt> authentication. Useful as a quick connectivity test and to retrieve balance without hitting the full /v1/account/balance endpoint.

The permissions field reflects the scope of the AUTHENTICATING key (e.g. ["read", "trade"] or ["read"] for a free-tier / read-only key), so a developer can inspect what their key can do without parsing the keys endpoint. For Bearer-JWT (dashboard) auth there is no API key, so the documented default scope is returned.

Per-user 5s Redis cache (override via ME_CACHE_TTL_S env). Set TTL to 0 to disable. Cache de-amplifies the 2-DB-query body — the pool was exhausting at c=50 sustained because every authed request held a session for ~150-300ms (launch-eve perf RCA, F-2).

GET

Get Api Me

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

{
  "user_id": 123,
  "balance": "<string>",
  "currency": "<string>",
  "key_count": 123,
  "tier": "<string>",
  "permissions": [
    "<string>"
  ],
  "auth_user_id": "<string>",
  "email": "<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

user_id

integer

required

balance

string

required

Paper balance as a decimal string.

currency

string

required

key_count

integer

required

tier

string

required

Rate-limit tier (free, pro, ...).

permissions

string[]

required

Scope of the authenticating API key (e.g. ["read", "trade"]). Bearer-JWT auth returns the default key scope.

auth_user_id

string | null

List markets (bare array; opt-in PM-shape envelope).List markets with live prices from cache. Public read — no authentication required (P1-4). Consistent with the other public CLOB-read endpoints (``/v1/book``, ``/v1/price``, ``/v1/midpoint``, …) so the keyless quickstart works. The single- market sub-routes (``/v1/markets/{cid}`` and its ``/book`` / ``/candles`` children) keep their ``get_api_user`` gate. Per-IP / per-key rate limiting is applied by the middleware via ``_V1_PUBLIC_CLOB_READ_PATHS`` since no ``get_api_user`` runs here. Markets are sourced from the Redis market-list cache filled by the background poller. Each market is enriched with its latest cached price data. Wrapped in a 30 s endpoint-level Redis cache (override via ``MARKETS_LIST_CACHE_TTL_S``). The wrapper de-amplifies the multi-MB ``markets:list:poller`` JSON parse path, which the 2026-05-08 perf audit measured at p99 = 14–63 s under load. The in-memory ``_parsed_market_cache`` already shaves the JSON parse cost per worker but is per-pid — the Redis wrapper makes the same response shareable across all replicas. See ``docs/internal/2026-05-08-platform-upgrade-plan.md`` §3.8. ``active_only`` is a post-filter pass over the (already cached and paginated) market list — cheap and safe because the cache slice is already volume-ordered and the filter only drops a few closed rows. ``category`` and ``q`` are search-class filters: with a fixed ``offset/limit`` page the post-filter would only ever see the first N volume-ordered markets, so ``?q=trump&limit=50`` (Aidan audit 2026-05-18) would correctly find zero matches in the first 50 rows even when thousands of "trump" markets exist deeper in the catalog. For those filters we therefore fetch a wider window (``SEARCH_FILTER_SCAN_WINDOW``, default 500) from offset=0, apply the substring match, THEN paginate the FILTERED result. The response-cache wrapper still de-amplifies the underlying poller- blob parse cost; we just key it on the wider window for search- qualified requests so different ``q`` values share one warmed scan.

Get Api Me

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

{
  "user_id": 123,
  "balance": "<string>",
  "currency": "<string>",
  "key_count": 123,
  "tier": "<string>",
  "permissions": [
    "<string>"
  ],
  "auth_user_id": "<string>",
  "email": "<string>"
}