Wallet Positions

Get all positions for a wallet with market context, current prices, unrealized P&L, and settlement status.

Returns every position a wallet has ever held, enriched with market metadata, live token prices, computed unrealized P&L, settlement status, and redemption data. All amounts are in USD.

Owner addresses. Pass an owner EOA as the wallet address and the response combines the EOA’s Polymarket wallets (Safe, proxy, deposit wallets) that have data for this endpoint. Passing a Safe, proxy or deposit wallet returns just that wallet, as before. Combined responses list the combined wallets in wallets. See Owner addresses.

​

Request

GET /v3/wallets/{address}/positions

​

Path parameters

Parameter	Type	Description
address	string	Wallet address or owner EOA (0x-prefixed, case-insensitive)

​

Query parameters

Parameter	Type	Default	Description
status	string	all	Filter: open, closed, redeemable, redeemed
sort	string	realized_pnl	Sort by: realized_pnl (default), amount (current shares), volume / total_bought, avg_price, recent (last trade time)
order	string	desc	Sort direction: asc or desc
condition_id	string	—	Filter by market condition ID
market_slug	string	—	Filter by market slug
min_size	number	—	Minimum position size in USD (e.g. min_size=10.0)
include_combos	boolean	false	Append combo positions to the response. Combo rows have position_type: "combo" and include legs metadata.
limit	integer	100	Results per page (max 300)
offset	integer	0	Pagination offset

​

Position statuses

Wallet and global position endpoints use lifecycle statuses:

Status	Meaning
open	Wallet holds shares in an active (unresolved) market
closed	Position fully sold before market resolved
redeemable	Market resolved, wallet still holds shares that can be redeemed
redeemed	Market resolved and shares have been redeemed

Market-scoped holder endpoints may use open/closed differently when explicitly documented as holder-state filters: open means the current balance is nonzero, and closed means the current balance is zero.

​

Examples

​

All positions

curl https://api.polynode.dev/v3/wallets/0xa9857c7bcb9bcfafd2c132ab053f34f678610058/positions?limit=1

{
  "address": "0xa9857c7bcb9bcfafd2c132ab053f34f678610058",
  "positions": [
    {
      "token_id": "56311531524793560667677947517355066819344622894461317832902534277368408457717",
      "size": 0.003332,
      "avg_price": 0.479999,
      "realized_pnl": 0.083202,
      "unrealized_pnl": 0.0,
      "total_pnl": 0.083202,
      "current_price": 0.0,
      "total_bought": 2.083332,
      "initial_value": 0.001599,
      "redeemable_payout": 0.0,
      "resolved": true,
      "price_source": "settlement",
      "status": "redeemable",
      "market": "Bitcoin Up or Down - May 13, 6:55AM-7:00AM ET",
      "slug": "btc-updown-5m-1778669700",
      "outcome": "Down",
      "outcome_index": 1,
      "opposite_asset": "75458928898922591833639657019011228747535375591777673334858165385124723756977",
      "image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/BTC+fullsize.png",
      "condition_id": "0xa1118bf183058190b9b47529d94eed53d0210c65531990019c09b893cb64b73b",
      "event_slug": "btc-updown-5m-1778669700",
      "neg_risk": false,
      "market_status": "live",
      "tag_slugs": ["Hide From New", "Recurring", "Up or Down", "Crypto Prices", "Crypto", "Bitcoin", "5M"],
      "last_trade_at": "1778670064",
      "resolved_at": "0",
      "winning_outcome_index": null,
      "won": null
    }
  ],
  "rows_returned": 1,
  "has_more": true,
  "offset": 0,
  "limit": 1,
  "elapsed_ms": 45
}

​

Only open positions

curl https://api.polynode.dev/v3/wallets/0x.../positions?status=open

​

Only redeemable (resolved but not yet claimed)

curl https://api.polynode.dev/v3/wallets/0x.../positions?status=redeemable

The redeemable_payout field shows the exact USD amount the wallet can claim.

