The trades channel ("orders") streams real-time trade events from Polymarket. By default, you receive confirmed events — trades that have been mined on-chain.
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. Event Types Event Description order_filledAn order was filled on-chain fee_refundA 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..." , "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 } }
Field Reference Field Type Description status"pending" | "confirmed"Event source — see Pending Trades event_type"order_filled"userstring Maker address (order placer) takerstring Taker address (order filler) side"BUY" | "SELL"Maker’s side of the trade pricenumber Execution price in USDC per share sharesnumber Raw share amount (6 decimal places) shares_normalizednumber Human-readable share amount feenumber Fee charged in USDC
Field Type Description token_idstring Outcome token ID token_labelstring | null Outcome label (e.g. “Yes”, “Up”) outcomestring | null Same as token_label outcome_indexnumber | null 0 = first outcome (Yes/Up), 1 = second (No/Down)complement_token_idstring | null Token ID of the opposite outcome complement_token_labelstring | null Label of the opposite outcome is_neg_riskboolean | null true for neg-risk marketscondition_idstring | null Market condition ID market_slugstring Market URL slug market_idstring | null Internal market ID titlestring | null Market title imagestring | null Market image URL
Field Type Description order_hashstring | null Order hash tx_hashstring Transaction hash log_indexstring | null Log index within the transaction (hex) timestampnumber Unix timestamp in seconds
fee_refund 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 } }
Field Type Description event_type"fee_refund"userstring Address that received the refund token_idstring Outcome token ID condition_idstring | null Market condition ID market_slugstring | null Market URL slug titlestring | null Market title order_hashstring The order hash this refund applies to tx_hashstring Transaction hash refundnumber USDC amount refunded to the maker fee_chargednumber 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 } ` ); } } };
