Polymarket Substreams

What this package is for

This is the comprehensive event archive in the Polymarket substreams family — designed to capture every on-chain event that touches Polymarket markets, not just trade fills.

It's complementary to two more focused packages:

If you only need order flow, use orderbook. If you only need P&L, use pnl. If you need market lifecycle (when conditions are prepared/resolved), user mint/redeem flows (PositionSplit/PositionsMerge/PayoutRedemption), or raw USDC.e + pUSD collateral movements, use this package.

CLOB v2 ready (since v0.3.0)

Polymarket migrated to CLOB v2 at the 2026-04-28 ~11:00 UTC cutover. v2 ships fresh Exchange contracts at new addresses, a redesigned OrderFilled event, a new fee model, and a new wallet-facing collateral wrapper (pUSD). This package indexes both contract generations and the new collateral wrapper alongside the unchanged Conditional Tokens layer.

What changed in CLOB v2

How this package handles it

1. CLOB v1 + v2 dual coverage. map_ctf_exchange_events (v1) extracts events from CTF Exchange 0x4bfb… and NegRisk Exchange 0xC5d5… (the v0.2.0 release was missing NegRisk — fixed in v0.3.0). Two new modules — map_ctf_exchange_v2_events and map_neg_risk_exchange_v2_events — extract the v2 OrderFilled (with single tokenId + explicit side + builder + metadata), v2 OrdersMatched, OrderPreapprovalInvalidated, FeeCharged, TradingPaused/Unpaused. Each v2 row is tagged with source_contract (ctf_v2 / neg_risk_v2).
2. Conditional Tokens layer is unchanged. map_ctf_events decodes ConditionPreparation, ConditionResolution, PositionSplit, PositionsMerge, and PayoutRedemption from 0x4D97…6045 — these contracts are unchanged in v2, so this module covers both eras with a single configuration. (v0.2.0 had this as a stub; v0.3.0 actually implements it.)
3. Both collateral tokens. map_usdc_events continues to track USDC.e Transfer/Approval events (still the CTF-level collateral). map_pusd_events is new — it tracks the wallet-facing pUSD wrapper (0xC011…2DFB) introduced in v2. (USDC was also a stub in v0.2.0; now implemented.)
4. V4 protocol + S2 compression. Built against substreams-sink-database-changes v4 and the latest substreams CLI; benefits from V4 Blocks Streams batching and S2 compression auto-negotiated by StreamingFast endpoints.
5. No schema migration on existing tables. All v0.2.0 tables (order_fills, orders_matched, order_cancellations, fee_charges, token_registrations, etc.) keep their schema. New v2 tables (order_fills_v2, orders_matched_v2, order_cancellations_v2, fee_charges_v2) sit alongside. New CTF lifecycle tables (condition_preparations, condition_resolutions, position_splits, position_merges, position_redemptions) and collateral tables (usdc_transfers, pusd_transfers) are also new.

What stays the same

• Same chain (Polygon), same Firehose source.
• Same module names for v1 modules — additive only, map_ctf_exchange_events now also covers NegRisk.
• Existing v0.2.0 SQL tables and indexes continue working unchanged.

Modules

CLOB v1 (legacy — historical fills only after the 2026-04-28 cutover)

CLOB v2 (deployed 2026-03-31, cutover 2026-04-28)

Conditional Tokens (unchanged across v1/v2)

Collateral

Aggregations

Contract Addresses

CLOB v1 (legacy)

CLOB v2 (deployed 2026-03-31)

Always-on infrastructure

V2 Exchange deploy block: 84,902,353 · Cutover: 2026-04-28 ~11:00 UTC

Quick Start

# Install Substreams CLI
brew install streamingfast/tap/substreams

# Authenticate
substreams auth

# Stream all v1 + v2 fills (v1 module covers CTF + NegRisk)
substreams run https://spkg.io/PaulieB14/polymarket-v0.3.0.spkg \
  map_ctf_exchange_events \
  -e polygon.substreams.pinax.network:443 \
  -s 33605403 -t +1000

