Skip to main content

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.

Webhooks deliver real-time updates from the Codex API directly to an HTTP endpoint you control. Unlike subscriptions, which require a persistent connection, webhooks fit naturally into event-driven architectures, alerting systems, and background services.

​
Delivery and retries

Codex sends webhook messages via HTTP POST and expects a 2xx response within 3 seconds. If your endpoint responds slowly or fails, the message will be retried up to two additional times with gradually increasing delays. If your service is down for long enough, some messages will be lost.
Webhook usage breakdown:
  • Processed means an event matched at a basic level (for example, maker, pair, or token address)
  • Triggered means all conditions passed and Codex will try to publish
  • Success means publishing was attempted and succeeded
  • Failed means publishing was attempted and failed (usually a bad URL)

​
Creating a webhook

The fastest way to create and test a webhook is through the Codex Explorer, which provides a visual builder for every supported event type. To create one programmatically, use the createWebhooks mutation. Each event type has its own input field on the mutation (for example, tokenPairEventWebhooksInput or predictionTradeWebhooksInput). See the event type sections below for a ready-to-use creation example for each.

​
Organizing webhooks with bucketKey

You can optionally group and query your webhooks using a bucketKey. This is useful when you are managing many webhooks per user or per token, such as a price alert system. 
bucketKey: {
  bucketId: "price-alert-${user.id}"
  bucketSortKey: "price-alert-${token.id}"
}
Both bucketId and bucketSortKey must be provided together. If you don’t need to query webhooks by bucket, you can omit bucketKey entirely. Using both fields lets you independently query all alerts for a specific user and all alerts for a specific token.
The individual bucketId and bucketSortKey fields on createWebhook are deprecated. Use the bucketKey object instead.

​
Message structure

Every webhook message shares a common envelope. The type field tells you which event fired, and the data field contains the event-specific payload described in the event type sections.
​
type
WebhookPublisherMessageType
The event type. One of TOKEN_PAIR_EVENT, TOKEN_PAIR_EVENT_BATCH, TOKEN_PRICE_EVENT, TOKEN_PRICE_EVENT_BATCH, TOKEN_TRANSFER_EVENT, TOKEN_TRANSFER_EVENT_BATCH, MARKET_CAP_EVENT, MARKET_CAP_EVENT_BATCH, PREDICTION_TRADE_EVENT, or PREDICTION_TRADE_EVENT_BATCH.
​
deduplicationId
String
A unique identifier for this message. Use it to deduplicate retries on your side.
​
webhookId
String
The ID of the webhook that triggered this message.
​
groupId
String
The ID used to group related messages for ordered delivery.
​
hash
String
deprecated
Deprecated. SHA256 hash of the securityToken and deduplicationId. Prefer the X-Webhook-Timestamp and X-Webhook-Signature headers described in Verifying webhooks. The legacy hash does not cover the request body and is still emitted only for backwards compatibility.
​
data
WebhookPublisherDataModels
The event-specific payload. The shape depends on type. See the event type sections for each payload structure.

​
Verifying webhooks

Every webhook delivery includes two signature headers that authenticate the exact request body bytes and provide a freshness signal for replay protection:
  • X-Webhook-Timestamp: Unix timestamp in seconds.
  • X-Webhook-Signature: lowercase hex HMAC-SHA256 over {timestamp}.{rawBody}, using your webhook’s securityToken as the key.
To verify a delivery:
  1. Read the raw request body bytes as received, before any JSON parsing.
  2. Build the signed payload string {timestamp}.{rawBody}.
  3. Compute hex(hmac_sha256(securityToken, signedPayload)) and compare it to X-Webhook-Signature using a constant-time comparison.
  4. Reject the request if abs(now - X-Webhook-Timestamp) > 300 seconds, or if either header is missing or malformed.
const crypto = require("crypto");

