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

# predictionTrades

> Returns prediction trades with cursor-based pagination.

<Info>
  **Prediction Market data is currently in beta**. It is actively being worked on and improved, but may be unreliable. Polymarket and Kalshi data are live.

  At least for the time being, this endpoint requires a Growth or Enterprise plan. [Learn more](https://dashboard.codex.io/dashboard/billing?utm_source=codex\&utm_medium=docs\&utm_campaign=billing).
</Info>

<Info>
  **Kalshi has limited trade data**. When querying Kalshi trades:

  * **No `traderId` filtering**: Individual trader information is not exposed
  * **No BUY/SELL distinction**: All trades show as `TRADE` type (no direction information)
  * **No trader identity**: The `maker` and `traderId` fields will be null or unavailable

  These limitations are due to privacy considerations on Kalshi's CFTC-regulated exchange.
</Info>

<div data-generated>
  ## GraphQL

  ```
  type Query {
    # Requires a Growth or Enterprise plan.
    predictionTrades(
      input: PredictionTradesInput!
    ): PredictionTradesConnection
  }

  enum PredictionProtocol {
    POLYMARKET
    KALSHI
  }

  enum PredictionTradeType {
    TRADE
    BUY
    SELL
    BUY_COUNTERPARTY
    SELL_COUNTERPARTY
    POSITION_REDEEMED
  }

  type PredictionResolution {
    result: String
    source: String
  }

  type PredictionSubSubcategory {
    name: String!
    slug: String!
  }

  type PredictionSubcategory {
    name: String!
    slug: String!
    subcategories: [PredictionSubSubcategory!]
  }

  type PredictionCategory {
    name: String!
    slug: String!
    subcategories: [PredictionSubcategory!]
  }

  enum PredictionMetadataType {
    SPORTS
  }

  type SportsTeam {
    abbreviation: String!
    altAbbreviations: [String!]
    name: String
    league: String
    logo: String
    alias: String
    color: String
    providerId: Int
    isHome: Boolean
  }

  enum SportsTimezone {
    UTC
  }

  type SportsMarketEnrichedMetadata {
    sportsMarketType: String
    league: String
    teams: [SportsTeam!]
    gameStartDate: String
    gameStartTime: String
    gameStartTimeSeconds: Int
    gameStartTimezone: SportsTimezone
  }

  type PredictionMarketEnrichedMetadata {
    metadataType: PredictionMetadataType!
    sports: SportsMarketEnrichedMetadata
  }

  type PredictionMarket {
    id: String!
    protocol: PredictionProtocol!
    venueMarketId: String!
    venueMarketSlug: String
    eventId: String
    venueEventId: String
    question: String
    label: String
    suggestedLabel: String
    eventLabel: String
    rules: String
    rules2: String
    venueOutcomeIds: [String!]!
    outcomeIds: [String!]!
    outcomeLabels: [String!]
    resolution: PredictionResolution
    imageLargeUrl: String
    imageThumbUrl: String
    imageSmallUrl: String
    createdAt: Int
    updatedAt: Int
    opensAt: Int
    closesAt: Int
    resolvesAt: Int
    resolvedAt: Int
    observedAt: Int!
    networkId: Int
    exchangeAddress: String
    categories: [PredictionCategory!]
    winningOutcomeId: String
    enrichedMetadata: PredictionMarketEnrichedMetadata
  }

  type PredictionTrade {
    marketId: String!
    sortKey: String!
    outcomeId: String!
    outcomeLabel: String!
    protocol: PredictionProtocol!
    tradeType: PredictionTradeType!
    maker: String
    timestamp: Int!
    outcomeIndex: Int
    priceUsd: String
    priceCollateral: String
    amount: String
    amountCollateral: String
    amountUsd: String
    transactionHash: String
    blockNumber: Int
    networkId: Int
    exchangeAddress: String
    transactionId: String
    predictionMarket: PredictionMarket
    traderId: String
  }

  type PredictionTradesConnection {
    items: [PredictionTrade!]!
    cursor: String
  }

  input PredictionTradesInput {
    marketId: String
    eventId: String
    traderId: String
    limit: Int
    cursor: String
  }
  ```
</div>

## Example: Get recent trades for a market

<a href="/explore" target="_blank" rel="noopener noreferrer">Test this query in the Explorer →</a>

```graphql theme={null}
{
  predictionTrades(
    input: {
      marketId: "0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137"
      limit: 10
    }
  ) {
    items {
      marketId
      outcomeId
      outcomeIndex
      outcomeLabel
      timestamp
      tradeType
      maker
      traderId
      priceUsd
      amountUsd
      transactionHash
      networkId
      protocol
      predictionMarket {
        question
        eventLabel
        venueMarketSlug
      }
    }
  }
}
```

```json Example Response (truncated) theme={null}
{
  "data": {
    "predictionTrades": {
      "items": [
        {
          "marketId": "0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137",
          "outcomeId": "111080671036126109659854287535401661966194360665829017654832975124868412594547:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137",
          "outcomeIndex": 1,
          "outcomeLabel": "No",
          "timestamp": 1773267363,
          "tradeType": "SELL",
          "maker": "0x6904db029589e17f69209646381b6d663d695b63",
          "traderId": "0x6904db029589e17f69209646381b6d663d695b63:Polymarket",
          "priceUsd": "0.998041",
          "amountUsd": "5.988248",
          "transactionHash": "0xd215bd98f3797ebbc057633337658ee48e4d965f88e94931cc2d8927aca4d9c8",
          "networkId": 137,
          "protocol": "POLYMARKET",
          "predictionMarket": {
            "question": "Will the Fed increase interest rates by 25+ bps after the March 2026 meeting?",
            "eventLabel": "Fed decision in March?",
            "venueMarketSlug": "will-the-fed-increase-interest-rates-by-25-bps-after-the-march-2026-meeting"
          }
        }
        // ... 9 more trades
      ]
    }
  }
}
```

## Example: Get trades for a specific trader

```graphql theme={null}
{
  predictionTrades(
    input: {
      traderId: "0x6904db029589e17f69209646381b6d663d695b63:Polymarket"
      limit: 20
    }
  ) {
    items {
      timestamp
      tradeType
      priceUsd
      amountUsd
      outcomeLabel
      predictionMarket {
        question
        eventLabel
      }
    }
  }
}
```

## Example: Get trades for an event

```graphql theme={null}
{
  predictionTrades(
    input: {
      eventId: "67284:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137"
      limit: 50
    }
  ) {
    cursor
    items {
      timestamp
      tradeType
      marketId
      outcomeLabel
      priceUsd
      amountUsd
      predictionMarket {
        question
      }
    }
  }
}
```

## Example: Pagination

```graphql theme={null}
{
  predictionTrades(
    input: {
      eventId: "67284:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137"
      limit: 100
      cursor: "eyJpdiI6IjEzMGIwMzYzNWRkMzhjZjhmODhjMDRiZTZjYjJkZjc0IiwiY29udGVudCI6ImMzNWVlMWMwMDNjZGUxYmM2MDYzZjg2Njg5ZWNhZWNjZWE1ZjYwMTdmODE5YjU4NjcwYmY4ZjE1NGU3M2ExYjA3ZDM3OTkzNDVhM2U1Yjk5NDc2NjI3MWNhMGFkMjgwZTE5Y2I5NDZmNmEwMjU0NWFiNzBmYTZjMDE0M2EyNDIwNGQ1MzFlYWM0YWZlMDYxOTA3NzQ0NjRjZWI4YjRjZDA0ZjFiNGE2MDllN2Y2NzI4N2JjMGE3Njg0NGZiNDlkY2VmN2M1YjAyMTA1ZTFjODY1NmU3ODg0ZTgwNjNlYWM0ZTgyMjMzYmI2ZDM1ZmY0YjY0Y2Y1NmFmZDg0NjgyNjJmMDA2OWZhNmQwYmQxODgyMzM5ZTYzODYzMjI2ZTBhMDhhY2JhMGUxNmI4NjI3NWIwOTI3MjI3NmVlMzdjZmE3ZjAwOGM4NTlmODhkMmI2MTNiN2M4NTkxNzgwMDdkZGMwYjliYjM3ZmY3MjFmZjMwY2U0MjMzMzg3OTZmY2NkMDhkOGIzNGFhNDExOGExNmI1NjU3YjliMzE1YmZmYzI5OWRlYjM0YmQ3YWVlMmRmNzk1Y2ZlOWU3MmRmNzBhZjJiYTc3ZGYyZjRiNjIyN2Y3OTM1MjE4ZDAyZmQxOTc2YWFlZTBhOTVlOTk1ODA2YzA0N2M2YTI5MTQ0NjFkMjMyMDk0NzBmZDRjMmE4MjNhOWEyZjI1ODk3N2NiZmQ2Mjg5ODViNTcwMzg2MDkxYWE3NmVlNTRiMzE3NWI1ZTRmMzcxIn0="
    }
  ) {
    items {
      timestamp
      tradeType
      priceUsd
      amountUsd
    }
  }
}
```

### Usage Guidelines

* **Required**: You must provide at least one of `marketId`, `eventId`, or `traderId` (note: `traderId` only works for Polymarket)
* **ID formats**:
  * `marketId`:
    * **Polymarket**: `<marketAddress>:Polymarket:<exchangeAddress>:<networkId>` (e.g., `0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137`)
    * **Kalshi**: `<marketSlug>:Kalshi` (e.g., `KXMVECROSSCATEGORY-S2026A4A05B370DF-F1FBA451AA9:Kalshi`)
  * `eventId`:
    * **Polymarket**: `<eventSlug>:Polymarket:<exchangeAddress>:<networkId>` (e.g., `67284:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137`)
    * **Kalshi**: `<eventSlug>:Kalshi` (e.g., `KXMVESPORTSMULTIGAMEEXTENDED-S2026350C4EF9BCE:Kalshi`)
  * `traderId`: **Polymarket only** - `<address>:Polymarket` (e.g., `0x742d35cc6634c0532925a3b844bc9e7595f0beb6:Polymarket`)
* Use `cursor` for pagination to fetch additional results
* `limit` controls how many trades to return per request (max varies by plan)
* Trades are returned in reverse chronological order (most recent first)
* Each trade includes both the trade details and associated market information
* `transactionHash` is available for Polymarket (on-chain) but may be null for Kalshi

### Understanding Trade Types

See the [`PredictionTradeType`](/api-reference/enums/predictiontradetype) enum for all possible trade type values and their meanings.

**Platform differences:**

* **Polymarket**: Shows detailed trade types (`BUY`, `SELL`, `BUY_COUNTERPARTY`, `SELL_COUNTERPARTY`) - each trade has two records for both sides
* **Kalshi**: Only shows `TRADE` type with no buy/sell distinction due to privacy limitations on their regulated exchange

### Troubleshooting Tips

<AccordionGroup>
  <Accordion title="Why do I see duplicate trades with different tradeType values?">
    Each trade has two sides - the original trader and the counterparty. If a trader buys, their record shows `BUY` while their counterparty's record shows `BUY_COUNTERPARTY`. This allows you to track both sides of every transaction.
  </Accordion>

  <Accordion title="What's the difference between maker and traderId?">
    `maker` is the raw wallet address, while `traderId` is a composite ID that includes both the wallet address and the protocol. Use `traderId` for querying, and `maker` if you need just the wallet address.
  </Accordion>

  <Accordion title="Can I filter trades by time range?">
    The API doesn't support time range filtering directly. You'll need to fetch trades and filter by `timestamp` on your end. Trades are returned in reverse chronological order, so you can stop fetching once you reach your desired time range.
  </Accordion>

  <Accordion title="How do I calculate the total volume for a trader?">
    Sum the `amountUsd` values for all trades where `tradeType` is `BUY` or `SELL` (not the counterparty types) to avoid double-counting.
  </Accordion>

  <Accordion title="What does the transactionHash represent?">
    The `transactionHash` is the on-chain transaction ID. You can use it to look up the transaction on a block explorer like Polygonscan (for Polymarket, which runs on Polygon).
  </Accordion>
</AccordionGroup>

### Related Recipes

* [Prediction Event Dashboard](/recipes/predictions/event-dashboard): Display a trade feed for an event or market
* [Prediction Traders](/recipes/predictions/traders): Show trade-by-trade history for individual traders