> ## Documentation Index > Fetch the complete documentation index at: https://docs.agg.market/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > To integrate AGG, start with Quickstart: REST (https://docs.agg.market/quickstart/rest), then Order lifecycle & statuses (https://docs.agg.market/concepts/order-lifecycle). > Track every trade until it reaches a terminal status. Before retrying a failed or timed-out call, read Errors, retries & idempotency (https://docs.agg.market/concepts/errors). > The API reference is generated from https://docs.agg.market/openapi/openapi.json. # Get user positions > Open and closed positions for one user of your app. Filter with `venueEventId`, `venueMarketId` and `status`. Positions are reported per venue leg and marked at the user's average entry price — this endpoint does not consult an orderbook, so it returns no live mark or unrealized PnL. Authenticate with an `x-app-api-key` of either scope: a `read` key can read any user of your app, so treat it as a credential over your users' full trading history. ## OpenAPI ````yaml /openapi/openapi.json get /apps/{appId}/users/{userId}/positions openapi: 3.0.2 info: title: AGG API version: 1.0.0 description: >- Prediction market aggregator REST API — authentication, users, venue events, venue markets, orderbooks, charts, and execution workflows. servers: - url: https://api.agg.market description: Production security: [] tags: - name: Authentication description: Sign users in and manage their session tokens. - name: Markets description: Find events, markets and outcomes to trade. - name: Market Data description: Live orderbooks, prices, charts and scores for those markets. - name: Trading description: Quote, place, sign, track and cancel orders. - name: Portfolio description: A user's orders, positions, balances and activity. - name: Funding description: Deposit addresses, withdrawals, balance refills and fiat on-ramp. - name: Users description: The signed-in user's profile, linked accounts, KYC and venue keys. - name: Hosted Venue Accounts description: Provision, fund and withdraw from venue accounts hosted for the user. - name: Webhooks description: Configure and operate webhook delivery to your server. - name: Partner Admin description: Server-side reads across your app's users, orders and analytics. - name: Paper Trading description: Simulated accounts and orders for testing without real funds. - name: News description: News feeds linked to markets. - name: Correlated Markets description: Markets related to a given market and the effect of its resolution. paths: /apps/{appId}/users/{userId}/positions: get: tags: - Partner Admin summary: Get user positions description: >- Open and closed positions for one user of your app. Filter with `venueEventId`, `venueMarketId` and `status`. Positions are reported per venue leg and marked at the user's average entry price — this endpoint does not consult an orderbook, so it returns no live mark or unrealized PnL. Authenticate with an `x-app-api-key` of either scope: a `read` key can read any user of your app, so treat it as a credential over your users' full trading history. operationId: getAppUserPositions parameters: - name: appId in: path required: true schema: type: string - name: userId in: path required: true schema: type: string - name: cursor in: query required: false schema: type: string - name: limit in: query required: false schema: minimum: 1 maximum: 100 type: integer - name: venueEventId in: query required: false schema: type: string - name: venueMarketId in: query required: false schema: type: string - name: status in: query required: false schema: description: '`active`: shares still held. `closed`: fully sold or settled.' type: string enum: - active - closed responses: '200': description: '200' content: application/json: schema: type: object required: - data - nextCursor - hasMore properties: data: description: This page of results. type: array items: $ref: '#/components/schemas/PositionGroup' nextCursor: description: >- Pass as `cursor` to fetch the next page; `null` on the last page. type: string nullable: true hasMore: description: '`true` when another page exists.' type: boolean '401': description: '401' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '403': description: '403' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '404': description: '404' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' security: - appApiKey: [] components: schemas: PositionGroup: type: object required: - targetMarketId - redeemStatus - status - resolutionDate - venueMarket properties: targetMarketId: description: Market id that represents this group; also the pagination cursor. type: string eventId: description: Event id. Paper positions only. type: string redeemStatus: description: >- Whether winnings can be claimed. `eligible`: the outcome won and shares can be redeemed with POST /execution/redeem. `pending`: a redemption is in progress. `redeemed`: already claimed or settled. `ineligible`: nothing to claim through AGG; the outcome lost, the venue settles on its own, or the position is self-custody and is claimed on the venue. type: string enum: - eligible - pending - redeemed - ineligible status: description: '`active`: shares still held. `closed`: fully sold or settled.' type: string enum: - active - closed resolutionDate: description: ISO-8601. Earliest resolution date across the group's markets. type: string nullable: true venueMarket: description: The market, and the user's position in each of its outcomes. type: object required: - venueEventId - question - image - status - venueMarketOutcomes properties: venueEventId: description: Event id. type: string question: description: Market question. type: string image: description: Image URL. type: string nullable: true status: description: Market status. type: string enum: - open - closed - resolved - unopened - paused venueMarketOutcomes: description: One entry per outcome the user holds. type: array items: type: object required: - label - title - venueBreakdown - totalSize - avgEntryPrice - currentPrice - totalValue - unrealizedPnl - unrealizedPnlPercent - winner - priceSource - bookQuality properties: label: description: Outcome label, e.g. "Yes". type: string title: description: Longer outcome title, when the market has one. type: string nullable: true venueBreakdown: description: The legs that make up this position, one per venue. type: array items: type: object required: - venue - venueMarketId - size properties: executionBackend: description: >- ProphetX only. `direct`: held in the user's own ProphetX account. `clearinghouse`: held through AGG's ProphetX account. type: string enum: - clearinghouse - direct venue: allOf: - $ref: '#/components/schemas/Venue' description: Venue this leg is on. venueMarketId: description: Market id on that venue. type: string venueMarketOutcomeId: description: Outcome id on that venue. type: string nullable: true size: description: Shares held on this venue, as a float. type: number custodyKind: $ref: '#/components/schemas/PositionCustody' venueAccountId: description: AGG id of the venue account holding the shares. type: string externalAccountId: description: The venue's own identifier for that account. type: string totalSize: description: Shares held across all venues, as a float. type: number avgEntryPrice: description: >- Average entry price, 0 to 1, weighted by size over the legs with a known entry. It is 0 when no leg has a known entry; check `costBasisUnknown` first. type: number costBasisUnknown: description: >- Present and `true` when some shares have no known entry price. `totalValue` covers every leg; `avgEntryPrice`, `unrealizedPnl` and `unrealizedPnlPercent` cover only the legs with a known entry. type: boolean currentPrice: description: >- Current price, 0 to 1, weighted by size across legs. After resolution, the payout per share. type: number totalValue: description: >- Market value of every leg (negative for short legs). USD, as a float. type: number unrealizedPnl: description: >- Value minus cost over the legs with a known entry. USD, as a float. type: number unrealizedPnlPercent: description: '`unrealizedPnl` as a percentage of cost (12.5 = 12.5%).' type: number winner: description: >- Whether this outcome won; `null` until the market resolves. type: boolean nullable: true priceSource: $ref: '#/components/schemas/PriceSource' bookQuality: $ref: '#/components/schemas/BookQuality' ErrorMessage: type: object required: - message properties: message: type: string Venue: type: string enum: - kalshi - polymarket - limitless - opinion - predict - pred - tiprun - probable - myriad - hyperliquid - novig - prophetx - betdex PositionCustody: description: >- Where the shares are held: `EOA` the user's own wallet, `DEPOSIT_WALLET` the user's Polymarket deposit wallet, `VENUE_OMNIBUS` a shared account at the venue, `VENUE_ACCOUNT` the user's own account at the venue. type: string enum: - EOA - DEPOSIT_WALLET - VENUE_OMNIBUS - VENUE_ACCOUNT PriceSource: description: >- Where the current price came from. `orderbook`: the live book. `settled`: the market resolved, so the price is the payout (1 or 0). `cached`: a recent stored price, used when the live book was unavailable. `entry`: no price was available, so the entry price is used and P&L is not meaningful. On totals, the worst source across legs. type: string enum: - orderbook - cached - entry - settled BookQuality: description: >- How trustworthy the order book behind a price is. `healthy`: two-sided with a normal spread. `wide_spread`: two-sided but the spread is wide, so the midpoint overstates what you could sell for. `bid_only` / `ask_only`: one side of the book is empty. `endpoint_stub`: only placeholder quotes at the price bounds. `crossed`: best bid is at or above best ask. `empty`: no book (also reported for settled positions, which need none). type: string enum: - healthy - bid_only - ask_only - endpoint_stub - wide_spread - crossed - empty securitySchemes: appApiKey: type: apiKey in: header name: x-app-api-key description: App-scoped API key for programmatic app management. ````