Trade Events

The trades channel ("orders") streams real-time trade events from Polymarket. By default, you receive confirmed events - trades that have been mined on-chain. Covers both V1 and V2 Polymarket contracts.

Want even earlier signals? Pending trade events deliver trades 3–5 seconds before confirmation by decoding transactions from the Polygon mempool. Use status: "all" to receive both.

V1 vs V2: Every order_filled event has a version field (1 or 2). V2 trades add builder and metadata fields (bytes32 hex, currently zero). fee_refund events are V1-only - V2 emits net fees directly on order_filled (no refund flow). See the V2 Migration Guide.

Event Types

Event	Description
`order_filled`	An order was filled on-chain
`fee_refund`	A maker fee rebate was processed

order_filled

{
  "type": "event",
  "subscription_id": "sub_2f4b15b33798",
  "data": {
    "status": "confirmed",
    "event_type": "order_filled",
    "token_id": "61192765571543...",
    "token_label": "Up",
    "side": "SELL", 
    "market_slug": "btc-updown-15m-1770244200",
    "condition_id": "0x04f954e4f30f...",
    "shares": 2000000,
    "shares_normalized": 2, 
    "price": 0.04, 
    "tx_hash": "0xf30a29f249...",
    "log_index": "0x21e",
    "title": "Bitcoin Up or Down - February 4, 5:30PM-5:45PM ET",
    "timestamp": 1770244731,
    "order_hash": "0x8bf54f44e5d7...",
    "user": "0xe9cbb1c9b3f7f411...", 
    "taker": "0x98f36c3d6300b905...",
    "role": "maker", 
    "outcome": "Up",
    "outcome_index": 0,
    "complement_token_id": "9876543210...",
    "complement_token_label": "Down",
    "is_neg_risk": false,
    "market_id": "1329542",
    "image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/BTC+fullsize.png",
    "fee": 0.008,
    "version": 2,
    "builder": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "metadata": "0x0000000000000000000000000000000000000000000000000000000000000000"
  }
}

Field Reference

Hide Trade fields

Field	Type	Description
`status`	`"pending"` \| `"confirmed"`	Event source - see Pending Trades
`event_type`	`"order_filled"`
`user`	string	Maker address (order placer)
`taker`	string	Taker address (order filler) - equals an exchange contract address on `taker`-role rows
`role`	`"maker"` \| `"taker"`	Which OrderFilled emission this is. See Maker vs Taker emissions
`side`	`"BUY"` \| `"SELL"`	Maker’s side of the trade
`price`	number	Execution price in USDC per share
`shares`	number	Raw share amount (6 decimal places)
`shares_normalized`	number	Human-readable share amount
`fee`	number	Fee charged in USDC
`version`	number	`1` for V1 contracts, `2` for V2 contracts
`builder`	string \| null	bytes32 hex tag (V2 only, currently zero)
`metadata`	string \| null	bytes32 hex tag (V2 only, currently zero)

Show Market metadata

Field	Type	Description
`token_id`	string	Outcome token ID
`token_label`	string \| null	Outcome label (e.g. “Yes”, “Up”)
`outcome`	string \| null	Same as `token_label`
`outcome_index`	number \| null	`0` = first outcome (Yes/Up), `1` = second (No/Down)
`complement_token_id`	string \| null	Token ID of the opposite outcome
`complement_token_label`	string \| null	Label of the opposite outcome
`is_neg_risk`	boolean \| null	`true` for neg-risk markets
`condition_id`	string \| null	Market condition ID
`market_slug`	string	Market URL slug
`market_id`	string \| null	Internal market ID
`title`	string \| null	Market title
`image`	string \| null	Market image URL

Show Transaction fields

Field	Type	Description
`order_hash`	string \| null	Order hash
`tx_hash`	string	Transaction hash
`log_index`	string \| null	Log index within the transaction (hex)
`timestamp`	number	Unix timestamp in seconds

Maker vs Taker emissions

A single matchOrders transaction emits multiple order_filled events - one per maker matched, plus one synthetic taker-aggregate emission summarizing the taker’s overall fill. The role field tells you which one you’re looking at:

