PMWallets
中文

Reading Polymarket from the Polygon chain: contracts and events

Every Polymarket trade, split, merge and redemption is a log on Polygon. This is the map: which contracts matter, which events they emit, and the traps between a raw log and a correct number.

The contracts

Positions live in the Conditional Tokens (CTF) contract as ERC-1155 tokens. Orders are matched off chain by Polymarket's order book and settled on chain by an exchange contract: one for binary markets and one for NegRisk multi-outcome markets, each in a legacy and a v2 generation. The NegRisk adapter handles conversions and lifecycle operations for multi-outcome events. The addresses below are the ones PMWallets ingests.

text
# Polygon (chain id 137) — the contracts behind Polymarket trading
CTF (Conditional Tokens)        0x4d97dcd97ec945f40cf65f87097ace5ea0476045
CTF Exchange (legacy)           0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e
NegRisk CTF Exchange (legacy)   0xc5d563a36ae78145c45a50134d48a1215220f80a
CTF Exchange (v2)               0xe111180000d2663c0091e4f400237545b87b996b
NegRisk CTF Exchange (v2)       0xe2222d279d744050d28e00520010520000310f59
NegRisk Adapter                 0xd91e80cf2e7be2e162c6513ced06f1dd0da35296

# events worth reading
exchanges   OrderFilled, OrdersMatched, TokenRegistered (+ FeeCharged on v2)
CTF         TransferSingle, TransferBatch, PositionSplit, PositionsMerge,
            PayoutRedemption, ConditionPreparation, ConditionResolution
adapter     PositionSplit, PositionsMerge, PositionsConverted, PayoutRedemption,
            MarketPrepared, QuestionPrepared, OutcomeReported

Trades: OrderFilled and OrdersMatched

Each match emits OrderFilled events for the orders it fills, plus an OrdersMatched that summarises the taker's side. OrderFilled names the maker and the taker and the amounts on each side; which token was traded, and in which direction, follows from the asset IDs (collateral is asset 0) or, on v2, from an explicit side field. The legacy and v2 exchanges use different OrderFilled layouts, and v2 also emits a FeeCharged event for the fee collected.

Positions: transfers, splits, merges, redemptions

Every change in a wallet's shares is an ERC-1155 TransferSingle or TransferBatch on the CTF contract — including the ones caused by trades, splits and redemptions. PositionSplit, PositionsMerge and PayoutRedemption say why collateral moved; ConditionResolution gives the payout for each outcome. A wallet's balance computed from transfers is the ground truth that every other figure has to agree with.

The traps

Proxy wallets: fills name the smart-contract wallet, not the trader behind it. NegRisk: conversions are routed through a Polymarket contract, so the beneficiary is not the address in the event. Token IDs: logs carry token IDs only; mapping them to markets needs the exchanges' TokenRegistered events or the CTF's condition data, and market names come from Polymarket's Gamma API. Reorgs: Polygon produces a block about every 1.5 seconds and reorganises the tip now and then, so a head received over a WebSocket has to be checked against the canonical chain before it is trusted. Completeness: RPC providers cap how many logs one getLogs call returns, and a silently truncated answer looks like a quiet block.

Or let someone else carry it

PMWallets ingests all of these into its own ledger, block by block, and publishes the result as a leaderboard, per-trader profiles, a real-time fill feed and per-day trade-history files. If you need raw history yourself, the trade-history export gives every fill of a wallet as CSV, read from the same logs.

Questions

Which contract does Polymarket trade on?

Trades settle on Polymarket's CTF Exchange (binary markets) or NegRisk CTF Exchange (multi-outcome markets) on Polygon, each with a legacy and a v2 deployment; the shares themselves are ERC-1155 tokens in the Conditional Tokens contract.

Can I get Polymarket trade data without an API key?

Yes. Every fill is a public OrderFilled log on Polygon, readable from any Polygon node, and Polymarket's public Data API returns a wallet's trades without a key. The work is in decoding, attributing and keeping it complete.

Why do two Polymarket data sources disagree on a wallet's trades?

Usually because one counts the smart-contract wallet and the other the trader behind it, one includes splits, merges and conversions and the other only fills, or they cover different time ranges.

Related