> ## Documentation Index > Fetch the complete documentation index at: https://docs.polysimulator.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Positions > List 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. ## OpenAPI ````yaml /openapi.json get /v1/account/positions openapi: 3.1.0 info: title: Polysimulator API summary: HFT-style paper-trading API for Polymarket simulation. description: >- PolySimulator HFT API v1 — Virtual trading environment for Polymarket prediction markets. Practice trading with real market data using paper money, then switch to live trading by changing only your API credentials. termsOfService: https://polysimulator.com/legal/terms contact: name: PolySimulator url: https://polysimulator.com license: name: Proprietary — usage subject to Polysimulator Terms of Service url: https://polysimulator.com/legal/terms version: 1.0.0-beta servers: - url: https://api.polysimulator.com description: Production - url: https://staging-api.polysimulator.com description: Staging security: - ApiKeyAuth: [] tags: - name: API Keys description: >- Bootstrap, create, list, revoke API keys, mint short-lived WebSocket tokens, list rate-limit tiers. - name: Account description: >- Balance, equity curve, portfolio composition, open positions, trade history. - name: Export description: >- Pro data export — streamed CSV downloads for offline analysis, backtesting, and tax/accounting. v1: GET /v1/export/trades.csv (FILLED trades, keyset-paginated). Dual session + API-key auth. - name: Profile Analysis description: >- Trading-profile analytics — Sharpe, win-rate, drawdown, holding-period histograms. - name: Wallets description: >- Multi-wallet management (MAIN / SANDBOX / API / COMPETITION). List, switch active wallet, per-wallet balance + history. - name: Trading description: >- Place, cancel, batch, and list orders. Cancel-all + cancel-market-orders sweep endpoints. PolySimulator-native order surface. - name: Market Data description: >- Polymarket market metadata + live prices (POST /v1/prices/batch, /v1/markets, /v1/markets/{condition_id}/candles). - name: CLOB Read (Public) description: >- Polymarket-shape read endpoints (book, midpoint, spread, price, last-trade-price, tick-size, neg-risk, time). Wire-compatible with py-clob-client. - name: CLOB Compat description: >- Polymarket-shape order surface (POST /v1/order with nested body, POST /v1/orders batch, GET /v1/data/orders PM-envelope). Use these for drop-in py-clob-client compatibility. - name: WebSocket description: >- WebSocket subscription endpoints — /v1/ws/prices for live market data, /v1/ws/executions for order-state updates. - name: Billing description: >- Stripe-backed subscriptions, top-ups, customer portal, refund policy, paid-tier resets. - name: Status description: System-status surface — uptime, component health, recent incident markers. - name: Health description: >- Health, liveness, readiness, and authenticated-identity probes (/v1/health, /v1/health/live, /v1/health/ready, /v1/me). - name: Football description: >- Football / World-Cup 2026 enrichment — live score, minute, momentum, possession, xG, shotmap, commentary, lineups, group standings, knockout bracket, and head-to-head. Public read-only sports facts the UI merges with tradable Polymarket prices; degrades to empty shapes on upstream failure. paths: /v1/account/positions: get: tags: - Account - Account summary: Get Positions description: |- List 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. operationId: listPositions parameters: - name: status in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Filter by status: OPEN or CLOSED' title: Status description: 'Filter by status: OPEN or CLOSED' - name: wallet_id in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Wallet scope: an integer wallet id you own (404 WALLET_NOT_FOUND otherwise; MAIN/API wallet ids fold in legacy rows recorded before per-wallet attribution, matching /portfolio), 'all' (every wallet you own, including UI MAIN/SANDBOX wallets), or 'api' (your API wallet — includes legacy pre-attribution rows). Keywords are case-insensitive; any other value returns 422 VALIDATION_FAILED. **Default (omitted) = 'api'** since 2026-06-10, matching /balance, /portfolio and /equity; before 2026-06-10 the default was all-wallets — pass wallet_id=all to keep the old behaviour. title: Wallet Id description: >- Wallet scope: an integer wallet id you own (404 WALLET_NOT_FOUND otherwise; MAIN/API wallet ids fold in legacy rows recorded before per-wallet attribution, matching /portfolio), 'all' (every wallet you own, including UI MAIN/SANDBOX wallets), or 'api' (your API wallet — includes legacy pre-attribution rows). Keywords are case-insensitive; any other value returns 422 VALIDATION_FAILED. **Default (omitted) = 'api'** since 2026-06-10, matching /balance, /portfolio and /equity; before 2026-06-10 the default was all-wallets — pass wallet_id=all to keep the old behaviour. - name: envelope in: query required: false schema: type: boolean default: false title: Envelope - name: X-API-Key in: header required: false schema: anyOf: - type: string - type: 'null' description: Your PolySimulator API key title: X-Api-Key description: Your PolySimulator API key - name: POLY_API_KEY in: header required: false schema: anyOf: - type: string - type: 'null' description: >- Polymarket-CLOB-compat alias for ``X-API-Key`` (underscore form). SDK clients ported from Polymarket can authenticate without changing header names. ``X-API-Key`` takes precedence when both are provided. title: Poly Api Key description: >- Polymarket-CLOB-compat alias for ``X-API-Key`` (underscore form). SDK clients ported from Polymarket can authenticate without changing header names. ``X-API-Key`` takes precedence when both are provided. - name: Poly-API-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: Poly-Api-Key - name: authorization in: header required: false schema: anyOf: - type: string - type: 'null' description: >- PM-CLOB-compat: ``Authorization: Bearer ps_live_...`` (or ``ps_test_...``) is accepted as an alias for ``X-API-Key`` so py-clob-client and other ported SDKs authenticate without header name changes. Bearer JWTs are NOT accepted here — use the dashboard-auth endpoints for those. title: Authorization description: >- PM-CLOB-compat: ``Authorization: Bearer ps_live_...`` (or ``ps_test_...``) is accepted as an alias for ``X-API-Key`` so py-clob-client and other ported SDKs authenticate without header name changes. Bearer JWTs are NOT accepted here — use the dashboard-auth endpoints for those. responses: '200': description: Successful Response content: application/json: schema: anyOf: - type: array items: $ref: '#/components/schemas/PositionResponse' - $ref: '#/components/schemas/PositionsEnvelope' title: Response Listpositions headers: X-RateLimit-Limit: description: >- Requests permitted in the current minute window for this key's tier. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the current minute window. schema: type: string X-RateLimit-Reset: description: Unix-seconds timestamp when the current minute window resets. schema: type: string X-RateLimit-Limit-Per-Second: description: Requests permitted per second for this key's tier. schema: type: string X-RateLimit-Remaining-Per-Second: description: Requests remaining in the current one-second window. schema: type: string X-RateLimit-Tier: description: Rate-limit tier name applied to this request (free, pro, ...). schema: type: string X-Polysim-RateLimit-Limit: description: Alias of X-RateLimit-Limit (requests per minute for this tier). schema: type: string X-Polysim-RateLimit-Remaining: description: Alias of X-RateLimit-Remaining (requests remaining this minute). schema: type: string X-Polysim-RateLimit-Reset: description: Alias of X-RateLimit-Reset (minute-window reset, unix seconds). schema: type: string X-Polysim-RateLimit-Limit-Per-Second: description: Alias of X-RateLimit-Limit-Per-Second. schema: type: string X-Polysim-RateLimit-Remaining-Per-Second: description: Alias of X-RateLimit-Remaining-Per-Second. schema: type: string X-Polysim-RateLimit-Tier: description: Alias of X-RateLimit-Tier (tier name applied to this request). schema: type: string X-Request-Id: description: >- Request id for log correlation. Echoes the caller's ``X-Request-Id`` when supplied, otherwise a server-minted UUID. Stamped on every response (success and error). schema: type: string '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ApiError' headers: X-Polysim-Code: description: >- Stable short code identifying the error class. SDK consumers should branch on this header rather than the body text. Domain codes (INVALID_KEY, MARKET_NOT_FOUND, RATE_LIMIT_EXCEEDED, …) are preferred; HTTP_ fallbacks ship when no domain code applies. The full list is mirrored in /llms.txt under ‘Error Format’. schema: type: string enum: - INVALID_KEY - MISSING_API_KEY - INSUFFICIENT_PERMISSION - INSUFFICIENT_BALANCE - MARKET_CLOSED - INVALID_ORDER_MIN_TICK_SIZE - MARKET_NOT_FOUND - ORDER_NOT_FOUND - RATE_LIMIT_EXCEEDED - BOOK_UNAVAILABLE - VALIDATION_FAILED - UPGRADE_REQUIRED - ACCESS_RESTRICTED - COHORT_FULL - AUTH_STATE_INCOMPLETE - INTERNAL_ERROR - TOKEN_NOT_FOUND - INVALID_CURSOR - UPSTREAM_UNAVAILABLE - UNSUPPORTED_ORDER_TYPE - DUPLICATE_CLIENT_ORDER_ID - ORDER_EXECUTION_FAILED - DEADLINE_OVERSHOT_BUT_PERSISTED - PERSISTENCE_UNKNOWN - INVALID_BODY - INVALID_SOURCE - CLOSED_BETA - API_PRO_COMING_SOON - TIER_KEY_LIMIT_EXCEEDED - HTTP_400 - HTTP_401 - HTTP_403 - HTTP_404 - HTTP_409 - HTTP_422 - HTTP_429 - HTTP_500 - HTTP_502 - HTTP_503 X-Request-Id: description: >- Request id for log correlation. Echoes the caller's ``X-Request-Id`` when supplied, otherwise a server-minted UUID. Stamped on every response (success and error). schema: type: string '403': description: Insufficient permission or access restricted. content: application/json: schema: $ref: '#/components/schemas/ApiError' headers: X-Polysim-Code: description: >- Stable short code identifying the error class. SDK consumers should branch on this header rather than the body text. Domain codes (INVALID_KEY, MARKET_NOT_FOUND, RATE_LIMIT_EXCEEDED, …) are preferred; HTTP_ fallbacks ship when no domain code applies. The full list is mirrored in /llms.txt under ‘Error Format’. schema: type: string enum: - INVALID_KEY - MISSING_API_KEY - INSUFFICIENT_PERMISSION - INSUFFICIENT_BALANCE - MARKET_CLOSED - INVALID_ORDER_MIN_TICK_SIZE - MARKET_NOT_FOUND - ORDER_NOT_FOUND - RATE_LIMIT_EXCEEDED - BOOK_UNAVAILABLE - VALIDATION_FAILED - UPGRADE_REQUIRED - ACCESS_RESTRICTED - COHORT_FULL - AUTH_STATE_INCOMPLETE - INTERNAL_ERROR - TOKEN_NOT_FOUND - INVALID_CURSOR - UPSTREAM_UNAVAILABLE - UNSUPPORTED_ORDER_TYPE - DUPLICATE_CLIENT_ORDER_ID - ORDER_EXECUTION_FAILED - DEADLINE_OVERSHOT_BUT_PERSISTED - PERSISTENCE_UNKNOWN - INVALID_BODY - INVALID_SOURCE - CLOSED_BETA - API_PRO_COMING_SOON - TIER_KEY_LIMIT_EXCEEDED - HTTP_400 - HTTP_401 - HTTP_403 - HTTP_404 - HTTP_409 - HTTP_422 - HTTP_429 - HTTP_500 - HTTP_502 - HTTP_503 X-Request-Id: description: >- Request id for log correlation. Echoes the caller's ``X-Request-Id`` when supplied, otherwise a server-minted UUID. Stamped on every response (success and error). schema: type: string '404': description: Resource not found (market / order / token). content: application/json: schema: $ref: '#/components/schemas/ApiError' headers: X-Polysim-Code: description: >- Stable short code identifying the error class. SDK consumers should branch on this header rather than the body text. Domain codes (INVALID_KEY, MARKET_NOT_FOUND, RATE_LIMIT_EXCEEDED, …) are preferred; HTTP_ fallbacks ship when no domain code applies. The full list is mirrored in /llms.txt under ‘Error Format’. schema: type: string enum: - INVALID_KEY - MISSING_API_KEY - INSUFFICIENT_PERMISSION - INSUFFICIENT_BALANCE - MARKET_CLOSED - INVALID_ORDER_MIN_TICK_SIZE - MARKET_NOT_FOUND - ORDER_NOT_FOUND - RATE_LIMIT_EXCEEDED - BOOK_UNAVAILABLE - VALIDATION_FAILED - UPGRADE_REQUIRED - ACCESS_RESTRICTED - COHORT_FULL - AUTH_STATE_INCOMPLETE - INTERNAL_ERROR - TOKEN_NOT_FOUND - INVALID_CURSOR - UPSTREAM_UNAVAILABLE - UNSUPPORTED_ORDER_TYPE - DUPLICATE_CLIENT_ORDER_ID - ORDER_EXECUTION_FAILED - DEADLINE_OVERSHOT_BUT_PERSISTED - PERSISTENCE_UNKNOWN - INVALID_BODY - INVALID_SOURCE - CLOSED_BETA - API_PRO_COMING_SOON - TIER_KEY_LIMIT_EXCEEDED - HTTP_400 - HTTP_401 - HTTP_403 - HTTP_404 - HTTP_409 - HTTP_422 - HTTP_429 - HTTP_500 - HTTP_502 - HTTP_503 X-Request-Id: description: >- Request id for log correlation. Echoes the caller's ``X-Request-Id`` when supplied, otherwise a server-minted UUID. Stamped on every response (success and error). schema: type: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/ApiError' headers: X-Polysim-Code: description: >- Stable short code identifying the error class. SDK consumers should branch on this header rather than the body text. Domain codes (INVALID_KEY, MARKET_NOT_FOUND, RATE_LIMIT_EXCEEDED, …) are preferred; HTTP_ fallbacks ship when no domain code applies. The full list is mirrored in /llms.txt under ‘Error Format’. schema: type: string enum: - INVALID_KEY - MISSING_API_KEY - INSUFFICIENT_PERMISSION - INSUFFICIENT_BALANCE - MARKET_CLOSED - INVALID_ORDER_MIN_TICK_SIZE - MARKET_NOT_FOUND - ORDER_NOT_FOUND - RATE_LIMIT_EXCEEDED - BOOK_UNAVAILABLE - VALIDATION_FAILED - UPGRADE_REQUIRED - ACCESS_RESTRICTED - COHORT_FULL - AUTH_STATE_INCOMPLETE - INTERNAL_ERROR - TOKEN_NOT_FOUND - INVALID_CURSOR - UPSTREAM_UNAVAILABLE - UNSUPPORTED_ORDER_TYPE - DUPLICATE_CLIENT_ORDER_ID - ORDER_EXECUTION_FAILED - DEADLINE_OVERSHOT_BUT_PERSISTED - PERSISTENCE_UNKNOWN - INVALID_BODY - INVALID_SOURCE - CLOSED_BETA - API_PRO_COMING_SOON - TIER_KEY_LIMIT_EXCEEDED - HTTP_400 - HTTP_401 - HTTP_403 - HTTP_404 - HTTP_409 - HTTP_422 - HTTP_429 - HTTP_500 - HTTP_502 - HTTP_503 X-Request-Id: description: >- Request id for log correlation. Echoes the caller's ``X-Request-Id`` when supplied, otherwise a server-minted UUID. Stamped on every response (success and error). schema: type: string '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ApiError' headers: X-Polysim-Code: description: >- Stable short code identifying the error class. SDK consumers should branch on this header rather than the body text. Domain codes (INVALID_KEY, MARKET_NOT_FOUND, RATE_LIMIT_EXCEEDED, …) are preferred; HTTP_ fallbacks ship when no domain code applies. The full list is mirrored in /llms.txt under ‘Error Format’. schema: type: string enum: - INVALID_KEY - MISSING_API_KEY - INSUFFICIENT_PERMISSION - INSUFFICIENT_BALANCE - MARKET_CLOSED - INVALID_ORDER_MIN_TICK_SIZE - MARKET_NOT_FOUND - ORDER_NOT_FOUND - RATE_LIMIT_EXCEEDED - BOOK_UNAVAILABLE - VALIDATION_FAILED - UPGRADE_REQUIRED - ACCESS_RESTRICTED - COHORT_FULL - AUTH_STATE_INCOMPLETE - INTERNAL_ERROR - TOKEN_NOT_FOUND - INVALID_CURSOR - UPSTREAM_UNAVAILABLE - UNSUPPORTED_ORDER_TYPE - DUPLICATE_CLIENT_ORDER_ID - ORDER_EXECUTION_FAILED - DEADLINE_OVERSHOT_BUT_PERSISTED - PERSISTENCE_UNKNOWN - INVALID_BODY - INVALID_SOURCE - CLOSED_BETA - API_PRO_COMING_SOON - TIER_KEY_LIMIT_EXCEEDED - HTTP_400 - HTTP_401 - HTTP_403 - HTTP_404 - HTTP_409 - HTTP_422 - HTTP_429 - HTTP_500 - HTTP_502 - HTTP_503 X-Request-Id: description: >- Request id for log correlation. Echoes the caller's ``X-Request-Id`` when supplied, otherwise a server-minted UUID. Stamped on every response (success and error). schema: type: string components: schemas: PositionResponse: properties: id: type: integer title: Id market_id: type: string title: Market Id outcome: type: string title: Outcome quantity: type: string title: Quantity avg_entry_price: type: string title: Avg Entry Price current_price: anyOf: - type: string - type: 'null' title: Current Price unrealized_pnl: anyOf: - type: string - type: 'null' title: Unrealized Pnl market_value: anyOf: - type: string - type: 'null' title: Market Value status: type: string title: Status market_question: anyOf: - type: string - type: 'null' title: Market Question type: object required: - id - market_id - outcome - quantity - avg_entry_price - status title: PositionResponse PositionsEnvelope: properties: data: items: $ref: '#/components/schemas/PositionResponse' type: array title: Data next_cursor: type: string title: Next Cursor default: '' type: object required: - data title: PositionsEnvelope description: |- PM-shape envelope for ``GET /v1/account/positions?envelope=true``. ``next_cursor`` is always ``""`` (positions are unpaginated). ApiError: properties: error: type: string title: Error description: >- Human-readable message (PM-shape default body) OR machine-readable error code (verbose body). The machine code is always available in the X-Polysim-Code response header. message: anyOf: - type: string - type: 'null' title: Message description: >- Human-readable error description — populated only on verbose body (X-Polysim-Verbose: true). details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: Additional context — populated only on verbose body. request_id: anyOf: - type: string - type: 'null' title: Request Id description: >- Request id for support reference. Always exposed via X-Request-Id response header; only inlined in the verbose body. type: object required: - error title: ApiError description: |- Structured error response for all API v1 endpoints. * ``error`` carries the human-readable message in the default body and the machine code in the verbose body. The machine code is ALWAYS exposed via the ``X-Polysim-Code`` response header so SDK consumers can switch on a stable identifier without parsing the body. * ``request_id`` → exposed as the ``X-Request-Id`` response header on every response (success and error). All non-required fields are ``Optional`` so generated SDK code can deserialize *either* shape (PM-default or polysim-verbose) without choking on missing keys. Pre-PR ``message`` was required, which broke SDK deserialization of the new PM-shape body. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: Issue from /v1/keys (or admin-issued for enterprise tier). ````