Event Replay API

The Event Replay API provides a way to fetch events that your system may have missed. All events (market changes, trades, settlements, etc.) are persisted with incrementing sequence numbers and retained for 24 hours.

Authentication: X-Api-Key header required.

Why Event Replay?

If your webhook endpoint goes down or your WebSocket disconnects, you can replay missed events:

1. Store the last sequence number you processed
2. When reconnected, call GET /api/v1/events?since={lastSequence}
3. Process events in order
4. Update your stored sequence number

Replay Events

GET /api/v1/events

Query Parameters:

Parameter	Type	Description
since	integer	Return events with sequence > this value
eventType	string	Filter by event type (e.g. ORDER_MATCHED)
marketId	string (UUID)	Filter by market
limit	integer	Page size (default: 100, max: 1000)

Example — fetch all events since sequence 42:

curl "https://polymarket.sandbox.playbatman.com/api/v1/events?since=42&limit=100" \
  -H "X-Api-Key: your-api-key"

Response:

{
  "success": true,
  "data": {
    "events": [
      {
        "id": "event-uuid-1",
        "sequence": 43,
        "operatorId": "operator-uuid",
        "eventType": "ORDER_PLACED",
        "marketId": "market-uuid",
        "payload": {
          "orderId": "order-uuid",
          "marketId": "market-uuid",
          "outcomeId": "outcome-uuid",
          "operatorId": "operator-uuid",
          "side": "BUY",
          "type": "LIMIT",
          "shares": 50,
          "price": 0.65,
          "status": "PENDING",
          "filledShares": 0,
          "timestamp": 1708293600000
        },
        "createdAt": "2026-02-18T23:00:00.000Z",
        "expiresAt": "2026-02-19T23:00:00.000Z"
      },
      {
        "id": "event-uuid-2",
        "sequence": 44,
        "operatorId": "operator-uuid",
        "eventType": "ORDER_MATCHED",
        "marketId": "market-uuid",
        "payload": {
          "orderId": "order-uuid",
          "marketId": "market-uuid",
          "outcomeId": "outcome-uuid",
          "operatorId": "operator-uuid",
          "tradeId": "trade-uuid",
          "side": "BUY",
          "price": 0.65,
          "shares": 50,
          "filledShares": 50,
          "remainingShares": 0,
          "status": "FILLED",
          "timestamp": 1708293600000
        },
        "createdAt": "2026-02-18T23:00:01.000Z",
        "expiresAt": "2026-02-19T23:00:01.000Z"
      }
    ],
    "hasMore": true,
    "lastSequence": 44
  }
}

Pagination

Use the lastSequence from the response as the since parameter in your next request:

# First page
GET /api/v1/events?limit=100

# Next page (using lastSequence from previous response)
GET /api/v1/events?since=44&limit=100

# Continue until hasMore is false

Filtering

By Event Type

# Only trade events
GET /api/v1/events?eventType=ORDER_MATCHED

# Only market resolution events
GET /api/v1/events?eventType=MARKET_RESOLVED

By Market

# Events for a specific market
GET /api/v1/events?marketId=market-uuid

# Combined filters
GET /api/v1/events?marketId=market-uuid&eventType=ORDER_MATCHED&since=100

Event Types

Event Type	Description
MARKET_CREATED	A new market was created
MARKET_STATUS_CHANGED	Market status changed (open, suspended, closed, etc.)
MARKET_RESOLVED	Market resolved with a winning outcome
ORDER_BOOK_UPDATE	Order book changed
PRICE_UPDATED	Market prices updated
ORDER_PLACED	A new order was submitted
ORDER_MATCHED	An order was matched, trade executed
ORDER_CANCELLED	An order was cancelled
POSITION_UPDATED	A position was updated
SETTLEMENT_COMPLETED	A settlement was processed

Event Fields

Field	Type	Description
id	string (UUID)	Unique event ID
sequence	integer	Monotonically increasing sequence number
operatorId	string (UUID)	Operator the event belongs to
eventType	string	One of the event types above
marketId	string (UUID) | null	Associated market (null for non-market events)
payload	object	Event-specific data
createdAt	string (ISO 8601)	When the event occurred
expiresAt	string (ISO 8601)	When the event will be deleted (24h retention)

Retention

• Events are retained for 24 hours from creation
• Expired events are automatically cleaned up every hour
• Store the lastSequence value on your side to resume after outages

Integration Pattern

Here's a recommended pattern for reliable event processing:

let lastSequence = loadLastSequence(); // Load from your database

async function syncEvents() {
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://polymarket.sandbox.playbatman.com/api/v1/events?since=${lastSequence}&limit=100`,
      { headers: { 'X-Api-Key': API_KEY } }
    );

    const { data } = await response.json();

    for (const event of data.events) {
      await processEvent(event);
      lastSequence = event.sequence;
      saveLastSequence(lastSequence); // Persist to your database
    }

    hasMore = data.hasMore;
  }
}

// Run on startup and periodically as a safety net
syncEvents();
setInterval(syncEvents, 60000); // Every minute