prediction-markets

name	prediction-markets
description	Use when the user asks about event probabilities, prediction market odds, what people are betting on, Polymarket/Kalshi prices, sports markets — or about the things you CANNOT get from a public API: historical price/volume/orderbook time series, smart-money positioning, whale leaderboards, wallet P&L, wallet identity and on-chain clustering, and canonical IDs matching the same question across venues. 55 endpoints over Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, Binance Futures, sports, and the UMA oracle. Pay-per-call in USDC via x402 — no Predexon account, no API key.
triggers	["polymarket","kalshi","limitless","predict.fun","predexon","prediction market","event probability","betting odds","implied probability","what are people betting on","election odds","crypto market odds","binance futures","yes/no market","sports markets","smart money","smart wallet","whale","top traders","top holders","who is winning","best traders","copy trade","leaderboard","wallet pnl","wallet profit","trader performance","wallet identity","wallet cluster","price history","candles","candlestick","ohlcv","orderbook","order book history","open interest","volume history","trade history","cross-venue markets","arbitrage","uma oracle"]

Prediction Markets (Predexon)

55 endpoints across Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, Binance Futures, sports, and the UMA oracle — one x402 gateway, no Predexon account or API key.

What is worth paying for. Current market lists are free from public APIs. These are not, and cannot be backfilled after the fact:

• History — candlesticks, orderbook snapshots, volume charts, open interest, trade history. Built from continuous ingestion; nobody can reconstruct it retroactively.
• Smart money — leaderboards, cohort stats, top holders, which wallets are positioned where, and which markets high-performing wallets just entered.
• Wallet intelligence — profiles, P&L time series, identity metadata, and on-chain clustering (find the other wallets behind one address).
• Cross-venue canonical IDs — one question, matched across five venues. The basis for arbitrage and consensus.

How to Call from MCP

One tool, three params. Method auto-routes: POST when body is set, GET otherwise.

blockrun_markets({ path: "polymarket/events", params: { limit: "10" } })

blockrun_markets({ path: "polymarket/candlesticks/0xCONDITION_ID", params: { interval: "1440" } })

blockrun_markets({ path: "polymarket/wallet/identities", body: {
  addresses: ["0xabc...", "0xdef..."]
}})

Paths are relative — no /api/v1/pm/ prefix. Use agent_id to bill a child agent's budget.

Paid calls can run in parallel on Base: each EIP-3009 authorization carries its own random nonce, so concurrent calls from one wallet cannot collide. The Solana payload has no nonce field — distinctness comes from the SDK (@blockrun/llm >= 3.8.4), so keep that floor if you fan out on Solana.

Current parameter contracts that prevent paid 4xx responses:

• Discover with markets/search (its search term is q), then resolve the selected market with polymarket/markets/keyset + condition_id.
• On polymarket/markets{,/keyset} the free-text filter is search, not q. Use status:"open" rather than Gamma's active/closed, and sort rather than order/ascending. end_after/end_before are supported (Unix seconds).
• Candlestick interval is integer minutes (1440, not 1h) and is optional — the server has a default. Which intervals a market can serve varies: 1440 may work where 60 returns a paid 400. Optional start_time/end_time are Unix seconds.
• polymarket/orderbooks requires token_id, start_time, and end_time; the times are Unix milliseconds.
• Smart-money needs a smart-wallet criterion: min_trades, min_volume, min_roi, min_realized_pnl, min_total_pnl, min_win_rate, or min_profit_factor. window only scopes the time range and is not sufficient alone (verified: window-only returns a paid 400). Use { window: "30d", min_trades: "100" }; narrower cohorts are fine.
• markets/listings is retired upstream (410 Gone) — the MCP blocks it before payment.

Two Pricing Tiers

Tier	Price	What
All endpoints	$0.0085	Market data, events, history, candles, orderbooks, trades, leaderboard, sports, UMA, wallet analytics, smart money, identity + clustering, cross-venue matching, Binance

Pass-through pricing, 0% BlockRun margin — settles straight to Predexon's Base treasury.

Quick Decision Table — "User asks about X"

User wants…	path	Tier
Same question across venues	markets	1
Search every venue at once	markets/search	2
Resolve a canonical outcome ID	outcomes/{predexon_id}	1
Equivalent markets (arbitrage)	matching-markets	2
Active matched pairs	matching-markets/pairs	2
Active Polymarket events	polymarket/events	1
Polymarket markets	polymarket/markets	1
Large result sets (stable paging)	polymarket/markets/keyset	1
Crypto up/down markets	polymarket/crypto-updown	1
Current/historical price of a token	polymarket/market-price/{token_id}	1
Price history (OHLCV)	polymarket/candlesticks/{condition_id}	1
OHLCV for one outcome	polymarket/candlesticks/token/{token_id}	1
Volume over time (YES/NO split)	polymarket/volume-chart/{condition_id}	1
Historical orderbook snapshots	polymarket/orderbooks	1
Historical trades	polymarket/trades	1
Merges / splits / redeems for a user	polymarket/activity	1
Cumulative volume for a market	polymarket/markets/{token_id}/volume	1
Open interest history	polymarket/markets/{condition_id}/open_interest

