> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobula.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Prediction Positions

> Get a wallet's prediction market positions with current value and PnL.

<Warning>**Alpha** — This endpoint is part of the Prediction Markets API, currently in early access. May change without notice.</Warning>

### Query Parameters

<ParamField query="wallet" type="string" required>
  The wallet address to get positions for.
</ParamField>

<ParamField query="platforms" type="string">
  Comma-separated list of platforms to filter by.
</ParamField>

<ParamField query="status" type="string">
  Position status filter: `active`, `resolved`, `redeemed`, or `all`. `redeemed` covers positions whose underlying market has resolved AND whose payout has been claimed via [`/api/2/pm/redeem/submit`](/endpoint/pm-redeem-submit) — the outcome tokens are gone but the row stays for PnL/history.
</ParamField>

<ParamField query="sortBy" type="string" default="amountUSD">
  Sort order: `amountUSD`, `totalPnlUSD`, or `createdAt`.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Number of positions to return (1 to 100).
</ParamField>

<ParamField query="offset" type="number" default="0">
  Pagination offset.
</ParamField>

### Response

<ResponseField name="data" type="array">
  Array of wallet positions.

  <Expandable title="Position">
    <ResponseField name="platform" type="string">Platform name.</ResponseField>

    <ResponseField name="market" type="object">
      Market information.

      <Expandable title="Market">
        <ResponseField name="marketId" type="string">Market identifier.</ResponseField>
        <ResponseField name="question" type="string">Market question.</ResponseField>
        <ResponseField name="category" type="string | null">Market category.</ResponseField>
        <ResponseField name="status" type="string">Market status.</ResponseField>
        <ResponseField name="logo" type="string | null">Market logo URL.</ResponseField>
        <ResponseField name="endDate" type="string | null">Market end date (ISO 8601).</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="outcomeId" type="string">Outcome token ID.</ResponseField>
    <ResponseField name="label" type="string">Outcome label.</ResponseField>
    <ResponseField name="balance" type="number">Number of outcome tokens held.</ResponseField>
    <ResponseField name="costBasisUSD" type="number">Total cost basis in USD.</ResponseField>
    <ResponseField name="avgBuyPriceUSD" type="number">Average buy price in USD.</ResponseField>
    <ResponseField name="avgSellPriceUSD" type="number | null">Average sell price in USD.</ResponseField>
    <ResponseField name="priceUSD" type="number">Current outcome price.</ResponseField>
    <ResponseField name="amountUSD" type="number">Current position value in USD.</ResponseField>
    <ResponseField name="unrealizedPnlUSD" type="number">Unrealized profit/loss in USD.</ResponseField>
    <ResponseField name="unrealizedPnlPercent" type="number">Unrealized PnL as percentage.</ResponseField>
    <ResponseField name="realizedPnlUSD" type="number">Realized profit/loss in USD.</ResponseField>
    <ResponseField name="totalPnlUSD" type="number">Total PnL in USD (realized + unrealized).</ResponseField>
    <ResponseField name="totalFeesPaidUSD" type="number | null">Total fees paid in USD.</ResponseField>
    <ResponseField name="buys" type="number | null">Number of buy trades.</ResponseField>
    <ResponseField name="sells" type="number | null">Number of sell trades.</ResponseField>
    <ResponseField name="volumeBuyUSD" type="number | null">Total buy volume in USD.</ResponseField>
    <ResponseField name="volumeSellUSD" type="number | null">Total sell volume in USD.</ResponseField>
    <ResponseField name="firstDate" type="string | null">Timestamp of first trade (ISO 8601).</ResponseField>
    <ResponseField name="lastDate" type="string | null">Timestamp of last trade (ISO 8601).</ResponseField>
    <ResponseField name="labels" type="string[]">Position-specific labels.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="wallet" type="object | null">Wallet metadata (fundingInfo, entity, labels). Null when unavailable.</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata.

  <Expandable title="Pagination">
    <ResponseField name="page" type="number">Current page number.</ResponseField>
    <ResponseField name="offset" type="number">Current offset.</ResponseField>
    <ResponseField name="limit" type="number">Results per page.</ResponseField>
    <ResponseField name="pageEntries" type="number">Number of entries in this page.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="hostname" type="string">Server node identifier.</ResponseField>
