Real-time stream

The stream endpoint delivers every matched Polymarket mempool transaction via Server-Sent Events (SSE), allowing you to see the market before it hits the chain. Each event contains the full transaction: market context, the taker order that triggered the fill, and all matching maker orders. Powered by a multi-node mempool synchronization engine, the system achieves a >99.99% delivery rate and streams live order flow up to 3-6 seconds faster than on-chain confirmations, with 10ms transaction awareness. Endpoint: GET /v1/stream/orders

Filter parameters

Apply filters to receive only the events relevant to your strategy. Omit a parameter to receive all values for that dimension.

Parameter	Type	Description
`traders`	string	Comma-separated wallet addresses. Only events where the taker or a maker matches will be delivered.
`tags`	string	Comma-separated market tags (e.g. `crypto,sports`).
`series`	string	Comma-separated series slugs (e.g. `nba-2026,btc-up-or-down-5m`).
`min_usdc` / `max_usdc`	float	Filter by USDC value of the taker order.
`min_shares` / `max_shares`	float	Filter by share quantity of the taker order.
`min_price` / `max_price`	float	Filter by execution price (0–100).
`format`	string	Set to `json` for structured JSON objects. Omit for the default compact array format.

Output formats

The stream supports two formats. Choose based on your throughput and parsing needs.

Compact array (default)
JSON (?format=json)

The default format serializes each transaction as a nested array. It is more compact and faster to transmit than equivalent JSON objects — ideal for high-frequency feeds.

[
  "0x39a4c634526de17a2f0e7e2834bcb0a044e909d7782887fcc24100a3a043a61f",
  "2026-06-18 03:18:20.068Z",
  [
    1694212,
    "Minnesota Lynx vs. Los Angeles Sparks: O/U 176.5",
    "wnba-min-la-2026-06-17-total-176pt5",
    "2026-06-17T04:31:05.891286Z",
    "2026-06-18T02:00:00Z",
    "https://polymarket-upload.s3.us-east-2.amazonaws.com/wnba-logo-PAR4befDAubM.png",
    false,
    "wnba-min-la-2026-06-17",
    "wnba",
    ["sports", "wnba", "games"],
    "Over",
    "Under",
    "O/U 176.5",
    "Minnesota Lynx vs. Los Angeles Sparks",
    "https://polymarket-upload.s3.us-east-2.amazonaws.com/wnba-logo-PAR4befDAubM.png"
  ],
  ["BUY", ["0x14e72e19ea2f6e2be41504dd3268184ebe5fa32c", "Negyedikaccount", "", "", "2026-05-26T20:17:22.279378Z"], "Under", "99169083723444391261088493561245365795535154938116614078681360075869499660270", "33000000", "50000000", "336600", "0"],
  [
    ["BUY", ["0xc29198ad764bd6adaf7bb971a3757a689ece5d74", "SnakeBall", "", "", "2026-02-14T23:54:51.615155Z"], "Over", "23731496537980602209118903433978041013300904286970617085197373043164590194158", "17000000", "50000000", "0", "0"]
  ]
]

The array positions map as follows:

Index	Field
`[0]`	Transaction hash
`[1]`	Timestamp
`[2]`	Market array (id, question, slug, start_date, end_date, icon, neg_risk, event_slug, series_slug, tags, outcome_1, outcome_2, group_item_title, event_title, event_icon)
`[3]`	Taker order array (side, trader array, outcome, token_id, usdc, shares, fee, fee_rate_bps)
`[4]`	Array of maker order arrays (same structure as taker)

Use the parser utilities to convert the compact array into a structured object.

Add ?format=json to receive fully-labelled JSON objects. Easier to work with directly, but higher byte overhead per event.