function verifyWebhook ({ rawBody, timestamp, signature, securityToken }) {
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (!Number.isFinite(age) || age > 300) {
    return false;
  }

  const expected = crypto
    .createHmac("sha256", securityToken)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const expectedBuffer = Buffer.from(expected, "hex");
  const signatureBuffer = Buffer.from(signature, "hex");

  return (
    expectedBuffer.length === signatureBuffer.length &&
    crypto.timingSafeEqual(expectedBuffer, signatureBuffer)
  );
}
Verify the original raw request body bytes, then parse JSON only after the signature check passes. Re-serializing the parsed body will change whitespace and key order and produce a different signature.
Capturing the raw body
  • Next.js App Router: call await request.text() once and use that exact string.
  • Next.js API routes: set export const config = { api: { bodyParser: false } }, then read the request stream into a buffer.
  • Express: mount express.raw({ type: "application/json" }) on the webhook route, or capture the buffer in express.json({ verify }).
  • AWS Lambda + API Gateway: use event.body directly, base64-decoding when event.isBase64Encoded is true.
  • Rails/Rack: use request.raw_post. Flask/Django: request.get_data() / request.body.
Common mistakes
  • Parsing and re-serializing JSON before verification.
  • Verifying only data or the legacy hash field instead of {timestamp}.{rawBody}.
  • Comparing signatures with == instead of a constant-time helper.
  • Treating the timestamp as milliseconds. X-Webhook-Timestamp is Unix seconds.
  • Skipping the freshness check, which removes replay protection.

​
Hash verification (deprecated)

The body hash field is deprecated. Use Verifying webhooks with X-Webhook-Timestamp and X-Webhook-Signature. The legacy hash is computed from sha256(securityToken + deduplicationId), so it only identifies the delivery id pair and does not authenticate the delivered body. Both the headers and the legacy hash are emitted during the migration period.
The legacy hash is a SHA256 digest of your webhook’s securityToken concatenated with the message’s deduplicationId: 
const crypto = require('crypto');

const calculatedHash = crypto
  .createHash('sha256')
  .update(securityToken)
  .update(deduplicationId)
  .digest('hex');

​
Source IP addresses

Codex sends webhook deliveries from a fixed set of IP addresses. If you want to gate inbound webhook traffic at the network layer in addition to verifying the signature on each payload, allowlist these IPs at your firewall or load balancer: 
35.155.50.173
52.25.29.13
44.235.164.143
52.32.112.191
Network-level allowlisting complements signature verification, it doesn’t replace it. Always verify the signature on incoming payloads to confirm authenticity.

​
Event types

​
TOKEN_PAIR_EVENT

The TOKEN_PAIR_EVENT webhook fires when a swap, mint, burn, or other liquidity event occurs on a trading pair. It delivers the full Pair and Event objects so you can reconstruct exactly what happened on-chain. This is the most commonly used webhook. When to use it
  • Tracking every trade made by a specific wallet
  • Monitoring high-value swaps on a single token or pair
  • Feeding a live trade tape for a specific pool
  • Alerting on liquidity events (mints, burns) for a pair
Filter conditions
  • tokenAddress: fire for events involving this token
  • networkId: one or more network IDs to listen on
  • swapValue: filter by USD value of the swap
  • maker: fire for events made by a specific wallet
  • pairAddress: fire for events on a specific pair
  • exchangeAddress: fire for events on a specific exchange
  • eventType: filter to specific event types (SWAP, MINT, BURN, SYNC, BUY, SELL, COLLECT, COLLECT_PROTOCOL)
