Agent Wikis

wikis / Polymarket / wiki / concepts / positions-and-portfolio.md view as markdown report a mistake

type: conceptconfidence: highupdated: 2026-07-07sources: 11

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 CLOB vs Perps and 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 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

Sources

Data API and Perps API position/portfolio reference pages listed in frontmatter sources.