{
  "tx_hash": "0x0da9665e2dd6945f65ae6b11afe55aecdd24039dbcc5e1fadf776bcb9f8aa760",
  "timestamp": "2026-06-18 03:18:21.896Z",
  "market": {
    "id": "1681525",
    "question": "Will the highest temperature in Seoul be 28°C on June 18?",
    "slug": "highest-temperature-in-seoul-on-june-18-2026-28c",
    "start_date": "2026-06-16T04:10:33.362986Z",
    "end_date": "2026-06-18T12:00:00Z",
    "icon": "https://polymarket-upload.s3.us-east-2.amazonaws.com/highest-temperature-in-seoul-on-december-6-WzqtMeHg43n4.jpg",
    "neg_risk": true,
    "event_slug": "highest-temperature-in-seoul-on-june-18-2026",
    "series_slug": "seoul-daily-weather",
    "tags": [
      "weather",
      "recurring",
      "hide-from-new",
      "seoul",
      "daily-temperature",
      "highest-temperature"
    ],
    "outcome_1": "Yes",
    "outcome_2": "No",
    "group_item_title": "28°C",
    "event_title": "Highest temperature in Seoul on June 18?",
    "event_icon": "https://polymarket-upload.s3.us-east-2.amazonaws.com/highest-temperature-in-seoul-on-december-6-WzqtMeHg43n4.jpg",
    "resolved_at": "",
    "winning_outcome": ""
  },
  "taker_order": {
    "side": "BUY",
    "usdc": "15180000",
    "shares": "23000000",
    "trader": {
      "address": "0x2ef2f13f30e523197e9e66afa2f2620f02fbfaa5",
      "name": "usmaga",
      "x_username": "",
      "profile_image": "",
      "profile_created_at": "2026-03-02T06:23:07.41598Z"
    },
    "outcome": "No",
    "fee": "258060",
    "token_id": "64556817934163764870635868220841704981072426085805880644944019517839346202215",
    "fee_rate_bps": "0"
  },
  "maker_orders": [
    {
      "side": "BUY",
      "usdc": "4477800",
      "shares": "13170000",
      "trader": {
        "address": "0x4a2f4fc2f1e15e40b12348c5a7cbd9ca2d63e889",
        "name": "kysun72966",
        "x_username": "",
        "profile_image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/profile-image-8570042-f9ff72d3-1bd7-4171-a4fd-2b43ba1a01ac.png",
        "profile_created_at": "2026-06-11T13:16:54.926827Z"
      },
      "outcome": "Yes",
      "fee": "0",
      "token_id": "87434773403162723289170036946177437253639423627539401959815171394026097362935",
      "fee_rate_bps": "0"
    }
  ]
}

Parsing the compact format

The SDK parsers convert a raw compact array into the same shape as the JSON format response. Here is the complete parser code for both languages:

function parseCompactTrader(arr) {
  if (!arr || arr.length === 0) return null;
  return {
    address: arr[0],
    name: arr[1] || "",
    x_username: arr[2] || "",
    profile_image: arr[3] || "",
    profile_created_at: arr[4] || ""
  };
}

function parseCompactOrder(arr) {
  if (!arr || arr.length === 0) return null;
  return {
    side: arr[0],
    trader: parseCompactTrader(arr[1]),
    outcome: arr[2],
    tokenId: arr[3],
    usdc: arr[4],
    shares: arr[5],
    fee: arr[6],
    feeRateBps: arr[7]
  };
}

function parseCompactMarket(arr) {
  if (!arr || arr.length === 0) return null;
  return {
    id: arr[0],
    question: arr[1] || "",
    slug: arr[2] || "",
    start_date: arr[3] || "",
    end_date: arr[4] || "",
    icon: arr[5] || "",
    neg_risk: arr[6] || false,
    event_slug: arr[7] || "",
    series_slug: arr[8] || "",
    tags: arr[9] || [],
    outcome_1: arr[10] || "",
    outcome_2: arr[11] || "",
    group_item_title: arr[12] || "",
    event_title: arr[13] || "",
    event_icon: arr[14] || ""
  };
}

function parseCompactTx(arr) {
  if (!arr || arr.length !== 5) return null;

  const makers = [];
  if (Array.isArray(arr[4])) {
    for (const makerArr of arr[4]) {
      makers.push(parseCompactOrder(makerArr));
    }
  }

  return {
    txHash: arr[0],
    timestamp: arr[1],
    market: parseCompactMarket(arr[2]),
    takerOrder: parseCompactOrder(arr[3]),
    makerOrders: makers
  };
}

export default parseCompactTx;

def parse_compact_trader(arr):
    if not arr or len(arr) == 0:
        return None
    return {
        "address": arr[0],
        "name": arr[1] if len(arr) > 1 else "",
        "x_username": arr[2] if len(arr) > 2 else "",
        "profile_image": arr[3] if len(arr) > 3 else "",
        "profile_created_at": arr[4] if len(arr) > 4 else ""
    }

def parse_compact_order(arr):
    if not arr or len(arr) == 0:
        return None
    return {
        "side": arr[0],
        "trader": parse_compact_trader(arr[1]),
        "outcome": arr[2],
        "tokenId": arr[3],
        "usdc": arr[4],
        "shares": arr[5],
        "fee": arr[6] if len(arr) > 6 else "0",
        "feeRateBps": arr[7] if len(arr) > 7 else "0"
    }

def parse_compact_market(arr):
    if not arr or len(arr) == 0:
        return None
    return {
        "id": arr[0],
        "question": arr[1] if len(arr) > 1 else "",
        "slug": arr[2] if len(arr) > 2 else "",
        "start_date": arr[3] if len(arr) > 3 else "",
        "end_date": arr[4] if len(arr) > 4 else "",
        "icon": arr[5] if len(arr) > 5 else "",
        "neg_risk": arr[6] if len(arr) > 6 else False,
        "event_slug": arr[7] if len(arr) > 7 else "",
        "series_slug": arr[8] if len(arr) > 8 else "",
        "tags": arr[9] if len(arr) > 9 else [],
        "outcome_1": arr[10] if len(arr) > 10 else "",
        "outcome_2": arr[11] if len(arr) > 11 else "",
        "group_item_title": arr[12] if len(arr) > 12 else "",
        "event_title": arr[13] if len(arr) > 13 else "",
        "event_icon": arr[14] if len(arr) > 14 else ""
    }

