polymarket-prediction-trades

Polymarket Prediction Trades — real-time streaming on Polygon

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).

---

What to consider before installing

This skill's code implements the described Polymarket stream and contacts only Bitquery. Before installing:

1. Registry metadata: Confirm the registry metadata declares 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.
2. Treat the API key as a secret: Set it in an environment variable only. Do not print or log the full WebSocket URL; the token is passed as ?token=... and can appear in logs, shell history, or monitoring tools. Rotate the key if you suspect it was exposed during testing or use.
3. Sandbox first: Run the bundled script in a sandboxed environment (e.g. virtualenv or container) to observe behavior before relying on it in production.
4. Verify publisher/source: If the skill's homepage or source is unknown, verify the publisher or use an alternative from a trusted source. If the registry declares BITQUERY_API_KEY and the source is validated, this skill is coherent with its stated purpose.
5. Rotate the key if exposed: If the key may have been exposed (e.g. URL printed, committed, or logged), rotate it in the Bitquery dashboard and update your environment.

---

Credentials

• Single required secret at runtime: BITQUERY_API_KEY (Bitquery API token).
• Registry: The registry metadata should declare this as the primary/required credential. If it does not, installers may not see that the skill needs an API key until they read this SKILL.md or run the script — that mismatch is the main inconsistency to fix on the registry side.
• Usage: The key must be passed in the WebSocket URL as a query parameter (?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.

---

Prerequisites

• Environment: 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.
• Runtime: Python 3 and pip. Install the dependency: pip install 'gql[websockets]'.

---

Trader Use Cases

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.

---

Step 1 — Check API Key

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.

---

Step 2 — Run the stream

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