See the full input type at tokenPairEventWebhookConditionInput. Creation example 
mutation CreateTokenPairWebhook {
  createWebhooks(
    input: {
      tokenPairEventWebhooksInput: {
        webhooks: {
          name: "Big swaps on WETH/USDC"
          callbackUrl: "https://your-endpoint.com/webhook"
          securityToken: "your-security-token"
          alertRecurrence: INDEFINITE
          conditions: {
            pairAddress: { eq: "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640" }
            networkId: { oneOf: [1] }
            swapValue: { gte: "10000" }
          }
        }
      }
    }
  ) {
    tokenPairEventWebhooks {
      id
      name
    }
  }
}
Message payload 
{
  "deduplicationId": "aa4cd403-b54e-4e2d-825c-f70a69f6fd9f-DbyEjKTHE76qgb8niQ4zDCoaU4CK7Si9PJkD6Ckjtugo:1399811149-0000000256717997#00000000#00000002#00000009",
  "groupId": "bc9345e6-b0da-4935-9b31-47b34cc5f628",
  "hash": "e39fa0bfcef1bfcd12d6707c29ac752899228d026338e594e04a398255962022",
  "type": "TOKEN_PAIR_EVENT",
  "webhook": {
    "bucketId": "bc9345e6-b0da-4935-9b31-47b34cc5f628",
    "bucketSortkey": "GSE6vfr6vws493G22jfwCU6Zawh3dfvSYXYQqKhFsBwe",
    "id": "aa4cd403-b54e-4e2d-825c-f70a69f6fd9f",
    "name": "traderpow:GSE6vfr6vws493G22jfwCU6Zawh3dfvSYXYQqKhFsBwe:TOKEN_PAIR_EVENT"
  },
  "webhookId": "aa4cd403-b54e-4e2d-825c-f70a69f6fd9f",
  "data": {
    "event": {
      "address": "DbyEjKTHE76qgb8niQ4zDCoaU4CK7Si9PJkD6Ckjtugo",
      "baseTokenPrice": "18651403264.31996",
      "blockHash": "DGXgkMSxovvjdA5iKgrsFL7duNyXRPsW86Ztvg2Mc1hL",
      "blockNumber": 256717997,
      "data": {
        "amount0": "7020307392",
        "amount1": "-2899270904078",
        "liquidity": "51478999661589",
        "liquidity0": "1140722809229",
        "liquidity1": "457845387792910",
        "protocol": "Orca",
        "sqrtPriceX64": "376244087403309877755",
        "tick": "60310",
        "type": "Swap"
      },
      "eventDisplayType": "Buy",
      "eventType": "Swap",
      "eventType2": "Token1Buy",
      "id": "DbyEjKTHE76qgb8niQ4zDCoaU4CK7Si9PJkD6Ckjtugo:1399811149",
      "labels": {},
      "liquidityToken": "So11111111111111111111111111111111111111112",
      "logIndex": 2,
      "maker": "GSE6vfr6vws493G22jfwCU6Zawh3dfvSYXYQqKhFsBwe",
      "makerHashKey": "GSE6vfr6vws493G22jfwCU6Zawh3dfvSYXYQqKhFsBwe:DbyEjKTHE76qgb8niQ4zDCoaU4CK7Si9PJkD6Ckjtugo:1399811149",
      "networkId": 1399811149,
      "quoteToken": "token1",
      "sortKey": "0000000256717997#00000000#00000002#00000009",
      "supplementalIndex": 9,
      "timestamp": 1711526246,
      "token0PoolValueUsd": "186.5140326431996",
      "token0SwapValueUsd": "186.51403264319955960744460600963952776157867455426636901017",
      "token0ValueBase": "1",
      "token0ValueUsd": "186.5140326431996",
      "token1PoolValueUsd": "0.4483442346979745",
      "token1SwapValueUsd": "0.45162590368325119780671230665069180443756818839541768",
      "token1ValueBase": "0.0024038096669951625071971972244735217782",
      "token1ValueUsd": "0.4483442346979745",
      "transactionHash": "2dd5jDHbVYZpXgYbEQzpv47Z7jwimmHeDxKytiM9FB4GzBA5QeYh5xHTzkQvCScQksvTrHqgq9k7q84MBcGbaFfJ",
      "transactionIndex": 0,
      "ttl": 1716710246
    },
    "pair": {
      "address": "DbyEjKTHE76qgb8niQ4zDCoaU4CK7Si9PJkD6Ckjtugo",
      "exchangeHash": "whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc",
      "fee": null,
      "id": "DbyEjKTHE76qgb8niQ4zDCoaU4CK7Si9PJkD6Ckjtugo:1399811149",
      "networkId": 1399811149,
      "tickSpacing": null,
      "token0": "So11111111111111111111111111111111111111112",
      "token1": "FU1q8vJpZNUrmqsciSjp8bAKKidGsLmouB8CBdf8TKQv"
    }
  }
}