def parse_compact_tx(arr):
    if not arr or len(arr) != 5:
        return None

    makers = []
    if isinstance(arr[4], list):
        for maker_arr in arr[4]:
            makers.append(parse_compact_order(maker_arr))

    return {
        "txHash": arr[0],
        "timestamp": arr[1],
        "market": parse_compact_market(arr[2]),
        "takerOrder": parse_compact_order(arr[3]),
        "makerOrders": makers
    }

Depending on the format you request, the properties in the final transaction object will have different casing:

Default (Compact Format): After running the compact array through the SDK’s parser, the output uses camelCase for top-level fields and specific order fields (such as txHash, takerOrder, tokenId, and feeRateBps).
JSON Format (?format=json): The raw API returns a structured object using snake_case for all fields (such as tx_hash, taker_order, token_id, and fee_rate_bps).

Here are the complete shapes for both formats:

Parsed Compact Object Shape (camelCase)
Raw JSON Object Shape (snake_case)

{
  "txHash": "0x39a4c634526de17a2f0e7e2834bcb0a044e909d7782887fcc24100a3a043a61f",
  "timestamp": "2026-06-18 03:18:20.068Z",
  "market": {
    "id": 1694212,
    "question": "Minnesota Lynx vs. Los Angeles Sparks: O/U 176.5",
    "slug": "wnba-min-la-2026-06-17-total-176pt5",
    "start_date": "2026-06-17T04:31:05.891286Z",
    "end_date": "2026-06-18T02:00:00Z",
    "icon": "https://polymarket-upload.s3.us-east-2.amazonaws.com/wnba-logo-PAR4befDAubM.png",
    "neg_risk": false,
    "event_slug": "wnba-min-la-2026-06-17",
    "series_slug": "wnba",
    "tags": ["sports", "wnba", "games"],
    "outcome_1": "Over",
    "outcome_2": "Under",
    "group_item_title": "O/U 176.5",
    "event_title": "Minnesota Lynx vs. Los Angeles Sparks",
    "event_icon": "https://polymarket-upload.s3.us-east-2.amazonaws.com/wnba-logo-PAR4befDAubM.png"
  },
  "takerOrder": {
    "side": "BUY",
    "trader": {
      "address": "0x14e72e19ea2f6e2be41504dd3268184ebe5fa32c",
      "name": "Negyedikaccount",
      "x_username": "",
      "profile_image": "",
      "profile_created_at": "2026-05-26T20:17:22.279378Z"
    },
    "outcome": "Under",
    "tokenId": "99169083723444391261088493561245365795535154938116614078681360075869499660270",
    "usdc": "33000000",
    "shares": "50000000",
    "fee": "336600",
    "feeRateBps": "0"
  },
  "makerOrders": [
    {
      "side": "BUY",
      "trader": {
        "address": "0xc29198ad764bd6adaf7bb971a3757a689ece5d74",
        "name": "SnakeBall",
        "x_username": "",
        "profile_image": "",
        "profile_created_at": "2026-02-14T23:54:51.615155Z"
      },
      "outcome": "Over",
      "tokenId": "23731496537980602209118903433978041013300904286970617085197373043164590194158",
      "usdc": "17000000",
      "shares": "50000000",
      "fee": "0",
      "feeRateBps": "0"
    }
  ]
}