Worked Examples

1. "What are people betting on right now?"

blockrun_markets({ path: "polymarket/events", params: { limit: "10" } })

2. "What's the market saying about the 2028 election?"

Search every venue in one call, then resolve the canonical outcome.

blockrun_markets({ path: "markets/search", params: { q: "2028 presidential election" } })
blockrun_markets({ path: "outcomes/PXM-12345" })   // → venue listings + prices side by side

3. "Show me this market's price history" (impossible from a free API)

blockrun_markets({ path: "polymarket/candlesticks/0xCONDITION_ID", params: {
  interval: "1440", start_time: "<UNIX_SECONDS>", end_time: "<UNIX_SECONDS>"
} })
blockrun_markets({ path: "polymarket/volume-chart/0xCONDITION_ID" })
blockrun_markets({ path: "polymarket/markets/0xCONDITION_ID/open_interest" })
blockrun_markets({ path: "polymarket/orderbooks", params: {
  token_id: "<TOKEN_ID>", start_time: "<UNIX_MILLISECONDS>", end_time: "<UNIX_MILLISECONDS>"
} })

4. "Who's smart money betting on in this market?" ← compound

Positioning → then profile the wallets behind it.

// 1. Which high-performing wallets are in this market, and on which side
blockrun_markets({ path: "polymarket/market/0xCONDITION_ID/smart-money", params: {
  window: "30d", min_trades: "100"
} })

// 2. Profile the top wallet it returns — win rate, P&L, style
blockrun_markets({ path: "polymarket/wallet/0xWHALE" })

// 3. What else are they in right now?
blockrun_markets({ path: "polymarket/wallet/positions/0xWHALE" })

5. "This whale is up 400% — who are they really?" ← compound

Identity plus the on-chain cluster: one trader often runs many wallets.

blockrun_markets({ path: "polymarket/wallet/identity/0xWHALE" })        // ENS, socials, portfolio
blockrun_markets({ path: "polymarket/wallet/0xWHALE/cluster" })         // linked wallets + confidence
blockrun_markets({ path: "polymarket/wallet/pnl/0xWHALE" })             // realized P&L series
blockrun_markets({ path: "polymarket/wallet/0xWHALE/similar" })         // who trades like them

6. "Find me something to copy-trade" ← compound

blockrun_markets({ path: "polymarket/leaderboard", params: { limit: "20" } })   // best wallets
blockrun_markets({ path: "polymarket/markets/smart-activity" })                 // where they just moved
blockrun_markets({ path: "polymarket/cohorts/stats" })                          // which style is working

Then trade it with blockrun_polymarket (see skills/polymarket-trading/SKILL.md). Real money — always dry-run first.

7. "Is the same bet cheaper on another venue?" ← arbitrage

blockrun_markets({ path: "matching-markets", params: { status: "active" } })
blockrun_markets({ path: "matching-markets/pairs" })

8. "Who's ahead in tonight's NBA games?"

blockrun_markets({ path: "sports/markets", params: { league: "NBA", status: "open" } })
blockrun_markets({ path: "sports/markets/GAME_ID" })   // every venue's price for that game

9. "Is this market about to resolve?"

blockrun_markets({ path: "polymarket/uma/markets", params: { state: "proposed" } })
blockrun_markets({ path: "polymarket/uma/market/0xCONDITION_ID" })   // dispute timeline

Method Routing — When to Use body

Almost everything is GET → use params. Only bulk identity takes a body:

blockrun_markets({ path: "polymarket/wallet/identities", body: { addresses: ["0x1", "0x2"] } })

Paging Large Result Sets

Prefer keyset over offset — stable across writes, faster on big tables.

const p1 = blockrun_markets({ path: "polymarket/markets/keyset", params: { limit: "100" } })
// then pass the returned pagination.next_key back in:
blockrun_markets({ path: "polymarket/markets/keyset", params: { limit: "100", pagination_key: "<next_key>" } })

polymarket/events/keyset works the same way.

Notes on Response Shape

Predexon returns raw upstream responses; shape varies by venue.

• Polymarket — usually { data: [...] } or { events: [...] }
• Kalshi — usually { markets: [...] } with ticker, yes_bid, no_bid. Tickers look like KXBTC-25MAR14 (series + expiry).
• Canonical v2 — { markets: [...] } with predexon_id + venue_listings
• Print the raw response when exploring a path you have not used before.

Prices are probabilities 0–1. 0.62 means the market implies 62%.

Python SDK (for non-MCP use)

Inside the MCP, use blockrun_markets above. For standalone scripts:

from blockrun_llm import setup_agent_wallet   # setup_agent_solana_wallet() on Solana
client = setup_agent_wallet()

client.pm("polymarket/candlesticks/0xCONDITION_ID", interval="1440")
client.pm_query("polymarket/wallet/identities", {"addresses": ["0xabc"]})

Requires pip install blockrun-llm and a funded USDC wallet (client.get_balance()).