Sign in

v1

latestOpenAPI 3.1.02026-07-243035381.4 MB
Prediction API

Get wallet open positions

/v4/data/prediction/wallets/{address}/positions

100 credits per API call

Current open positions held by a wallet — one row per outcome token, with unrealised PnL, current value, lifetime cost basis, and the parent market's question, slug and outcome metadata. Useful for "what's in my portfolio right now" views and per-market drill-downs.

Platform support

  • Polymarket only. Kalshi wallets return 400.

Filtering, sorting and pagination

  • market scopes the response to a comma-separated list of condition ids (0x + 64 hex), up to 50 entries.
  • eventId scopes the response to a comma-separated list of Polymarket numeric event ids, up to 50 entries. Mutually exclusive with market — passing both returns 400.
  • sizeThreshold filters out positions smaller than the given size. Defaults to 1; pass 0 to include dust.
  • redeemable=true returns positions on resolved markets that the wallet has won but has not yet redeemed. mergeable=true returns positions eligible for merging back to USDC. Both default to false.
  • sortBy accepts CURRENT, INITIAL, TOKENS, CASHPNL, PERCENTPNL, TITLE, RESOLVING, PRICE, AVGPRICE. Defaults to TOKENS. Combine with sortDirection (ASC / DESC, defaults to DESC).
  • title filters by a substring of the market question.
  • Pagination is offset-based — limit (1..500, default 100) and offset (0..10000, default 0).

Other notes

  • address is normalised to lowercase before being echoed in the response (every row's proxyWallet).
  • negativeRisk indicates whether the parent market is part of Polymarket's negative-risk grouping (e.g. multi-candidate winner-take-all markets).
get/v4/data/prediction/wallets/{address}/positions

Path parameters

addressstring required

EVM wallet address — 0x-prefixed, 40 hex characters. Returned lowercased in response payloads. Non-EVM inputs (e.g. Kalshi user identifiers) return 400 from every wallets endpoint.

Example:0x56687bf447db6ffa42ffe2204a05edaa20f55839

Wallet address (0x + 40 hex). Kalshi addresses return 400.

Query parameters

marketstring
Example:0xdd22472e552920b8438158ea7238bfadfa4f736aa4cee91a6b86c39ead110917

Comma-separated list of condition ids (0x + 64 hex) to scope the response to. Up to 50 entries. Mutually exclusive with eventId.

eventIdstring
Example:12345,67890

Comma-separated list of Polymarket numeric event ids to scope the response to. Up to 50 entries. Mutually exclusive with market.

sizeThresholdnumber
Example:1

Minimum position size to include. Defaults to 1; pass 0 to include dust positions.

redeemableboolean

When true, returns positions on resolved markets that the wallet has won but has not yet redeemed. Defaults to false.

mergeableboolean

When true, returns positions eligible for merging back to USDC. Defaults to false.

sortBy'CURRENT' | 'INITIAL' | 'TOKENS' | 'CASHPNL' | 'PERCENTPNL' | 'TITLE' | 'RESOLVING' | 'PRICE' | 'AVGPRICE'

Sort key for /wallets/{address}/positions.

Example:TOKENS

Sort key. Defaults to TOKENS.

sortDirection'ASC' | 'DESC'

Sort direction.

Example:DESC

Sort direction. Defaults to DESC.

titlestring
Example:Mars

Filter rows where the market question contains this substring.

limitinteger
Example:100

Page size. Defaults to 100.

offsetinteger

Page offset. Defaults to 0.

Response

OK

Example response

{
  "data": [
    {
      "proxyWallet": "0x56687bf447db6ffa42ffe2204a05edaa20f55839",
      "asset": "71321045679252212594626385532706912750332728571942612009397583165281712267356",
      "conditionId": "0xdd22472e552920b8438158ea7238bfadfa4f736aa4cee91a6b86c39ead110917",
      "size": 1250,
      "avgPrice": 0.38,
      "initialValue": 475,
      "currentValue": 525,
      "cashPnl": 50,
      "percentPnl": 0.1053,
      "totalBought": 475,
      "curPrice": 0.42,
      "title": "Will Elon Musk land humans on Mars by 2030?",
      "slug": "will-elon-musk-land-humans-on-mars-by-2030",
      "icon": "https://polymarket.com/images/elon-mars.png",
      "eventSlug": "elon-mars-event",
      "outcome": "YES",
      "oppositeOutcome": "NO",
      "oppositeAsset": "52398412765829301823124912398421398214129482198431928421319284213192842131",
      "endDate": "2030-12-31T23:59:59Z"
    }
  ],
  "pagination": {
    "pageSize": 100
  }
}