Wallet Positions - PolyNode

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.

Request

GET /v3/wallets/{address}/positions

Path parameters

Parameter	Type	Description
`address`	string	Wallet address (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

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

​Request

​Path parameters

​Query parameters

​Position statuses

​Examples

​All positions

​Only open positions

​Only redeemable (resolved but not yet claimed)

​Sort by most recent trade

​Sort by current position size

​Include combo positions

​Response fields

​Top-level combo fields

​Position data

​Market context

​Timestamps and resolution

​Use cases