​

Sort by most recent trade

curl "https://api.polynode.dev/v3/wallets/0x.../positions?sort=recent"

​

Sort by current position size

curl "https://api.polynode.dev/v3/wallets/0x.../positions?sort=amount"

​

Include combo positions

curl "https://api.polynode.dev/v3/wallets/0x63613e3b96f418332d43cd2af8dc321014d15907/positions?include_combos=true&limit=2"

When combo rows are present, they are appended with position_type: "combo" and a combo-specific field set:

{
  "position_type": "combo",
  "combo_condition_id": "0x030002fa8781d9f445d838e60524d70bf30000000000000000000000000000",
  "combo_position_id": "1356959103499736670017337806334234879289930581423500836189165811753797287936",
  "shares_balance": "0.000100",
  "entry_avg_price_usdc": "0.2285",
  "entry_cost_usdc": "0.00",
  "realized_pnl_usdc": "0.000000",
  "total_pnl_usdc": "0.000000",
  "status": "open",
  "legs": [
    {
      "leg_index": 0,
      "leg_position_id": "943244391856361009754982642766252708422485833075867696330382296106234020352",
      "leg_outcome_label": "Yes",
      "leg_status": "OPEN"
    }
  ]
}

​

Response fields

​

Top-level combo fields

Field	Type	Description
include_combos	boolean	Present when include_combos=true was requested
included_position_types	array	Includes market and combo when combo inclusion was requested
combo_position_count	integer	Number of combo position rows returned in this page

​

Position data

Field	Type	Description
token_id	string	Outcome token ID
size	number	Current shares held in USD (0 if closed/redeemed)
avg_price	number	Weighted-average entry price in USD
realized_pnl	number	Realized P&L from closed trades (USD)
unrealized_pnl	number	Paper P&L: (current_price - avg_price) * size
total_pnl	number	realized_pnl + unrealized_pnl
current_price	number	Latest token price (USD, from settlement, CLOB mid, or last fill)
total_bought	number	Total USD spent buying this position
initial_value	number	avg_price * size at current holdings
redeemable_payout	number	USD claimable if redeemed now (0 for losing outcomes)
resolved	boolean	Whether the market has settled
price_source	string	Price source: settlement, clob_mid, v1_condition, last_fill
status	string	open, closed, redeemable, or redeemed

​

Market context

Field	Type	Description
market	string	Market question text
slug	string	Market URL slug
outcome	string	Outcome label (e.g. “Yes”, “No”, “Trump”)
outcome_index	integer	Outcome position (0 or 1)
opposite_asset	string	Token ID of the other outcome in this market
image	string	Market image URL
condition_id	string	Market condition ID
event_slug	string	Parent event slug
neg_risk	boolean	Whether this is a neg-risk (multi-outcome) market
market_status	string	live, closed, resolved-win, or resolved-loss
tag_slugs	array	Category tags for this market

​

Timestamps and resolution

Field	Type	Description
last_trade_at	string	Unix timestamp of the most recent fill for this token
resolved_at	string	Unix timestamp when the market was resolved
winning_outcome_index	integer	Which outcome won (0 or 1), null if unresolved
won	boolean	Whether this position’s outcome won, null if unresolved

​

Owner address fields

Present only when you pass an owner EOA. See Owner addresses.

Field	Type	Description
wallets	array	The combined wallets, in a fixed order, each {wallet, type} with type one of eoa, safe, proxy, or deposit_wallet
positions[].wallet	string	The wallet this row belongs to

Positions are never merged across wallets. When two of the owner’s wallets hold the same token, each has its own row, so key rows by wallet and token_id. Combo rows from include_combos=true also carry wallet.

​

Use cases

• Portfolio dashboard — show a trader’s open positions with live P&L and market context
• Redemption alerts — find wallets with unclaimed payouts using ?status=redeemable
• Performance analysis — sort by P&L to see best and worst positions
• Copy trading — see what a wallet is currently holding with ?status=open&sort=amount