Skip to main content
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

ParameterTypeDescription
addressstringWallet address (0x-prefixed, case-insensitive)

​
Query parameters

ParameterTypeDefaultDescription
statusstringallFilter: open, closed, redeemable, redeemed
sortstringrealized_pnlSort by: realized_pnl (default), amount (current shares), volume / total_bought, avg_price, recent (last trade time)
orderstringdescSort direction: asc or desc
condition_idstring—Filter by market condition ID
market_slugstring—Filter by market slug
min_sizenumber—Minimum position size in USD (e.g. min_size=10.0)
include_combosbooleanfalseAppend combo positions to the response. Combo rows have position_type: "combo" and include legs metadata.
limitinteger100Results per page (max 300)
offsetinteger0Pagination offset

​
Position statuses

Wallet and global position endpoints use lifecycle statuses:
StatusMeaning
openWallet holds shares in an active (unresolved) market
closedPosition fully sold before market resolved
redeemableMarket resolved, wallet still holds shares that can be redeemed
redeemedMarket 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

FieldTypeDescription
include_combosbooleanPresent when include_combos=true was requested
included_position_typesarrayIncludes market and combo when combo inclusion was requested
combo_position_countintegerNumber of combo position rows returned in this page

​
Position data

FieldTypeDescription
token_idstringOutcome token ID
sizenumberCurrent shares held in USD (0 if closed/redeemed)
avg_pricenumberWeighted-average entry price in USD
realized_pnlnumberRealized P&L from closed trades (USD)
unrealized_pnlnumberPaper P&L: (current_price - avg_price) * size
total_pnlnumberrealized_pnl + unrealized_pnl
current_pricenumberLatest token price (USD, from settlement, CLOB mid, or last fill)
total_boughtnumberTotal USD spent buying this position
initial_valuenumberavg_price * size at current holdings
redeemable_payoutnumberUSD claimable if redeemed now (0 for losing outcomes)
resolvedbooleanWhether the market has settled
price_sourcestringPrice source: settlement, clob_mid, v1_condition, last_fill
statusstringopen, closed, redeemable, or redeemed

​
Market context

FieldTypeDescription
marketstringMarket question text
slugstringMarket URL slug
outcomestringOutcome label (e.g. “Yes”, “No”, “Trump”)
outcome_indexintegerOutcome position (0 or 1)
opposite_assetstringToken ID of the other outcome in this market
imagestringMarket image URL
condition_idstringMarket condition ID
event_slugstringParent event slug
neg_riskbooleanWhether this is a neg-risk (multi-outcome) market
market_statusstringlive, closed, resolved-win, or resolved-loss
tag_slugsarrayCategory tags for this market

​
Timestamps and resolution

FieldTypeDescription
last_trade_atstringUnix timestamp of the most recent fill for this token
resolved_atstringUnix timestamp when the market was resolved
winning_outcome_indexintegerWhich outcome won (0 or 1), null if unresolved
wonbooleanWhether 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