Prediction Hunt

↑ ↓ move · Enter open · Esc close

API docs
REST API / Polymarket / Wallet Positions

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.

GET/v2/wallet/{addr}/positions
Plans All plansPlan rate limits apply

Parameters

addrstring (path)required

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).

limitinteger

Optional. Page size, default 100, max 200.

offsetinteger

Optional. Page offset, default 0. Use offset += limit to walk pages.

Response

walletstring

Wallet address (lowercased).

limitinteger

Page size returned (max 200).

offsetinteger

Page offset.

countinteger

Number of positions returned in this page.

has_moreboolean

True when count == limit, indicating another page may exist. Use offset += limit to fetch the next page.

positionsarray

Per-position rows. Realized vs unrealized PnL is split explicitly - see _meta.field_definitions for exact semantics.

Show 20 fields
proxy_walletstring

Polymarket proxy wallet.

condition_idstring

Market condition ID.

assetstring

Outcome token ID (CTF ERC-1155).

outcomestring

Human outcome label (e.g. "Yes").

outcome_indexinteger

Outcome index in the market.

sizenumber

Open share count.

avg_pricenumber

VWAP entry price across all fills for the open size.

cost_basisnumber

USDC paid to acquire the open size (avg_price * size). Excludes already-realized portions and excludes taker fees.

mark_pricenumber

Current mid-market price used to mark the open position.

current_valuenumber

mark_price * size - paper value of the open position.

realized_pnlnumber

PnL locked in from sells/redemptions/conversions. Already net of taker fees Polymarket charged at fill time. Will not change as the market moves.

unrealized_pnlnumber

Mark-to-market PnL on the open size only. Moves tick-by-tick. Pre-fee - fees would only be incurred on eventual close.

total_pnlnumber

realized_pnl + unrealized_pnl.

percent_pnlnumber

Percentage return on the position.

redeemableboolean

Market resolved and the position can be redeemed for USDC.

negative_riskboolean

NegRisk (multi-outcome) market flag.

titlestring

Market title (display).

slugstring

Market slug.

iconstring

Market icon URL.

event_slugstring

Parent event slug.

_metaobject

Source, cache, and authoritative field definitions.

Show 4 fields
sourcestring

Data source identifier.

cache_secondsinteger

Cache window in seconds.

field_definitionsobject

Per-field semantic definitions for realized_pnl, unrealized_pnl, total_pnl, mark_price, cost_basis.

fees_notestring

How taker fees are reflected in the PnL fields.

Full API response