> ## 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.

# onPredictionTradesCreated

> Streams new prediction trades as they are ingested. onPredictionTradesCreated subscription reference: arguments and payload fields.

> [!NOTE]
>
> **Kalshi has limited trade data**. When subscribing to 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.

## GraphQL

```
type Subscription {
  # Requires a Growth or Enterprise plan.
  onPredictionTradesCreated(
    input: OnPredictionTradesCreatedInput
  ): AddPredictionTradeOutput
}

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
  exchangeTradedOnAddress: String
  collateralTokenAddress: String
  transactionId: String
  predictionMarket: PredictionMarket
  traderId: String
}

type AddPredictionTradeOutput {
  marketId: String!
  eventId: String!
  trades: [PredictionTrade]!
}

input OnPredictionTradesCreatedInput {
  marketId: String
  eventId: String
  traderId: String
}
```

## Subscription example

[Test this query in the Explorer →](https://docs.codex.io/explore.md)

```graphql theme={null}
subscription {
  onPredictionTradesCreated(
    input: {
      marketId: "0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137"
      # Optional filters:
      # eventId: "67284:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137"
      # traderId: "0xa8702435199b2275b827ee5b88e78bb568a67a65:Polymarket"
    }
  ) {
    eventId
    trades {
      sortKey
      outcomeId
      outcomeLabel
      protocol
      tradeType
      maker
      timestamp
      outcomeIndex
      priceUsd
      priceCollateral
      amount
      amountCollateral
      amountUsd
      transactionHash
      blockNumber
      networkId
      exchangeAddress
      transactionId
      traderId
      predictionMarket {
        id
        protocol
        venueMarketId
        question
        label
        eventLabel
        outcomeLabels
        closesAt
        resolvesAt
      }
    }
  }
}
```

```json Example Response theme={null}
{
  "data": {
    "onPredictionTradesCreated": {
      "marketId": "0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137",
      "eventId": "67284:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137",
      "trades": [
        {
          "marketId": "0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137",
          "outcomeId": "111080671036126109659854287535401661966194360665829017654832975124868412594547:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137",
          "outcomeLabel": "No",
          "protocol": "POLYMARKET",
          "tradeType": "BUY",
          "maker": "0xa8702435199b2275b827ee5b88e78bb568a67a65",
          "timestamp": 1773355617,
          "outcomeIndex": 1,
          "priceUsd": "0.998860",
          "priceCollateral": "0.999",
          "amount": "54.004",
          "amountCollateral": "53.949996",
          "amountUsd": "53.942428",
          "transactionHash": "0x282415359cdc196306f87011fa080f11dc7dedd6a5ade65b369407244b66cec0",
          "blockNumber": 84117792,
          "networkId": 137,
          "exchangeAddress": "0xc5d563a36ae78145c45a50134d48a1215220f80a",
          "transactionId": null,
          "traderId": "0xa8702435199b2275b827ee5b88e78bb568a67a65:Polymarket",
          "predictionMarket": null
        }
      ]
    }
  }
}
```

### Usage Guidelines

* **ID formats**:
  * Market ID:
    * **Polymarket**: `<marketAddress>:Polymarket:<exchangeAddress>:<networkId>` (e.g., `0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137`)
    * **Kalshi**: `<marketSlug>:Kalshi` (e.g., `KXMVECROSSCATEGORY-S2026A4A05B370DF-F1FBA451AA9:Kalshi`)
  * Event ID varies by platform:
    * **Polymarket**: `<eventSlug>:Polymarket:<exchangeAddress>:<networkId>` (e.g., `67284:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137`)
    * **Kalshi**: `<eventSlug>:Kalshi` (e.g., `KXMVESPORTSMULTIGAMEEXTENDED-S2026350C4EF9BCE:Kalshi`)
  * Trader ID: **Polymarket only** - `<address>:Polymarket` (e.g., `0x02227b8f5a9636e895607edd3185ed6ee5598ff7:Polymarket`)
* Subscribe with optional filters: `marketId` (specific outcome), `eventId` (all outcomes in an event), or `traderId` (trades by a specific user - Polymarket only)
* Trades stream in real-time as they are ingested from prediction market venues
* `priceUsd` shows the probability price (0.00 to 1.00), while `amountUsd` shows the monetary value
* **Platform differences**: Polymarket shows `BUY`/`SELL` trade types, while Kalshi only shows `TRADE` type

### Troubleshooting Tips

> [accordion] What do the different tradeType values mean?
>
> `BUY` means purchasing shares of an outcome, `SELL` means selling shares. `TRADE` is a generic trade without direction. `BUY_COUNTERPARTY` and `SELL_COUNTERPARTY` represent the opposite side of maker trades. `PAYOUT_REDEMPTION` indicates claiming winnings after resolution.

> [accordion] How do I calculate the trader's profit or loss?
>
> For a resolved market, profit = (final outcome price - entry price) \* shares held. If the trader bought "Yes" at 0.65 and it resolved to 1.00, their profit is (1.00 - 0.65) \* shares. If it resolved to 0.00, their loss is 0.65 \* shares.

> [accordion] What's the relationship between amount, priceUsd, and amountUsd?
>
> `amount` is the number of shares traded, `priceUsd` is the per-share price, and `amountUsd` is the total cost (`amount * priceUsd`). For example, buying 1000 shares at 0.65 per share costs \$650 USD.

> [accordion] Why do some trades have null values for certain fields?
>
> Older trades or trades from certain venues may be missing data like `transactionHash`, `blockNumber`, or `traderId`. This depends on what data the prediction market protocol provides. Always check for null before using these fields.

> [accordion] How do I build a real-time order book from this subscription?
>
> This subscription provides executed trades (fills), not pending orders. To build an order book, you need to track the current state of liquidity using [`onPredictionMarketBarsUpdated`](https://docs.codex.io/api-reference/subscriptions/onpredictionmarketbarsupdated) or query market depth through the prediction venue's native API. Use trade data to show trade history and recent activity.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.