Positions API

Positions represent the share holdings of a specific player (under an operator) for an outcome in a market. Positions are updated automatically when trades execute.

Authentication: X-Api-Key header required.

Get Positions

Retrieve all positions for your operator account.

GET /api/v1/positions

Query Parameters:

Parameter	Type	Description
marketId	string	Filter positions by market
playerId	string	Filter positions by player

Example:

curl "https://polymarket.sandbox.playbatman.com/api/v1/positions?marketId=market-uuid&playerId=player-123" \
  -H "X-Api-Key: your-api-key"

Response:

{
  "success": true,
  "data": [
    {
      "id": "position-uuid",
      "marketId": "market-uuid",
      "outcomeId": "outcome-uuid-1",
      "operatorId": "operator-uuid",
      "playerId": "player-123",
      "shares": "150",
      "avgPrice": "0.62",
      "totalCost": "93",
      "realizedPnl": "0",
      "createdAt": "2026-02-18T22:00:00.000Z",
      "updatedAt": "2026-02-18T22:30:00.000Z"
    },
    {
      "id": "position-uuid-2",
      "marketId": "market-uuid",
      "outcomeId": "outcome-uuid-2",
      "operatorId": "operator-uuid",
      "playerId": "player-456",
      "shares": "50",
      "avgPrice": "0.38",
      "totalCost": "19",
      "realizedPnl": "5.20",
      "createdAt": "2026-02-18T22:05:00.000Z",
      "updatedAt": "2026-02-18T22:35:00.000Z"
    }
  ]
}

Position Fields

Field	Type	Description
id	string	Position UUID
marketId	string	Market this position is in
outcomeId	string	Outcome this position is for
operatorId	string	Owning operator
playerId	string	Player identifier
shares	string (decimal)	Current share balance
avgPrice	string (decimal)	Volume-weighted average acquisition price
totalCost	string (decimal)	Total cost basis (shares * avgPrice)
realizedPnl	string (decimal)	Profit/loss from closed trades
createdAt	string (ISO 8601)	When the position was first created
updatedAt	string (ISO 8601)	Last update time

How Positions Work

• A position is created the first time a player's order is matched for a given market outcome
• Positions are scoped to (marketId, outcomeId, operatorId, playerId) — one position per player per outcome
• BUY trades increase shares and update avgPrice
• SELL trades decrease shares and update realizedPnl
• When shares reach 0, the position remains in the database with shares: "0" for PnL tracking
• SELL orders are validated against the player's position — you cannot sell more shares than the player holds