--- title: "Positions and Portfolio" type: concept tags: [positions, portfolio, pnl, balances, holders, open-interest, data-api, perps-api] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/llms_txt_doc-get-current-positions-for-a-user.md", "raw/llms_txt_doc-get-closed-positions-for-a-user.md", "raw/llms_txt_doc-get-positions-for-a-market.md", "raw/llms_txt_doc-get-portfolio.md", "raw/llms_txt_doc-get-public-portfolio.md", "raw/llms_txt_doc-get-pnl.md", "raw/llms_txt_doc-get-equity.md", "raw/llms_txt_doc-get-balances.md", "raw/llms_txt_doc-get-total-value-of-a-user-s-positions.md", "raw/llms_txt_doc-get-top-holders-for-markets.md", "raw/llms_txt_doc-get-open-interest.md"] confidence: high --- ## Two Position Systems Polymarket exposes positions through two distinct APIs. The **Data API** (`https://data-api.polymarket.com`) reports prediction-market (CLOB) positions keyed by condition ID and outcome token, and is mostly public (queried by wallet address). The **Perps API** (`https://api.perpetuals.polymarket.com`) reports perpetual-futures positions with margin, leverage, and liquidation, and its account routes require authentication. The two are not interchangeable; see [[syntheses/clob-vs-perps|CLOB vs Perps]] and [[concepts/perps-trading|Perps Trading]]. ## Prediction-Market Positions (Data API) `GET /positions` (current positions for a user). Query: `user` (required, `0x`-prefixed 40-hex address), `market` (comma-separated condition IDs, mutually exclusive with `eventId`), `eventId` (comma-separated event IDs, mutually exclusive with `market`), `sizeThreshold` (default 1), `redeemable` (default false), `mergeable` (default false), `limit` (default 100, max 500), `offset` (max 10000), `sortBy` (`CURRENT`, `INITIAL`, `TOKENS`, `CASHPNL`, `PERCENTPNL`, `TITLE`, `RESOLVING`, `PRICE`, `AVGPRICE`; default `TOKENS`), `sortDirection` (`ASC`/`DESC`, default `DESC`), `title` (max 100). Returns an array of `Position`: `proxyWallet`, `asset`, `conditionId`, `size`, `avgPrice`, `initialValue`, `currentValue`, `cashPnl`, `percentPnl`, `totalBought`, `realizedPnl`, `percentRealizedPnl`, `curPrice`, `redeemable`, `mergeable`, `title`, `slug`, `icon`, `eventSlug`, `outcome`, `outcomeIndex`, `oppositeOutcome`, `oppositeAsset`, `endDate`, `negativeRisk`. `GET /closed-positions` (settled/exited positions). Same `user`/`market`/`eventId`/`title` filters; `limit` default 10 (max 50), `offset` max 100000, `sortBy` (`REALIZEDPNL`, `TITLE`, `PRICE`, `AVGPRICE`, `TIMESTAMP`; default `REALIZEDPNL`). Each `ClosedPosition`: `proxyWallet`, `asset`, `conditionId`, `avgPrice`, `totalBought`, `realizedPnl`, `curPrice`, `timestamp`, `title`, `slug`, `icon`, `eventSlug`, `outcome`, `outcomeIndex`, `oppositeOutcome`, `oppositeAsset`, `endDate`. `GET /v1/market-positions` (all holders' positions for one market). Query: `market` (required condition ID), `user` (optional single wallet), `status` (`OPEN` = size > 0.01, `CLOSED` = size <= 0.01, `ALL`; default `ALL`), `sortBy` (`TOKENS`, `CASH_PNL`, `REALIZED_PNL`, `TOTAL_PNL`; default `TOTAL_PNL`), `sortDirection`, `limit` (default 50, max 500), `offset`. Returns `MetaMarketPositionV1` objects `{token, positions}` where each `MarketPositionV1` adds profile fields (`name`, `profileImage`, `verified`) plus `avgPrice`, `size`, `currPrice`, `currentValue`, `cashPnl`, `totalBought`, `realizedPnl`, `totalPnl`, `outcome`, `outcomeIndex`. ## Aggregate Value, Holders, Open Interest (Data API) - `GET /value` - total value of a user's positions. Query `user` (required), `market` (comma-separated condition IDs). Returns array of `Value` `{user, value}`. - `GET /holders` - top holders for markets. Query `limit` (default 20, **max 20**), `market` (required, comma-separated condition IDs), `minBalance` (default 1, max 999999). Returns array of `MetaHolder` `{token, holders}`; each `Holder`: `proxyWallet`, `bio`, `asset`, `pseudonym`, `amount`, `displayUsernamePublic`, `outcomeIndex`, `name`, `profileImage`, `profileImageOptimized`. - `GET /oi` - open interest. Query `market` (comma-separated condition IDs). Returns array of `OpenInterest` `{market, value}`. ## Perps Portfolio, PnL, Equity, Balances These live on the Perps API. Account routes authenticate with the `POLYMARKET-PROXY` (proxy address) and `POLYMARKET-SECRET` (proxy secret) headers; see [[concepts/authentication|Authentication]]. `GET /v1/account/portfolio` (`getPortfolio`, Request Weight 2, authenticated) - current portfolio snapshot. Returns `Portfolio` `{positions, margin, withdrawable, in_liquidation, timestamp}`. Each `PortfolioPosition`: `instrument_id`, `symbol` (e.g. `NVDA-USDC`), `size` (signed contracts; positive = long, negative = short), `entry_price`, `leverage`, `cross`, `initial_margin`, `maintenance_margin`, `position_value`, `liquidation_price`, `unrealized_pnl`, `return_on_equity`, `cumulative_funding`. `MarginSummary`: `total_account_value`, `total_initial_margin`, `total_maintenance_margin`, `total_position_value`. `withdrawable` is the withdrawable USD balance; `in_liquidation` flags liquidation; `timestamp` is milliseconds. `GET /v1/info/portfolio` (`getPublicPortfolio`, Request Weight 5, public) - query `address` (required). Returns `PublicPortfolio` `{positions, equity, timestamp}`; each `PublicPortfolioPosition` is the reduced set `instrument_id`, `symbol`, `size`, `entry_price`, `unrealized_pnl`, `return_on_equity`. `GET /v1/account/pnl` (`getPnlHistory`, Request Weight 10, authenticated) - `interval` (required; `1h`, `4h`, `1d`, `1w`), `start_timestamp` (required, ms), `end_timestamp` (optional; defaults to now). Returns `PnlHistory` `{data, more}` where `data` is an array of `[timestamp, pnl]` pairs (pnl as a string, e.g. `"100.50"`), max 1000 entries; `more` signals additional data. `GET /v1/account/equity` (`getEquityHistory`, authenticated) - `interval` (required; `1s`, `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `6h`, `12h`, `1d`, `1w`), `start_timestamp` (required), `end_timestamp` (optional). Returns `EquityHistory` `{data, more}`, `data` an array of `[timestamp, equity]` pairs, max 1000. `GET /v1/account/balances` (`getBalances`, authenticated) - returns an array of `Balance` `{asset, balance, value}` where `value` is the USD value. ## Notes and Pitfalls - Data API `market` and `eventId` filters are mutually exclusive on `/positions`, `/closed-positions`, and `/activity`. - The `/holders` `limit` caps at 20, unlike other list endpoints. - Perps `size` is signed; a negative value is a short. PnL and equity timestamps are Unix milliseconds; values are returned as strings. - Realized profit-and-loss is exposed on both closed prediction positions (`realizedPnl`) and perps history (`/v1/account/pnl`). ## Related Concepts - [[concepts/trades-and-activity|Trades and Activity]] - [[concepts/markets-and-events|Markets and Events]] - [[concepts/perps-trading|Perps Trading]] - [[syntheses/clob-vs-perps|CLOB vs Perps]] ## Sources Data API and Perps API position/portfolio reference pages listed in frontmatter `sources`.