## BATCH VERSION
{
  "deduplicationId": "aa4cd403-b54e-4e2d-825c-f70a69f6fd9f-batch-0000000256717997",
  "groupId": "bc9345e6-b0da-4935-9b31-47b34cc5f628",
  "hash": "e39fa0bfcef1bfcd12d6707c29ac752899228d026338e594e04a398255962022",
  "type": "TOKEN_PAIR_EVENT_BATCH",
  "webhookId": "aa4cd403-b54e-4e2d-825c-f70a69f6fd9f",
  "data": [
    {
      "event": { "...": "same shape as single event above" },
      "pair": { "...": "same shape as single event above" }
    },
    {
      "event": { "...": "second event in batch" },
      "pair": { "...": "second pair in batch" }
    }
  ]
}

​
TOKEN_PRICE_EVENT

The TOKEN_PRICE_EVENT webhook fires when the price of a specific token crosses a threshold you define. Use it for price alerts on tokens you care about. When to use it
  • Price alerts for a single token (for example, “WETH above $4000”)
  • Watchlist-style notifications for a small set of tokens
  • Dashboard price tickers where polling is not acceptable
Filter conditions
  • address: the token contract address (required)
  • networkId: the network ID (required)
  • priceUsd: price condition that must be met (required). Supports gt, gte, lt, lte, eq
