Real-time streaming Polymarket prediction trades on Polygon (matic) with live USD pricing. Use this skill to subscribe to a live stream of Polymarket predict...
This skill gives you a real-time streaming Polymarket prediction trade feed over WebSocket on Polygon (matic). Every event is a successful prediction trade with outcome token amounts, collateral in USD, price in USD, buyer/seller addresses, market question, outcome label (e.g. "Up" / "Down"), and transaction hash.
Trades are filtered to TransactionStatus.Success: true. The stream uses Bitquery's EVM.PredictionTrades subscription so downstream code can build dashboards, track order flow, or monitor specific markets.
Official docs: Polymarket API — Get Prices, Trades & Market Data (Bitquery).
This skill's code implements the described Polymarket stream and contacts only Bitquery. Before installing:
BITQUERY_API_KEY as a required credential. The skill will fail at runtime without it. If the registry does not list this env var, the mismatch with this SKILL.md is the main inconsistency — ask the publisher to update the registry so installers see the requirement.?token=... and can appear in logs, shell history, or monitoring tools. Rotate the key if you suspect it was exposed during testing or use.BITQUERY_API_KEY and the source is validated, this skill is coherent with its stated purpose.BITQUERY_API_KEY (Bitquery API token).?token=...); Bitquery does not support header-based auth for this endpoint. Because the token appears in the URL, there is a higher risk of accidental exposure if the URL is printed or captured. Best practice: set BITQUERY_API_KEY in the environment, never log or print the full WebSocket URL, and rotate the key if you suspect exposure.BITQUERY_API_KEY — your Bitquery API token (required). Set it in your environment; the script and examples read it from there. The token is passed in the WebSocket URL only as ?token=... — do not print or log the full URL.pip. Install the dependency: pip install 'gql[websockets]'.These are the key reasons a trader would use this feed:
1. Order flow / market activity Monitor every filled order: buyer, seller, collateral in USD, price in USD, and outcome (Yes/No or Up/Down). Identify which markets are most active and which side (buy vs sell) is dominant.
2. Whale / large-trade detection
Filter by CollateralAmountInUSD or Amount to surface large prediction-market trades. Useful for following smart-money flow into specific outcomes.
3. Market-specific monitoring
Use Question.MarketId, Question.Title, or Question.Id to filter the stream to a single market (e.g. "Ethereum Up or Down - March 10") and track all trades for that market in real time.
4. Outcome imbalance
Aggregate trades by Outcome.Label (e.g. "Up" vs "Down") and IsOutcomeBuy to see net buying pressure per outcome — useful for sentiment or momentum.
5. Resolution source / data markets
Use Question.ResolutionSource and Question.Title to focus on data or oracle-driven markets (e.g. Chainlink streams) and monitor trading around resolution.
6. Entry / exit timing
Stream PriceInUSD and CollateralAmountInUSD per trade to see where size is trading and at what price — helps time entries and exits in prediction markets.
7. Protocol / marketplace verification
Marketplace.ProtocolName and ProtocolFamily (e.g. "polymarket", "Gnosis_CTF") confirm the trade is from Polymarket on Polygon; use to avoid mixing with other protocols.
8. Audit trail
Each event includes Transaction.Hash, Block.Time, Call.Signature.Name (e.g. "matchOrders"), and Log.Signature.Name (e.g. "OrderFilled") for full on-chain audit.
import os
api_key = os.getenv("BITQUERY_API_KEY")
if not api_key:
print("ERROR: BITQUERY_API_KEY environment variable is not set.")
print("Run: export BITQUERY_API_KEY=your_token")
exit(1)
If the key is missing, tell the user and stop. Do not proceed without it.
Install the WebSocket dependency once:
pip install 'gql[websockets]'
Use the streaming script:
python ~/.openclaw/skills/polymarket-prediction-trades/scripts/stream_polymarket.py
Optional: stop after N seconds:
python ~/.openclaw/skills/polymarket-prediction-trades/scripts/stream_polymarket.py --timeout 60
Or subscribe inline with Python:
import asyncio, os
from gql import Client, gql
from gql.transport.websockets import WebsocketsTransport
async def main():
token = os.environ["BITQUERY_API_KEY"]
url = f"wss://streaming.bitquery.io/graphql?token={token}"
transport = WebsocketsTransport(
url=url,
headers={"Sec-WebSocket-Protocol": "graphql-ws"},
)
async with Client(transport=transport) as session:
sub = gql("""
subscription MyQuery {
EVM(network: matic) {
PredictionTrades(where: { TransactionStatus: { Success: true } }) {
Block { Time }
Call { Signature { Name } }
Log { Signature { Name } SmartContract }
Trade {
OutcomeTrade {
Buyer
Seller
Amount
CollateralAmount
CollateralAmountInUSD
OrderId
Price
PriceInUSD
IsOutcomeBuy
}
Prediction {
CollateralToken { Name Symbol SmartContract AssetId }
ConditionId
OutcomeToken { Name Symbol SmartContract AssetId }
Marketplace { SmartContract ProtocolVersion ProtocolName ProtocolFamily }
Question { Title ResolutionSource Image MarketId Id CreatedAt }
Outcome { Id Index Label }
}
}
Transaction { From Hash }
}
}
}
""")
async for result in session.subscribe(sub):
for trade in (result.get("EVM") or {}).get("PredictionTrades") or []:
q = (trade.get("Trade") or {}).get("Prediction") or {}
q = q.get("Question") or {}
ot = (trade.get("Trade") or {}).get("OutcomeTrade") or {}
pred = (trade.get("Trade") or {}).get("Prediction") or {}
outcome = pred.get("Outcome") or {}
print(
f"{q.get('Title', '?')} | "
f"Outcome: {outcome.get('Label', '?')} | "
f"${float(ot.get('CollateralAmountInUSD') or 0):.2f}"
)
asyncio.run(main())
| Field | What it means for traders |
|---|---|
Trade.OutcomeTrade.Buyer | Taker buyer address |
Trade.OutcomeTrade.Seller | Maker seller address |
Trade.OutcomeTrade.Amount | Outcome token amount (raw) |
Trade.OutcomeTrade.CollateralAmount | Collateral token amount |
Trade.OutcomeTrade.CollateralAmountInUSD | Notional in USD — use for size/whale filter |
Trade.OutcomeTrade.OrderId | Order identifier |
Trade.OutcomeTrade.Price | Price in collateral (0–1 typical for binary) |
Trade.OutcomeTrade.PriceInUSD | Price in USD — entry/exit reference |
Trade.OutcomeTrade.IsOutcomeBuy | True = buyer bought the outcome (Yes/Up) |
Trade.Prediction.Question.Title | Market question (e.g. "Ethereum Up or Down - ...") |
Trade.Prediction.Question.MarketId | Market ID for filtering |
Trade.Prediction.Question.ResolutionSource | Resolution source (e.g. Chainlink URL) |
Trade.Prediction.Outcome.Label | Outcome label (e.g. "Up", "Down") |
Trade.Prediction.Marketplace.ProtocolName | e.g. "polymarket" |
Block.Time | Trade timestamp (ISO) |
Transaction.Hash | On-chain tx hash for audit |
Call.Signature.Name | e.g. "matchOrders" |
Log.Signature.Name | e.g. "OrderFilled" |
When presenting prediction trades to a trader, use this layout:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Polymarket [matic] Protocol: polymarket (Gnosis_CTF)
Time: 2026-03-10T13:21:11Z Tx: 0x9566...f2da
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Question: Ethereum Up or Down - March 10, 9:15AM-9:30AM ET
MarketId: 1537455 | Outcome: Down (Index 1)
Resolution: https://data.chain.link/streams/eth-usd
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
OutcomeTrade
Side: BUY outcome (IsOutcomeBuy: true)
Buyer: 0x22dc...91bb → Seller: 0x86a2...73a8
Collateral: 0.316471 USDC (USD: $0.32)
Price: 0.632942 (USD: $0.633)
Amount: 500000 (outcome tokens)
OrderId: 44433632...
Call: matchOrders | Log: OrderFilled @ 0x4bfb...982e
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
?token= only — do not pass the token in headers)TransactionStatus: { Success: true } and network is maticreferences/graphql-fields.md. Use it to add filters or request extra fields (e.g. by MarketId, ConditionId, or date) in the subscription.ZIP package — ready to use