<ResponseField name="took" type="number">Request processing time in milliseconds.</ResponseField>

### Usage Example

```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/wallet/pm/positions?wallet=0xYourWalletAddress&status=active"
```

### Example Response

```json theme={null}
{
  "data": [
    {
      "platform": "polymarket",
      "market": {
        "marketId": "0x1234...",
        "question": "Will ETH reach $10,000 by end of 2026?",
        "category": "crypto",
        "status": "active",
        "logo": "https://polymarket.com/images/market.png",
        "endDate": "2026-12-31T23:59:59.000Z"
      },
      "outcomeId": "71321...",
      "label": "Yes",
      "balance": 100,
      "costBasisUSD": 35,
      "avgBuyPriceUSD": 0.35,
      "avgSellPriceUSD": null,
      "priceUSD": 0.42,
      "amountUSD": 42,
      "unrealizedPnlUSD": 7,
      "unrealizedPnlPercent": 20,
      "realizedPnlUSD": 0,
      "totalPnlUSD": 7,
      "totalFeesPaidUSD": 0.12,
      "buys": 2,
      "sells": 0,
      "volumeBuyUSD": 35,
      "volumeSellUSD": 0,
      "firstDate": "2026-02-01T10:00:00.000Z",
      "lastDate": "2026-02-15T14:30:00.000Z",
      "labels": []
    }
  ],
  "wallet": null,
  "pagination": {
    "page": 1,
    "offset": 0,
    "limit": 50,
    "pageEntries": 1
  },
  "hostname": "node-xyz",
  "took": 42
}
```


## OpenAPI

````yaml GET /2/wallet/pm/positions
openapi: 3.0.0
info:
  version: 1.0.0
  title: Mobula Prediction Markets API
  description: >-
    Documentation of the Mobula Prediction Markets API.


    The PM API is currently served from a dedicated host:
    `pm-api-prod-eu.mobula.io`.

    All endpoints below require an API key (same key as the main Mobula API).


    Parameter names below are the **canonical names enforced by the API

    controllers** (Zod-validated). Following the wrong name (e.g. `?market=...`

    instead of `?platform=...&marketId=...`) returns `HTTP 400`.
servers:
  - url: https://pm-api-prod-eu.mobula.io/api/
    description: PM Production API (requires API key)
security: []
tags:
  - name: V2 - PM Market
    description: Prediction market data — details, prices, order book, trades, OHLCV
  - name: V2 - PM Discovery
    description: Search, trending, categories, live markets
  - name: V2 - PM Wallet
    description: Wallet prediction-market positions, balances, PnL, activity, status
paths:
  /2/wallet/pm/positions:
    get:
      tags:
        - V2 - PM Wallet
      summary: Get Prediction Positions
      description: Get a wallet's prediction market positions with current value and PnL.
      parameters:
        - $ref: '#/components/parameters/Wallet'
        - name: platforms
          in: query
          required: false
          description: >-
            Comma-separated platform filter (e.g. `polymarket`). Empty = all
            platforms.
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Filter by position status.
          schema:
            type: string
            enum:
              - active
              - resolved
              - redeemed
              - all
        - name: sortBy
          in: query
          required: false
          schema:
            type: string
            enum:
              - amountUSD
              - totalPnlUSD
              - createdAt
            default: amountUSD
        - name: limit
          in: query
          required: false
          description: Page size (1-100).
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Positions list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
components:
  parameters:
    Wallet:
      name: wallet
      in: query
      required: true
      description: >-
        User EOA wallet address. The API resolves the matching Safe trading
        account internally.
      schema:
        type: string
        example: '0x0000000000000000000000000000000000000001'
    Offset:
      name: offset
      in: query
      required: false
      description: Pagination offset.
      schema:
        type: integer
        minimum: 0
        default: 0

````