predictfun-mcp
The predictfun-mcp server provides AI agents with structured access to Predict.fun, a BNB Chain prediction market protocol, enabling analysis of trading activity, market data, positions, and yield mechanics through 14 tools across three specialized subgraphs.
Platform Analytics – Retrieve platform-wide stats including total volume, trade count, open interest, yield figures, and active market count.
Top Markets – List highest-ranked prediction markets sorted by volume, open interest, or trade count (up to 50 results).
Market Details – Deep dive into a specific market by ID, including volume, open interest, resolution status, recent trades, and top holders.
Trader Profiles – Look up a wallet address for full trading history, open positions, P&L, and reward claims.
Leaderboard – Rank top traders by volume, payouts, or trade count.
Recent Activity – Fetch latest platform events filtered by type: trades, splits, merges, redemptions, or yield claims.
Yield Mechanics – Analyze Venus Protocol integration including deposits, redemptions, net balances, yield claims, and token mappings.
Whale Tracking – Identify the largest position holders across all markets, filterable by minimum position size.
Resolved Markets – Browse recently settled markets with their outcomes and payout information.
Custom GraphQL Queries – Execute arbitrary queries against any of the three subgraphs (orderbook, positions, yield) for tailored data retrieval.
Behavioral Analysis (AI meta-tools) – Classify traders into archetypes (whale accumulator, yield farmer, arbitrageur, etc.) and scan for specific behavioral patterns.
Market Structure Analysis (AI meta-tools) – Tag markets by resolution latency, liquidity profile, oracle type, and tail-risk indicators, then filter markets by these structural characteristics.
Pre-built Workflows – 9 pre-configured prompts for common tasks like platform overviews, trader analysis, market deep dives, and yield analysis.
Provides structured access to Predict.fun's prediction market protocol on the BNB Chain, enabling AI agents to track market volume, open interest, trader profiles, and yield-bearing mechanics.
Enables custom GraphQL queries against specialized subgraphs to retrieve detailed blockchain data for prediction markets, including orderbook activity, user positions, and reward distributions.
Predict.fun Subgraphs
A suite of three subgraphs indexing Predict.fun — a prediction market protocol on BNB Chain (Polymarket fork) with $1.7B+ volume and novel yield-bearing mechanics via Venus Protocol.
Subgraphs
1. predictfun-orderbook
Indexes orderbook activity across all CTF and NegRisk exchanges.
Entities: Markets, Orderbooks, OrderFilled/Matched/Cancelled events, Fee tracking, Account stats, NegRisk markets, TradeData timeseries with hourly/daily aggregations
Contracts:
Contract | Address |
CTFExchange (Non-Yield) |
|
CTFExchange (Yield) |
|
NegRiskCtfExchange (Non-Yield) |
|
NegRiskCtfExchange (Yield) |
|
NegRiskAdapter (Non-Yield) |
|
NegRiskAdapter (Yield) |
|
+ 4 Fee Module contracts |
2. predictfun-positions
Indexes position lifecycle — splits, merges, redemptions, and open interest tracking.
Entities: Conditions, UserPositions, MarketOpenInterest, Split/Merge/Redemption events, NegRisk conversions, TransferSingle events
Contracts:
Contract | Address |
ConditionalTokens (Non-Yield) |
|
ConditionalTokens (Yield) |
|
NegRisk ConditionalTokens (Yield) |
|
NegRiskAdapter (Non-Yield) |
|
NegRiskAdapter (Yield) |
|
NegRiskOperator (Yield) |
|
NegRiskOperator (Non-Yield) |
|
3. predictfun-yield
Indexes Predict.fun's novel yield-bearing mechanics — Venus Protocol integration, reward distributions, and UMA oracle resolution.
Entities: TokenMappings (underlying/vToken pairs), YieldClaims, VTokenMints, RewardRounds, OracleRequests/Proposals/Settlements
Contracts:
Contract | Address |
YieldBearingConditionalTokens |
|
RewardDistributor |
|
UMA Optimistic Oracle |
|
Related MCP server: graph-polymarket-mcp
Architecture
predict.fun (BNB Chain)
├── predictfun-orderbook ── Fills, matches, fees, market registration
├── predictfun-positions ── Splits, merges, redemptions, open interest
└── predictfun-yield ── Venus yield, reward claims, oracle resolutionAll subgraphs share:
Network: BSC (BNB Smart Chain)
Collateral: USDT (18 decimals)
Start Block: 64,817,753
Spec Version: 1.3.0
Best Practices Applied
Bytes!IDs everywhere (cheaper thanString!)@entity(immutable: true)on all event logs@derivedFromfor reverse lookups (no redundant storage)No
eth_calls(events only)indexerHints: prune: autofor storage efficiencynonFatalErrorsfeature enabledconcatI32(logIndex)for unique event IDs
MCP Server
An MCP (Model Context Protocol) server that gives AI agents structured access to all three subgraphs.
Setup
Get a Graph API key from Subgraph Studio (docs)
Add to your Claude Code config (
~/.claude/settings.json):
{
"mcpServers": {
"predictfun": {
"command": "npx",
"args": ["predictfun-mcp"],
"env": {
"GRAPH_API_KEY": "your-api-key-here"
}
}
}
}Subgraph IDs are built in. Queries go through The Graph Gateway and are billed to your API key.
OpenClaw / Remote Agents (SSE)
# Dual transport — stdio + SSE on port 3850
GRAPH_API_KEY=your-key npx predictfun-mcp --http
# SSE only (for remote/server deployments)
GRAPH_API_KEY=your-key npx predictfun-mcp --http-only
# Custom port
MCP_HTTP_PORT=4000 GRAPH_API_KEY=your-key npx predictfun-mcp --httpPoint your agent at: http://localhost:3850/sse
Invocation | Transports | Use case |
| stdio | Claude Desktop, Cursor, Claude Code |
| stdio + SSE :3850 | Dual — local + remote agents |
| SSE :3850 | OpenClaw, remote deployments |
Tools (14)
Data Tools
Tool | Description |
| Full platform overview — volume, OI, yield, sync status |
| Rank markets by volume, open interest, or trade count |
| Deep dive: OI, resolution, top holders, orderbook stats |
| Full P&L: trades, positions, payouts, yield rewards |
| Latest trades, splits, merges, redemptions, or yield claims |
| Venus Protocol deposits, redemptions, yield stats |
| Largest holders with % of market OI |
| Top traders by volume, payouts, or trade count |
| Recently settled markets with outcomes |
| Custom GraphQL against any subgraph |
Meta-Tools (agent reasoning layer)
Tool | Description |
| Classify a trader into archetypes: whale accumulator, yield farmer, arbitrageur, early mover, resolution sniper |
| Find traders matching a specific behavioral archetype across the platform |
| Tag a market by resolution latency, liquidity profile, oracle type, and tail-risk indicators |
| Find markets by structural filter: resolution speed, liquidity depth, oracle type, OI concentration, tail risk |
Meta-tools return structured JSON so agents can reason programmatically over trader behavior and market quality — not just raw volume and OI.
Prompts (9)
Pre-built workflows: platform_overview, analyze_trader, market_deep_dive, yield_analysis, whale_alert, market_scanner, custom_query_examples, trader_persona_analysis, market_quality_scan
Subgraph Development
cd predictfun-<subgraph>
npm install
npx graph codegen
npx graph build
npx graph deploy predictfun-<subgraph> --version-label v0.0.1License
MIT
Available Tools
15 toolsfind_trader_personaA
Classify a trader into behavioral archetypes: whale_accumulator, yield_farmer, arbitrageur, early_mover, or resolution_sniper. Returns structured JSON with matched personas and supporting metrics.
Inputs: address (required).
get_leaderboardA
Get the top traders on Predict.fun by volume, P&L, or trade count
Inputs: rank_by, limit.
get_market_detailsB
Get full details for a specific market/condition: volume, OI, resolution status, recent trades, top holders
Inputs: condition_id (required).
get_market_orderbookA
Get the live order book for a Predict.fun market — current bids and asks with prices and sizes. Requires PREDICT_API_KEY. Provide market_id (integer from Predict.fun API) or condition_id. Use this to see the current state of the market, not historical trades.
Inputs: condition_id, market_id.
get_platform_statsA
Get Predict.fun platform-wide stats: total volume, trades, open interest, yield, and active markets
Inputs: no named parameters.
get_recent_activityC
Get recent activity on Predict.fun: latest trades, splits, merges, redemptions, or yield events
Inputs: event_type (required), limit.
get_resolved_marketsB
Get recently resolved markets with their outcomes and payout info
Inputs: limit.
get_top_marketsA
Get the top prediction markets ranked by volume, open interest, or trade count
Inputs: rank_by, limit.
get_trader_profileB
Get a trader's full profile: trading history, positions, P&L, and reward claims
Inputs: address (required).
get_whale_positionsB
Find the largest position holders across all Predict.fun markets
Inputs: limit, min_position.
get_yield_overviewA
Get Venus Protocol yield stats: deposits, redemptions, net balance, yield claims, and token mappings
Inputs: no named parameters.
query_subgraphA
Run a custom GraphQL query against any Predict.fun subgraph. Use this for advanced queries not covered by other tools.
Inputs: subgraph (required), graphql_query (required).
scan_markets_by_structureB
Find markets matching structural criteria: resolution speed, liquidity depth, oracle type, or tail-risk flags. Returns structured JSON.
Inputs: filter (required), resolved_only, limit.
scan_trader_personasB
Find traders matching a specific behavioral archetype across the platform. Returns structured JSON with matching traders and evidence.
Inputs: persona (required), limit.
tag_market_structureB
Classify a market by structural features: resolution latency, liquidity profile, oracle type, and tail-risk indicators. Returns structured JSON.
Inputs: condition_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools have distinct purposes (e.g., get_market_orderbook vs get_market_details), but some overlap exists between get_leaderboard and get_whale_positions (both rank traders) and between find_trader_persona and scan_trader_personas (both deal with personas). Descriptions help differentiate, but slight ambiguity remains.
All names use snake_case and follow a verb_noun pattern, but verbs vary: get (9 tools), scan (2), find (1), tag (1), query (1). While each verb is semantically appropriate, the mix deviates from a strict pattern. Minor inconsistency.
15 tools is within the optimal range for a domain-specific server covering prediction markets and yield. Each tool serves a clear purpose without excessive redundancy, and the count feels well-scoped for the intended functionality.
The tool set covers core read operations: markets (details, top, resolved, orderbook), traders (profile, leaderboard, whale positions, personas), platform stats, and activity. The query_subgraph tool fills any gaps, making the surface effectively complete for a data-querying server.
Maintenance
Related MCP Connectors
Historical tick, order book and settlement data for Polymarket and Predict.fun crypto up/down markets, plus smart-money lists and backtest quotes, over a read-only MCP server.
Polymarket MCP — prediction-market data via Gamma + CLOB + Data public APIs.
Pay-per-call DeFi and macro intel for AI agents. x402 USDC tools via streamable HTTP /api/mcp.
Pay-per-call ($0.005-$0.03 USDC) market, on-chain, and prediction-market data API for AI agents and trading bots via x402 — no signup, no API key. Remote MCP server, 28 tools: token security (honeypot/liquidity/counterfeit checks), Hyperliquid oracle-gap risk, kimchi premium, funding APR, DEX slippage, Polymarket arbitrage/liquidity audits, Hyperliquid HIP-4 odds.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that powers AI agents with indexed blockchain data from The Graph.3MIT
- AlicenseBqualityCmaintenanceAn MCP server that enables querying Polymarket prediction market data through The Graph subgraphs. It provides tools for accessing market stats, trader P\&L, user positions, and orderbook activity using AI agents.35101 npm4MIT
- AlicenseNot gradedqualityDmaintenanceReal-time prediction market intelligence for AI agents. Query Polymarket and Kalshi markets, wallet profiles, smart money leaderboards, social pulse signals, price candlesticks, and orderbook data — 13 agents, one MCP connection. Powered by 1.1TB+ of historical data.MIT
- FlicenseAqualityCmaintenanceAI-agent ready FastMCP server for Polymarket market discovery, wallet analytics, and public CLOB data, providing a read-only interface for querying markets, wallets, and order books.2235 PyPI-