See the full input type at tokenPriceEventWebhookConditionInput. Creation example 
mutation CreateTokenPriceWebhook {
  createWebhooks(
    input: {
      priceWebhooksInput: {
        webhooks: {
          name: "WETH above $4000"
          callbackUrl: "https://your-endpoint.com/webhook"
          securityToken: "your-security-token"
          alertRecurrence: INDEFINITE
          conditions: {
            address: { eq: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" }
            networkId: { eq: 1 }
            priceUsd: { gte: "4000" }
          }
        }
      }
    }
  ) {
    priceWebhooks {
      id
      name
    }
  }
}
Message payload 
{
  "type": "TOKEN_PRICE_EVENT",
  "deduplicationId": "5e0fe797-c795-451f-af87-0257847b8c3b-0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2:1-0000000024000071#00000117#00000353",
  "webhookId": "5e0fe797-c795-451f-af87-0257847b8c3b",
  "groupId": "5e0fe797-c795-451f-af87-0257847b8c3b",
  "hash": "c296a760c563c9a4115146af75945d1b35d0741835309fa44d393ef3c2b044dd",
  "webhook": {
    "id": "5e0fe797-c795-451f-af87-0257847b8c3b",
    "name": "token-price-webhook"
  },
  "data": {
    "id": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2:1",
    "priceUsd": "3.0898058248076381750556910457327e+3",
    "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "networkId": 1,
    "timestamp": 1765585223,
    "blockNumber": 24000071
  }
}

## BATCH VERSION
{
  "type": "TOKEN_PRICE_EVENT_BATCH",
  "deduplicationId": "5e0fe797-c795-451f-af87-0257847b8c3b-batch-0000000024000071",
  "webhookId": "5e0fe797-c795-451f-af87-0257847b8c3b",
  "groupId": "5e0fe797-c795-451f-af87-0257847b8c3b",
  "hash": "c296a760c563c9a4115146af75945d1b35d0741835309fa44d393ef3c2b044dd",
  "data": [
    {
      "id": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2:1",
      "priceUsd": "3.0898058248076381750556910457327e+3",
      "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "networkId": 1,
      "timestamp": 1765585223,
      "blockNumber": 24000071
    },
    {
      "id": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2:1",
      "priceUsd": "3.0998058248076381750556910457327e+3",
      "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "networkId": 1,
      "timestamp": 1765585423,
      "blockNumber": 24000072
    }
  ]
}

​
TOKEN_TRANSFER_EVENT

The TOKEN_TRANSFER_EVENT webhook fires when a token is transferred to or from a wallet you are monitoring. Use it to track wallet inflows and outflows in real time. When to use it
  • Monitoring whale wallet movements
  • Triggering on-chain alerts for your own wallets
  • Watching known exchange hot wallets or bridge addresses
Filter conditions
  • tokenAddress: the token contract to track
  • networkId: one or more network IDs
  • address: the wallet address to monitor
  • direction: TO (receiving), FROM (sending), or both
See the full input type at tokenTransferEventWebhookConditionInput. Creation example 
mutation CreateTokenTransferWebhook {
  createWebhooks(
    input: {
      tokenTransferEventWebhooksInput: {
        webhooks: {
          name: "Inflows to whale wallet"
          callbackUrl: "https://your-endpoint.com/webhook"
          securityToken: "your-security-token"
          alertRecurrence: INDEFINITE
          conditions: {
            address: { eq: "0x1abde2088657de84ad6239f3d445dd07d6fa1033" }
            networkId: { oneOf: [8453] }
            direction: { oneOf: [TO] }
          }
        }
      }
    }
  ) {
    tokenTransferEventWebhooks {
      id
      name
    }
  }
}
Message payload 
{
  "type": "TOKEN_TRANSFER_EVENT",
  "deduplicationId": "6af3a260-7e2c-4615-babe-c239786ec9fd-0x84df029b0fc5d81ec8d65fa49568bc509e8ce0caa3de05c8de51acea8aafdb6b-740",
  "webhookId": "6af3a260-7e2c-4615-babe-c239786ec9fd",
  "groupId": "762acfb9-872d-4fa7-96a0-e45236759c55",
  "hash": "360adec82a811049a7374b087c40789e716c2329cb5dfc9b6dffc182fb77cd2b",
  "webhook": {
    "id": "6af3a260-7e2c-4615-babe-c239786ec9fd",
    "name": "Track transfers to wallet"
  },
  "data": {
    "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "networkId": 8453,
    "fromAddress": "0x4767bf3619bb493d129c864a023512fa1dce9da4",
    "toAddress": "0x1abde2088657de84ad6239f3d445dd07d6fa1033",
    "amount": "20000",
    "shiftedAmount": "0.02",
    "direction": "TO",
    "timestamp": 1767657659,
    "blockNumber": 40434156,
    "transactionHash": "0x84df029b0fc5d81ec8d65fa49568bc509e8ce0caa3de05c8de51acea8aafdb6b",
    "transactionIndex": 171,
    "logIndex": 740
  }
}

## BATCH VERSION
{
  "type": "TOKEN_TRANSFER_EVENT_BATCH",
  "deduplicationId": "6af3a260-7e2c-4615-babe-c239786ec9fd-batch-40434156",
  "webhookId": "6af3a260-7e2c-4615-babe-c239786ec9fd",
  "groupId": "762acfb9-872d-4fa7-96a0-e45236759c55",
  "hash": "360adec82a811049a7374b087c40789e716c2329cb5dfc9b6dffc182fb77cd2b",
  "webhook": {
    "id": "6af3a260-7e2c-4615-babe-c239786ec9fd",
    "name": "Track all transfers"
  },
  "data": [
    {
      "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "networkId": 8453,
      "fromAddress": "0x4767bf3619bb493d129c864a023512fa1dce9da4",
      "toAddress": "0x1abde2088657de84ad6239f3d445dd07d6fa1033",
      "amount": "20000",
      "shiftedAmount": "0.02",
      "direction": "TO",
      "timestamp": 1767657659,
      "blockNumber": 40434156,
      "transactionHash": "0x84df029b0fc5d81ec8d65fa49568bc509e8ce0caa3de05c8de51acea8aafdb6b",
      "transactionIndex": 171,
      "logIndex": 740
    },
    {
      "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "networkId": 8453,
      "fromAddress": "0x1abde2088657de84ad6239f3d445dd07d6fa1033",
      "toAddress": "0x9876543210fedcba9876543210fedcba98765432",
      "amount": "50000",
      "shiftedAmount": "0.05",
      "direction": "FROM",
      "timestamp": 1767657700,
      "blockNumber": 40434160,
      "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "transactionIndex": 85,
      "logIndex": 312
    }
  ]
}

​
MARKET_CAP_EVENT

The MARKET_CAP_EVENT webhook fires when a token’s market cap crosses a threshold you specify. Unlike token price webhooks, it factors in supply (both fully diluted and circulating). When to use it
  • Market cap milestone alerts (for example, “VIRTUAL crosses $1B FDV”)
  • Large-cap filtering logic for automated tools
  • Portfolio-level risk dashboards
Filter conditions
  • tokenAddress: the token contract (required)
  • networkId: the network ID (required)
  • fdvMarketCapUsd: fully diluted market cap threshold
  • circulatingMarketCapUsd: circulating market cap threshold
  • pairAddress: optional source pair constraint
  • liquidityUsd, volumeUsd: optional pair-level liquidity and volume constraints
See the full input type at marketCapEventWebhookConditionInput. Creation example 
mutation CreateMarketCapWebhook {
  createWebhooks(
    input: {
      marketCapEventWebhooksInput: {
        webhooks: {
          name: "VIRTUAL hits $1B FDV"
          callbackUrl: "https://your-endpoint.com/webhook"
          securityToken: "your-security-token"
          alertRecurrence: ONCE
          conditions: {
            tokenAddress: { eq: "0x0b3e328455c4059eeb9e3f84b5543f74e24e7e1b" }
            networkId: { eq: 8453 }
            fdvMarketCapUsd: { gte: "1000000000" }
          }
        }
      }
    }
  ) {
    marketCapEventWebhooks {
      id
      name
    }
  }
}
Message payload 
{
  "type": "MARKET_CAP_EVENT",
  "deduplicationId": "5e0fe797-c795-451f-af87-0257847b8c3b-0x0b3e328455c4059eeb9e3f84b5543f74e24e7e1b:8453-0000000030917440#00000117#00000353",
  "webhookId": "5e0fe797-c795-451f-af87-0257847b8c3b",
  "groupId": "test-group",
  "hash": "c296a760c563c9a4115146af75945d1b35d0741835309fa44d393ef3c2b044dd",
  "webhook": {
    "id": "5e0fe797-c795-451f-af87-0257847b8c3b",
    "name": "mcap-virt"
  },
  "data": {
    "priceModel": {
      "id": "0x0b3e328455c4059eeb9e3f84b5543f74e24e7e1b:8453",
      "priceUsd": "2.014904011469267",
      "address": "0x0b3e328455c4059eeb9e3f84b5543f74e24e7e1b",
      "networkId": 8453,
      "timestamp": 1748624227,
      "blockNumber": 30917440,
      "absoluteDeviation": 0,
      "derivedSwapPrice": "2.008965143151456",
      "targetTokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "pairMetadata": {
        "liquidityUsd": "67747",
        "pairId": "0x2aeee741fa1e21120a21e57db9ee545428e683c9:1",
        "volume24Usd": "162206"
      }
    },
    "tokenModel": {
      "id": "0x0b3e328455c4059eeb9e3f84b5543f74e24e7e1b:8453",
      "address": "0x0b3e328455c4059eeb9e3f84b5543f74e24e7e1b",
      "name": "Virtual Protocol",
      "symbol": "VIRTUAL",
      "decimals": 18,
      "shiftedTotalSupply": "495620931.12225886540849246",
      "shiftedCirculatingSupply": "495620930.505466750752879695"
    },
    "fdvMarketCapUsd": "998628602.29",
    "circulatingMarketCapUsd": "998628601.04"
  }
}

