Skip to main content
Returns wallet-position rows for every outcome token in a market condition. Use sort=amount to fetch the largest current holders first across all outcomes in the condition.

​
Request

GET /v3/markets/condition/{condition_id}/positions

​
Path parameters

ParameterTypeDescription
condition_idstringMarket condition ID (0x + 64 hex characters). The response includes positions for every outcome token in this condition.

​
Query parameters

ParameterTypeDefaultDescription
sortstringpnlSort order. One of pnl (realized P&L), amount (current shares held), or volume (total bought).
limitinteger100Rows per page. Requests are capped by API key tier: Starter 300, Growth 1000, Enterprise 2000.
offsetinteger0Number of rows to skip for pagination.
If limit is above your tier cap, PolyNode normalizes it to the maximum allowed value instead of rejecting the request. Every response includes the applied limit, plus rows_returned, offset, and has_more.

​
Sorting

Use sort=amount when you need the largest current holders for a condition. The sort is descending, so the first rows are the wallets with the highest current amount across the condition’s outcome tokens.

​
Example

curl -H "x-api-key: $POLYNODE_API_KEY" \
  "https://api.polynode.dev/v3/markets/condition/0x713641f745d71f6ec61f906237ffca3c8583f251e49384429a63ceb0ccdb2d37/positions?sort=amount&limit=1&offset=0"

​
Example response

{
  "data": [
    {
      "amount": "6660546928621",
      "avg_price": null,
      "realized_pnl": "0",
      "token_id": "1770840559776249239623005379825945674336282130390798724203946923853499387834",
      "total_bought": "0",
      "user": "0xa5ef39c3d3e10d0b270233af41cac69796b12966"
    }
  ],
  "elapsed_ms": 3,
  "has_more": true,
  "limit": 1,
  "offset": 0,
  "rows_returned": 1
}

​
Response columns

ColumnTypeDescription
userstringWallet address (lowercased)
token_idstringOutcome token this row covers (each condition has multiple outcomes; a wallet can appear once per outcome it has touched)
amountstringCurrent shares held in 6-decimal token units (0 if the wallet has exited this outcome)
avg_pricestring | nullAverage entry price in 6-decimal USDC units (500000 = $0.50). May be null when cost basis is not available.
realized_pnlstringRealized P&L on the closed portion of the position in 6-decimal USDC units
total_boughtstringCumulative purchase cost basis in 6-decimal USDC units