> ## 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 Market Trades

> Get trade history for a prediction market, with optional outcome and time filters.

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

### Query Parameters

<ParamField query="platform" type="string" required>
  The prediction market platform (e.g., `polymarket`).
</ParamField>

At least one of `marketId` or `outcomeId` must be provided.

<ParamField query="marketId" type="string">
  The platform-specific market identifier (Polymarket `conditionId` hex).
  Optional when `outcomeId` is provided.
</ParamField>

<ParamField query="outcomeId" type="string">
  Outcome token ID. When provided alone, returns trades for this outcome across
  all markets. When provided with `marketId`, filters trades to this outcome
  within that market.
</ParamField>

<ParamField query="from" type="string | number">
  Start time. Accepts Unix timestamp in **milliseconds** (e.g., `1709913600000`) or ISO 8601 string (e.g., `2024-03-01T00:00:00Z`).
</ParamField>

<ParamField query="to" type="string | number">
  End time. Accepts Unix timestamp in **milliseconds** (e.g., `1709913600000`) or ISO 8601 string (e.g., `2024-03-01T00:00:00Z`).
</ParamField>

<ParamField query="minAmountUSD" type="number" default="0">
  Minimum trade value in USD. Filters out trades below this threshold.
</ParamField>

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

<ParamField query="offset" type="number" default="0">
  Pagination offset. Ignored when `cursor` is provided.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor for keyset pagination. Use the `nextCursor` value from a previous response to fetch the next page. Takes precedence over `offset`.
</ParamField>

<ParamField query="sortOrder" type="string" default="desc">
  Sort direction for trades by date. Possible values: `asc`, `desc`.
</ParamField>

### Response

<ResponseField name="data" type="array">
  Array of trade records.

  <Expandable title="Trade Record">
    <ResponseField name="id" type="string">Trade ID.</ResponseField>
    <ResponseField name="marketId" type="string">Market identifier.</ResponseField>
    <ResponseField name="outcomeId" type="string">Outcome token ID.</ResponseField>
    <ResponseField name="platform" type="string">Platform name.</ResponseField>
    <ResponseField name="type" type="string">Trade type: `buy` or `sell`.</ResponseField>
    <ResponseField name="priceUSD" type="number">Execution price (0 to 1).</ResponseField>
    <ResponseField name="sizeToken" type="number">Trade size in tokens.</ResponseField>
    <ResponseField name="amountUSD" type="number">Trade value in USD.</ResponseField>
    <ResponseField name="date" type="number">Trade timestamp in milliseconds.</ResponseField>
    <ResponseField name="swapRecipient" type="string | null">Trader proxy wallet address. Available for backfilled trades, null for real-time trades.</ResponseField>
    <ResponseField name="transactionHash" type="string | null">Transaction hash. Available for backfilled trades, null for real-time trades.</ResponseField>
  </Expandable>
</ResponseField>

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

  <Expandable title="Pagination">
    <ResponseField name="page" type="number">Current page number (1-based).</ResponseField>
    <ResponseField name="offset" type="number">Current offset.</ResponseField>
    <ResponseField name="limit" type="number">Requested page size.</ResponseField>
    <ResponseField name="pageEntries" type="number">Number of entries returned in this page.</ResponseField>
    <ResponseField name="totalCount" type="number">Total number of matching trades.</ResponseField>
    <ResponseField name="hasMore" type="boolean">Whether more trades are available.</ResponseField>
    <ResponseField name="nextCursor" type="string | null">Cursor for the next page. Null when no more results. Use this value as the `cursor` query parameter to fetch the next page.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="hostname" type="string">Server hostname that handled the request.</ResponseField>
<ResponseField name="took" type="number">Request processing time in milliseconds.</ResponseField>

### Usage Examples

#### Offset-based pagination

```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/pm/market/trades?platform=polymarket&marketId=0x1234...&limit=20&minAmountUSD=100"
```

#### Cursor-based pagination

```bash theme={null}
# First page
curl -X GET "https://api.mobula.io/api/2/pm/market/trades?platform=polymarket&marketId=0x1234...&limit=50"

# Next page (use nextCursor from previous response)
curl -X GET "https://api.mobula.io/api/2/pm/market/trades?platform=polymarket&marketId=0x1234...&limit=50&cursor=1709913600000:trade-001"
```

#### With ISO date range

```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/pm/market/trades?platform=polymarket&marketId=0x1234...&from=2024-03-01T00:00:00Z&to=2024-03-08T00:00:00Z&sortOrder=asc"
```

### Example Response

```json theme={null}
{
  "data": [
    {
      "id": "trade-001",
      "marketId": "0x1234...",
      "outcomeId": "71321...",
      "platform": "polymarket",
      "type": "buy",
      "priceUSD": 0.35,
      "sizeToken": 1000,
      "amountUSD": 350,
      "date": 1709913600000,
      "swapRecipient": "0xabc...",
      "transactionHash": "0xdef..."
    }
  ],
  "pagination": {
    "page": 1,
    "offset": 0,
    "limit": 50,
    "pageEntries": 1,
    "totalCount": 1,
    "hasMore": false,
    "nextCursor": null
  },
  "hostname": "node-xyz",
  "took": 42
}
```


## OpenAPI

````yaml GET /2/pm/market/trades
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/pm/market/trades:
    get:
      tags:
        - V2 - PM Market
      summary: Get Prediction Market Trades
      description: >
        Get trade history for a prediction market, with optional outcome and
        time filters.


        Required: `platform` + **one of** (`marketId`, `outcomeId`). Pagination
        uses

        an opaque `cursor` returned in `pagination.nextCursor`.


        ⚠️ `from` and `to` are in **Unix milliseconds**.
      parameters:
        - $ref: '#/components/parameters/Platform'
        - name: marketId
          in: query
          required: false
          description: CTF conditionId (required if `outcomeId` is not provided).
          schema:
            type: string
        - name: outcomeId
          in: query
          required: false
          description: Outcome token id (required if `marketId` is not provided).
          schema:
            type: string
        - name: from
          in: query
          required: false
          description: Start time in **Unix milliseconds**.
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: to
          in: query
          required: false
          description: End time in **Unix milliseconds**.
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: minAmountUSD
          in: query
          required: false
          description: Minimum trade size in USD.
          schema:
            type: number
            minimum: 0
            default: 0
        - name: limit
          in: query
          required: false
          description: Page size (1-500).
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 50
        - name: cursor
          in: query
          required: false
          description: >-
            Opaque cursor returned by the previous page
            (`pagination.nextCursor`).
          schema:
            type: string
      responses:
        '200':
          description: Trades list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
components:
  parameters:
    Platform:
      name: platform
      in: query
      required: true
      description: >-
        Prediction market platform. Today only `polymarket` is supported; any
        other value returns 400.
      schema:
        type: string
        enum:
          - polymarket
        example: polymarket

````