## BATCH VERSION
{
  "type": "MARKET_CAP_EVENT_BATCH",
  "deduplicationId": "5e0fe797-c795-451f-af87-0257847b8c3b-batch-0000000030917440",
  "webhookId": "5e0fe797-c795-451f-af87-0257847b8c3b",
  "groupId": "test-group",
  "hash": "c296a760c563c9a4115146af75945d1b35d0741835309fa44d393ef3c2b044dd",
  "data": [
    {
      "priceModel": { "...": "same shape as single event above" },
      "tokenModel": { "...": "same shape as single event above" },
      "fdvMarketCapUsd": "998628602.29",
      "circulatingMarketCapUsd": "998628601.04"
    }
  ]
}

​
PREDICTION_TRADE_EVENT

The PREDICTION_TRADE_EVENT webhook fires when a prediction market trade occurs. Use it to track trades by a specific trader, on a specific market or event, or matching conditions like trade value or volume. When to use it
  • Tracking copy-traded wallets on Polymarket or Kalshi
  • Notifying on large trades in a specific market or event
  • Feeding a live trade tape for a prediction market dashboard
Filter conditions
  • traderId: fire for a specific trader
  • marketId: fire for a specific market
  • eventId: fire for a specific event
  • eventType: filter by trade event type (TRADE, BUY, SELL, BUY_COUNTERPARTY, SELL_COUNTERPARTY, PAYOUT_REDEMPTION)
  • tradeValueUsd: filter by trade value in USD
  • amountToken: filter by number of tokens or shares traded