# Stream market lifecycle (creations/resolutions/splits/merges/redemptions)
substreams run https://spkg.io/PaulieB14/polymarket-v0.3.0.spkg \
  map_ctf_events \
  -e polygon.substreams.pinax.network:443 \
  -s 33605403 -t +1000

# Stream pUSD transfers (post-cutover)
substreams run https://spkg.io/PaulieB14/polymarket-v0.3.0.spkg \
  map_pusd_events \
  -e polygon.substreams.pinax.network:443 \
  -s 84902353 -t +1000

SQL Sink

# Create database and apply schema
createdb polymarket
psql -d polymarket -f schema.sql

# Setup sink
substreams-sink-sql setup \
  "psql://localhost:5432/polymarket?sslmode=disable" \
  https://spkg.io/PaulieB14/polymarket-v0.3.0.spkg

# Run sink
substreams-sink-sql run \
  "psql://localhost:5432/polymarket?sslmode=disable" \
  https://spkg.io/PaulieB14/polymarket-v0.3.0.spkg \
  -e polygon.substreams.pinax.network:443

Sample queries

-- All v1 + v2 fills in chronological order
SELECT 'v1' AS gen, evt_block_number, evt_tx_hash, maker, taker, maker_amount_filled
FROM order_fills
UNION ALL
SELECT source_contract AS gen, evt_block_number, evt_tx_hash, maker, taker, maker_amount_filled
FROM order_fills_v2
ORDER BY evt_block_number DESC LIMIT 100;

-- Markets created vs resolved
SELECT
  COUNT(DISTINCT cp.condition_id) AS markets_created,
  COUNT(DISTINCT cr.condition_id) AS markets_resolved
FROM condition_preparations cp
LEFT JOIN condition_resolutions cr USING (condition_id);

-- Top stakeholders by mint volume (PositionSplit)
SELECT stakeholder, COUNT(*) AS splits, SUM(amount::numeric) AS total_minted
FROM position_splits
GROUP BY stakeholder
ORDER BY total_minted DESC LIMIT 50;

-- Builder attribution (v2 only)
SELECT builder, COUNT(*) AS fills, SUM(taker_amount_filled::numeric) AS volume
FROM order_fills_v2
WHERE builder <> '0000000000000000000000000000000000000000000000000000000000000000'
GROUP BY builder
ORDER BY volume DESC;

-- pUSD vs USDC.e flow comparison post-cutover
SELECT 'usdc.e' AS token, SUM(value::numeric) AS volume FROM usdc_transfers WHERE evt_block_number > 84902353
UNION ALL
SELECT 'pusd' AS token, SUM(value::numeric) AS volume FROM pusd_transfers;

Architecture

                                Polygon Blockchain
                                       │
                                       ▼
                              ┌─────────────────┐
                              │ Firehose Blocks │
                              └────────┬────────┘
                                       │
        ┌────────────┬─────────────────┼─────────────────┬─────────────┐
        ▼            ▼                 ▼                 ▼             ▼
   ┌─────────┐  ┌──────────┐    ┌────────────┐    ┌──────────┐  ┌──────────┐
   │ CTF v1  │  │ CTF v2   │    │ NegRisk v2 │    │ CTF      │  │ USDC.e + │
   │ + NegRisk│  │ Exchange │    │ Exchange   │    │ Cond.Toks│  │ pUSD     │
   └─────┬───┘  └─────┬────┘    └─────┬──────┘    └────┬─────┘  └────┬─────┘
         │            │                │                │             │
         └────────────┴────────┬───────┴────────────────┴─────────────┘
                               ▼
                       ┌──────────────┐
                       │   db_out     │
                       │ (SQL/CH)     │
                       └──────┬───────┘
                              │
                    ┌─────────┴────────┐
                    ▼                  ▼
              PostgreSQL          ClickHouse

Build from Source

git clone https://github.com/PaulieB14/Polymarket-Substreams
cd Polymarket-Substreams

substreams build
substreams pack

# Stream locally
substreams run substreams.yaml map_ctf_exchange_v2_events \
  -e polygon.substreams.pinax.network:443 \
  -s 84902353 -t +100

License

MIT — see LICENSE.