Wallet Positions (Polymarket)
Open positions for a Polymarket wallet with realized vs. unrealized PnL split explicitly. Realized PnL is net of taker fees (deducted at fill time); unrealized is mark-to-market on open size and pre-fee. See the response field documentation for authoritative definitions.
/v2/wallet/{addr}/positionsQuery Parameters
Wallet address — must match ^0x[a-fA-F0-9]{40}$. Lowercased before lookup. Use the Polymarket proxy wallet address; the base/EOA address returns no results. Get it from /v2/wallet/{addr}/identity (proxy_wallet).
Optional. Page size, default 100, max 200.
Optional. Page offset, default 0. Use offset += limit to walk pages.
Response Schema
Wallet address (lowercased).
Page size returned (max 200).
Page offset.
Number of positions returned in this page.
True when count == limit, indicating another page may exist. Use offset += limit to fetch the next page.
Per-position rows. Realized vs unrealized PnL is split explicitly — see _meta.field_definitions for exact semantics.
Polymarket proxy wallet.
Market condition ID.
Outcome token ID (CTF ERC-1155).
Human outcome label (e.g. "Yes").
Outcome index in the market.
Open share count.
VWAP entry price across all fills for the open size.
USDC paid to acquire the open size (avg_price * size). Excludes already-realized portions and excludes taker fees.
Current mid-market price used to mark the open position.
mark_price * size — paper value of the open position.
PnL locked in from sells/redemptions/conversions. Already net of taker fees Polymarket charged at fill time. Will not change as the market moves.
Mark-to-market PnL on the open size only. Moves tick-by-tick. Pre-fee — fees would only be incurred on eventual close.
realized_pnl + unrealized_pnl.
Percentage return on the position.
Market resolved and the position can be redeemed for USDC.
NegRisk (multi-outcome) market flag.
Market title (display).
Market slug.
Market icon URL.
Parent event slug.
Source, cache, and authoritative field definitions.
Data source identifier.
Cache window in seconds.
Per-field semantic definitions for realized_pnl, unrealized_pnl, total_pnl, mark_price, cost_basis.
How taker fees are reflected in the PnL fields.
Error Responses
All errors return the same envelope. The code field is stable and programmatically branchable; error and message are human-readable. errors[] is present only on validation failures with field-level detail. See the full error code reference →
Always `false` on error responses.
Short, human-readable title (e.g. 'Invalid API Key.').
Human-readable explanation for the error. Safe to surface in UIs.
Stable, hierarchical machine-readable code (e.g. 'validation.invalid_enum'). Use for programmatic handling.
Link to this code's entry in the Error Reference.
Optional. Present only on validation failures with field-level detail.
Name of the offending parameter.
Field-level machine code.
Human-readable explanation.
Authentication
API Key
To secure your requests, we strongly recommend passing your API key via the X-API-Key header. This prevents sensitive keys from being exposed in access logs or browser history.
X-API-Key: pmx_test_5e8f...Rate Limits
API rate limits are enforced based on the tier associated with your API key. Limits are tracked on two dimensions: requests per second and requests per month. Each completed request counts toward the global monthly quota. Separate endpoint-group monthly limits (matched markets, arbitrage, EV) only advance when the response body has success: true.
Usage is returned on responses via headers such as:
X-RateLimit-Limit-Second: 10X-RateLimit-Remaining-Second: 9X-RateLimit-Limit-Month: 1000X-RateLimit-Remaining-Month: 842Example (endpoint-group, when applicable)X-RateLimit-Limit-Arb-Month: 500X-RateLimit-Remaining-Arb-Month: 412If you exceed a rate limit, the API returns a 429 status with a Retry-After header indicating when you can resume.
Request
Live API Key
Parameters
Response
—Click EXECUTE to send a request →