{
  "tx_hash": "0x0da9665e2dd6945f65ae6b11afe55aecdd24039dbcc5e1fadf776bcb9f8aa760",
  "timestamp": "2026-06-18 03:18:21.896Z",
  "market": {
    "id": "1681525",
    "question": "Will the highest temperature in Seoul be 28°C on June 18?",
    "slug": "highest-temperature-in-seoul-on-june-18-2026-28c",
    "start_date": "2026-06-16T04:10:33.362986Z",
    "end_date": "2026-06-18T12:00:00Z",
    "icon": "https://polymarket-upload.s3.us-east-2.amazonaws.com/highest-temperature-in-seoul-on-december-6-WzqtMeHg43n4.jpg",
    "neg_risk": true,
    "event_slug": "highest-temperature-in-seoul-on-june-18-2026",
    "series_slug": "seoul-daily-weather",
    "tags": ["weather", "recurring", "hide-from-new", "seoul", "daily-temperature", "highest-temperature"],
    "outcome_1": "Yes",
    "outcome_2": "No",
    "group_item_title": "28°C",
    "event_title": "Highest temperature in Seoul on June 18?",
    "event_icon": "https://polymarket-upload.s3.us-east-2.amazonaws.com/highest-temperature-in-seoul-on-december-6-WzqtMeHg43n4.jpg",
    "resolved_at": "",
    "winning_outcome": ""
  },
  "taker_order": {
    "side": "BUY",
    "usdc": "15180000",
    "shares": "23000000",
    "trader": {
      "address": "0x2ef2f13f30e523197e9e66afa2f2620f02fbfaa5",
      "name": "usmaga",
      "x_username": "",
      "profile_image": "",
      "profile_created_at": "2026-03-02T06:23:07.41598Z"
    },
    "outcome": "No",
    "fee": "258060",
    "token_id": "64556817934163764870635868220841704981072426085805880644944019517839346202215",
    "fee_rate_bps": "0"
  },
  "maker_orders": [
    {
      "side": "BUY",
      "usdc": "4477800",
      "shares": "13170000",
      "trader": {
        "address": "0x4a2f4fc2f1e15e40b12348c5a7cbd9ca2d63e889",
        "name": "kysun72966",
        "x_username": "",
        "profile_image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/profile-image-8570042-f9ff72d3-1bd7-4171-a4fd-2b43ba1a01ac.png",
        "profile_created_at": "2026-06-11T13:16:54.926827Z"
      },
      "outcome": "Yes",
      "fee": "0",
      "token_id": "87434773403162723289170036946177437253639423627539401959815171394026097362935",
      "fee_rate_bps": "0"
    }
  ]
}

Connect and process events

Instantiate the client

Create a PolyEdgeClient with your API key. The SDK handles authentication via the X-PolyEdge-Key header on every request.

import PolyEdgeClient from './polyedge.js';

const client = new PolyEdgeClient('YOUR_API_KEY');

from polyedge import PolyEdgeClient

client = PolyEdgeClient('YOUR_API_KEY')

Open the stream

Call streamOrders() / stream_orders() with your filters. The Node.js SDK uses eventsource-client which auto-reconnects on dropped connections.

// Stream all crypto orders above $100 USDC
for await (const order of client.streamOrders({ tags: 'crypto', min_usdc: 100 })) {
  const taker = order.takerOrder;
  console.log(`${taker.side} ${taker.outcome} — $${Number(taker.usdc) / 1e6} USDC`);
}

# Stream all crypto orders above $100 USDC
for order in client.stream_orders({'tags': 'crypto', 'min_usdc': 100}):
    taker = order['takerOrder']
    usdc  = float(taker['usdc']) / 1e6
    print(f"{taker['side']} {taker['outcome']} — ${usdc:.2f} USDC")

Process each event

Each yielded order object is already parsed by the SDK. Access order.market, order.takerOrder, and order.makerOrders directly.

for await (const order of client.streamOrders({ tags: 'sports', min_usdc: 500 })) {
  const { market, takerOrder, makerOrders } = order;

  console.log(`[${order.timestamp}] ${market.question}`);
  console.log(`  Taker: ${takerOrder.trader?.name} ${takerOrder.side} ${takerOrder.outcome}`);
  console.log(`  USDC: $${Number(takerOrder.usdc) / 1e6} | Shares: ${Number(takerOrder.shares) / 1e6}`);
  console.log(`  Filled by ${makerOrders.length} maker order(s)`);
}

for order in client.stream_orders({'tags': 'sports', 'min_usdc': 500}):
    market      = order['market']
    taker       = order['takerOrder']
    maker_count = len(order['makerOrders'])

    usdc   = float(taker['usdc'])   / 1e6
    shares = float(taker['shares']) / 1e6

    print(f"[{order['timestamp']}] {market['question']}")
    print(f"  Taker: {taker['trader']['name']} {taker['side']} {taker['outcome']}")
    print(f"  USDC: ${usdc:.2f} | Shares: {shares:.2f}")
    print(f"  Filled by {maker_count} maker order(s)")

Handle disconnections

The Node.js SDK auto-reconnects via eventsource-client. In Python, wrap your loop in a try/except and re-enter the loop to reconnect.

reconnect.py

import time

while True:
    try:
        for order in client.stream_orders({'tags': 'crypto'}):
            process(order)
    except Exception as e:
        print(f"Stream disconnected: {e}. Reconnecting in 2s...")
        time.sleep(2)

The SSE event name sent by the PolyEdge API is order. The SDK already filters on this event name for you, so non-order events (heartbeats, etc.) are silently dropped.

Get Started

Guides

SDKs

Filter parameters

Output formats

Parsing the compact format

Connect and process events

​Filter parameters

​Output formats

​Parsing the compact format

​Connect and process events

Filter parameters

Output formats

Parsing the compact format

Connect and process events