Skip to main content

Message Format

When a trade matches your subscription, you receive a message with type: "trade":
{
  "type": "trade",
  "subscription_id": "sub_a1b2c3d4",
  "data": {
    "platform": "polymarket",
    "asset_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
    "market_slug": "will-donald-trump-win-the-2024-us-presidential-election",
    "condition_id": "0x123...",
    "shares": 100.5,
    "shares_normalized": 100.5,
    "price": 0.65,
    "tx_hash": "0xabc...",
    "title": "Will Trump win the 2024 election?",
    "timestamp": 1704067200,
    "order_hash": "0xdef...",
    "user": "0x1234...",
    "taker": "0x5678...",
    "outcome": "Yes",
    "source": "alchemy"
  }
}

Field Reference

Identifiers

FieldTypeDescription
subscription_idstringWhich subscription matched this trade
asset_idstringToken ID for the outcome
condition_idstringMarket condition ID
market_slugstringURL-friendly market identifier
order_hashstringUnique order identifier
tx_hashstringEthereum transaction hash

Trade Details

FieldTypeDescription
sharesnumberNumber of shares traded
shares_normalizednumberShares normalized for display
pricenumberPrice per share (0.00 - 1.00)
outcomestringOutcome label (e.g., “Yes”, “No”)
timestampnumberUnix timestamp in seconds

Participants

FieldTypeDescription
userstringMaker address (order placer)
takerstringTaker address (order filler)

Metadata

FieldTypeDescription
platformstringAlways "polymarket"
titlestringMarket question/title
sourcestringData source identifier

Example: Processing Trades

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

  if (msg.type === 'trade') {
    const trade = msg.data;
    const value = trade.shares * trade.price;

    console.log(`${trade.outcome} ${trade.shares} @ ${trade.price}`);
    console.log(`Market: ${trade.title}`);
    console.log(`Value: $${value.toFixed(2)}`);
    console.log(`Maker: ${trade.user}`);
    console.log(`Taker: ${trade.taker}`);
  }
};

Filtering by Subscription

If you have multiple subscriptions, use subscription_id to determine which filter matched:
const subscriptions = {
  'sub_abc123': 'whale-tracker',
  'sub_def456': 'btc-markets'
};

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

  if (msg.type === 'trade') {
    const source = subscriptions[msg.subscription_id];
    console.log(`[${source}]`, msg.data.title, msg.data.price);
  }
};