`role`	Description	When to use
`"maker"`	Per-maker fill. One row per maker order matched in the tx. `taker` is the real taker user address.	Default for almost all use cases - counting fills, attributing volume to maker wallets, copytrading specific makers.
`"taker"`	Synthetic taker-aggregate. One row per `matchOrders` tx, summing across all makers. `taker` equals the exchange contract address.	Use when you want one row per taker action - e.g. dashboards keyed on the taker, or to avoid double-counting volume across the per-maker rows.

Pending events set role directly from the maker/taker builder; confirmed events derive it from the chain log (taker == exchange contract ⇒ "taker", else "maker"). Empirically the two agree 100%, so you can dedupe pending → confirmed by tx_hash + order_hash regardless of role.

Don’t sum volume across both roles - the taker-aggregate row covers the same shares as the per-maker rows. Pick one set: filter on role === "maker" for maker-attribution, or role === "taker" for taker-attribution.

fee_refund

fee_refund events are emitted for V1 trades only. V2 has no refund flow - the net fee is emitted directly on order_filled at match time.

Emitted when a maker fee rebate is processed on-chain.

{
  "type": "event",
  "subscription_id": "sub_2f4b15b33798",
  "data": {
    "event_type": "fee_refund",
    "user": "0x47a51f21d742...",
    "token_id": "53031995840519...",
    "condition_id": "0xdfb2f9d3ed88...",
    "market_slug": "btc-updown-15m-1770242400",
    "title": "Bitcoin Up or Down - February 4, 5:00PM-5:15PM ET",
    "order_hash": "0xbda8ab86c90f...", 
    "tx_hash": "0x97b2ae331881...",
    "refund": 9.9904, 
    "fee_charged": 0.0096
  }
}

Show Field reference

Field	Type	Description
`event_type`	`"fee_refund"`
`user`	string	Address that received the refund
`token_id`	string	Outcome token ID
`condition_id`	string \| null	Market condition ID
`market_slug`	string \| null	Market URL slug
`title`	string \| null	Market title
`order_hash`	string	The order hash this refund applies to
`tx_hash`	string	Transaction hash
`refund`	number	USDC amount refunded to the maker
`fee_charged`	number	Final net fee after refund

Understanding Fee Refunds

Polymarket implements a maker fee rebate program. Here’s how it works:

Trade executes

An order_filled event arrives with a fee field representing the gross fee charged.

Rebate processes

A fee_refund event for the same order_hash arrives 2–5ms later (same block, usually same tx). Rarely up to 50ms.

Calculate net fee

The maker’s actual net fee is fee_refund.fee_charged (or equivalently order_filled.fee - fee_refund.refund).

If you don’t need exact fee accounting, you can ignore fee_refund events. The fee field on order_filled is directionally correct for most purposes. Fee refunds are only necessary for precise PnL tracking or cost basis accounting.

Example: Processing Trades

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  if (msg.type === 'event') {
    const data = msg.data;

    if (data.event_type === 'order_filled') {
      const value = data.shares_normalized * data.price; 
      console.log(`${data.side} ${data.outcome} ${data.shares_normalized} @ ${data.price}`);
      console.log(`Market: ${data.title}`);
      console.log(`Value: $${value.toFixed(2)}`);
      console.log(`Maker: ${data.user}`);
      console.log(`Taker: ${data.taker}`);
    }

    if (data.event_type === 'fee_refund') {
      console.log(`Fee refund: $${data.refund} for order ${data.order_hash}`);
      console.log(`Net fee: $${data.fee_charged}`); 
    }
  }
};

Getting Started

Ticks

Markets

Discovery & Taxonomy

Pricing & Candles

Orderbooks

Trades

Activity & Positions

Wallet Identity

Wallet Positions & P&L

Smart Money & Leaderboards

Oracle & Settlement

Builders

Real-Time Signals (WebSocket)

Backtesting

Reference

Event Types

order_filled

Field Reference

Maker vs Taker emissions

fee_refund

Understanding Fee Refunds

Example: Processing Trades

​Event Types

​order_filled

​Field Reference

​Maker vs Taker emissions

​fee_refund

​Understanding Fee Refunds

​Example: Processing Trades

Event Types

order_filled

Field Reference

Maker vs Taker emissions

fee_refund

Understanding Fee Refunds

Example: Processing Trades