See the full input type at predictionTradeWebhookConditionInput. Creation example 
mutation CreatePredictionTradeWebhook {
  createWebhooks(
    input: {
      predictionTradeWebhooksInput: {
        webhooks: {
          name: "Track trader activity"
          callbackUrl: "https://your-endpoint.com/webhook"
          securityToken: "your-security-token"
          alertRecurrence: INDEFINITE
          conditions: {
            traderId: { eq: "your-trader-id" }
            tradeValueUsd: { gte: "100" }
          }
          bucketKey: {
            bucketId: "trader-alerts-${user.id}"
            bucketSortKey: "trader-${traderId}"
          }
        }
      }
    }
  ) {
    predictionTradeWebhooks {
      id
      name
    }
  }
}
Message payload 
{
  "type": "PREDICTION_TRADE_EVENT",
  "deduplicationId": "abc123-...",
  "webhookId": "6af3a260-7e2c-4615-babe-c239786ec9fd",
  "groupId": "762acfb9-872d-4fa7-96a0-e45236759c55",
  "hash": "360adec82a811049a7374b087c40789e716c2329cb5dfc9b6dffc182fb77cd2b",
  "webhook": {
    "id": "6af3a260-7e2c-4615-babe-c239786ec9fd",
    "name": "Track trader activity"
  },
  "data": {
    "marketId": "0x1234...abcd",
    "sortKey": "0000000040434156#00000171#00000740",
    "outcomeId": "outcome-1",
    "outcomeLabel": "Yes",
    "protocol": "POLYMARKET",
    "tradeType": "BUY",
    "maker": "0x4767bf3619bb493d129c864a023512fa1dce9da4",
    "timestamp": 1767657659,
    "outcomeIndex": 0,
    "priceUsd": "0.72",
    "priceCollateral": "0.72",
    "amount": "100",
    "amountCollateral": "72",
    "amountUsd": "72.00",
    "transactionHash": "0x84df029b0fc5d81ec8d65fa49568bc509e8ce0caa3de05c8de51acea8aafdb6b",
    "blockNumber": 40434156,
    "networkId": 137,
    "exchangeAddress": "0xe55b5ceba4dc0d4e26261f3dcd468faaf7d0cdb8",
    "transactionId": "txn-abc123",
    "traderId": "trader-xyz",
    "eventId": "event-456"
  }
}

