PolyEdgePolyEdgev2

Mempool Stream API Guide

PolyEdge delivers real-time Polymarket pre-block mempool trade executions over standard HTTP/2 Server-Sent Events (SSE). Peered directly with validator P2P gossip networks, PolyEdge intercepts and streams trades the moment they are matched in the mempool before block confirmation.

Management Options: You can manage streams programmatically via the REST APIs documented below, or configure, monitor, and update them visually in the Console Streams interface.

This guide walks through the complete workflow: creating a stream configuration, establishing a persistent connection, updating filters dynamically without reconnecting, and tearing down the stream. To inspect all provisioned streams and active session counts under your account, refer to List User Streams (GET /streams).

1. Create Stream (POST /streams)

Register a stream configuration with your required target filters (such as trader wallet addresses, market tags, or series slugs):

curl -X POST "https://stream.polyedge.dev/streams" \
  -H "Content-Type: application/json" \
  -H "X-PolyEdge-Key: <YOUR_API_KEY>" \
  -d '{
    "name": "Production Copy-Trading Stream",
    "addresses": ["0x2005d16a84ceefa912d4e380cd32e7ff827875ea"],
    "tags": ["crypto", "politics"],
    "series": ["sol-up-or-down-5m"]
  }'

Successful Response (201 Created):

{
  "id": "e8f3b207-9b4e-4b77-a8d1-1376d8b67cf9",
  "name": "Production Copy-Trading Stream",
  "enabled": true,
  "addresses": ["0x2005d16a84ceefa912d4e380cd32e7ff827875ea"],
  "tags": ["crypto", "politics"],
  "series": ["sol-up-or-down-5m"],
  "active_sessions": 0,
  "created_at": "2026-09-25T20:55:27.788Z",
  "updated_at": "2026-09-25T20:55:27.788Z"
}

Save the returned id to connect to your live stream feed in the next step.

2. Connect Stream (GET /streams/{id})

Connect to the stream URL using any standard HTTP/2 client or SSE library (such as Node.js HTTP/2, Python httpx, Go net/http, or cURL):

curl -N "https://stream.polyedge.dev/streams/e8f3b207-9b4e-4b77-a8d1-1376d8b67cf9" \
  -H "X-PolyEdge-Key: <YOUR_API_KEY>"

Wire Format & Event Types

PolyEdge streams standard SSE frames:

  • event: tx: Emitted whenever a trade matching your filter is captured. The data line contains a JSON-encoded LiveTransaction payload:
    id: 4716111
event: tx
data: {"tx_hash":"0xcb9add...","timestamp":"2026-09-25T20:55:29.248Z","market":{...},"taker":{...},"makers":[...]}
  • : heartbeat: A comment frame sent every 30 seconds to maintain NAT gateway routing and keep TCP sockets active:
    : heartbeat

Keep-Alive & Reconnection: On active mempool SSE stream connections, the server sends a heartbeat every 30 seconds. If your client receives no trade data or heartbeats for over 60 seconds, gracefully disconnect the SSE session and reconnect.

3. Update Stream (PUT /streams/{id}/subscription)

PolyEdge supports zero-downtime dynamic filtering. You can add new smart-money wallets, change monitored market categories, or adjust series filters on the fly. Active listeners receive updates immediately without disconnecting or dropping trades:

curl -X PUT "https://stream.polyedge.dev/streams/e8f3b207-9b4e-4b77-a8d1-1376d8b67cf9/subscription" \
  -H "Content-Type: application/json" \
  -H "X-PolyEdge-Key: <YOUR_API_KEY>" \
  -d '{
    "addresses": [
      "0x2005d16a84ceefa912d4e380cd32e7ff827875ea",
      "0x592306c26c00c4d9ede9ee341aa39bb2782649cd"
    ],
    "tags": ["sports", "tennis", "crypto"],
    "series": ["itf"]
  }'

Successful Response (200 OK):

{
  "id": "e8f3b207-9b4e-4b77-a8d1-1376d8b67cf9",
  "name": "Production Copy-Trading Stream",
  "enabled": true,
  "addresses": [
    "0x2005d16a84ceefa912d4e380cd32e7ff827875ea",
    "0x592306c26c00c4d9ede9ee341aa39bb2782649cd"
  ],
  "tags": ["sports", "tennis", "crypto"],
  "series": ["itf"],
  "active_sessions": 1,
  "updated_at": "2026-09-25T20:56:02.124Z"
}

4. Delete Stream (DELETE /streams/{id})

When a stream configuration is no longer needed, delete it to release active session quota:

curl -X DELETE "https://stream.polyedge.dev/streams/e8f3b207-9b4e-4b77-a8d1-1376d8b67cf9" \
  -H "X-PolyEdge-Key: <YOUR_API_KEY>"

Successful Response (200 OK):

{
  "id": "e8f3b207-9b4e-4b77-a8d1-1376d8b67cf9"
}