## BATCH VERSION
{
  "type": "PREDICTION_TRADE_EVENT_BATCH",
  "deduplicationId": "abc123-batch-40434156",
  "webhookId": "6af3a260-7e2c-4615-babe-c239786ec9fd",
  "groupId": "762acfb9-872d-4fa7-96a0-e45236759c55",
  "hash": "360adec82a811049a7374b087c40789e716c2329cb5dfc9b6dffc182fb77cd2b",
  "data": [
    {
      "marketId": "0x1234...abcd",
      "sortKey": "0000000040434156#00000171#00000740",
      "outcomeId": "outcome-1",
      "outcomeLabel": "Yes",
      "protocol": "POLYMARKET",
      "tradeType": "BUY",
      "maker": "0x4767bf3619bb493d129c864a023512fa1dce9da4",
      "timestamp": 1767657659,
      "outcomeIndex": 0,
      "priceUsd": "0.72",
      "priceCollateral": "0.72",
      "amount": "100",
      "amountCollateral": "72",
      "amountUsd": "72.00",
      "transactionHash": "0x84df029b0fc5d81ec8d65fa49568bc509e8ce0caa3de05c8de51acea8aafdb6b",
      "blockNumber": 40434156,
      "networkId": 137,
      "exchangeAddress": "0xe55b5ceba4dc0d4e26261f3dcd468faaf7d0cdb8",
      "transactionId": "txn-abc123",
      "traderId": "trader-xyz",
      "eventId": "event-456"
    },
    {
      "marketId": "0x1234...abcd",
      "sortKey": "0000000040434157#00000172#00000741",
      "outcomeId": "outcome-2",
      "outcomeLabel": "No",
      "protocol": "POLYMARKET",
      "tradeType": "SELL",
      "maker": "0x9876543210fedcba9876543210fedcba98765432",
      "timestamp": 1767657700,
      "outcomeIndex": 1,
      "priceUsd": "0.28",
      "priceCollateral": "0.28",
      "amount": "50",
      "amountCollateral": "14",
      "amountUsd": "14.00",
      "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "blockNumber": 40434157,
      "networkId": 137,
      "exchangeAddress": "0xe55b5ceba4dc0d4e26261f3dcd468faaf7d0cdb8",
      "transactionId": "txn-def456",
      "traderId": "trader-abc",
      "eventId": "event-456"
    }
  ]
}

​
FAQ

Webhooks monitor one token at a time, but there is no limit on how many webhooks you can create. To watch many tokens, create one webhook per token (the bucketKey field makes managing large sets straightforward).
Create a TOKEN_PAIR_EVENT webhook for the token and filter eventType to BUY. The webhook payload includes the full event object, so you don’t need a follow-up call to enrich the data. See the TOKEN_PAIR_EVENT section above for the full creation example.
securityToken is your secret. Codex uses it as the HMAC key for the X-Webhook-Signature header on every delivery, which authenticates the exact raw request body. See Verifying webhooks for the full verification flow. The legacy body hash field is also derived from securityToken but is deprecated because it doesn’t cover the body.
Each webhook delivery counts as 1 request. If you also fire a follow-up API call to enrich the event (e.g. fetching token metadata), that’s a second request. So if you’re processing 10k buys per day with one enrichment call each, that’s 20k requests/day or roughly 600k/month.