Polymarket + Hyperliquid + macro for AI agents. 38 tools, signal backtest, SSE streaming. Free tier.
Access Polymarket and Hyperliquid data with 38 tools, backtesting, and streaming.
Captured live from the server via tools/list.
create_api_key
Generate a free PredMCP API key. Requires an email. Returns the key and ready-to-use MCP config. Free tier: 100 calls/day, one key per IP.
Parameters (1)
emailstringrequired
Your email address — used to identify your key and for account recovery
get_markets
Live prediction markets from Polymarket and/or HIP-4, sorted by volume. Returns title, YES/NO prices, 24h volume, and expiry.
Parameters (3)
platformstring
Data source: "polymarket", "hip4", or "all" (default)
limitinteger
Number of markets to return (1–100, default: 20)
activeboolean
Filter to active/open markets only (default: true)
get_odds
Current YES/NO prices and implied probability for any Polymarket or HIP-4 market token.
Parameters (2)
platformstringrequired
Platform the market is on: "polymarket" or "hip4"
identifierstringrequired
For Polymarket: the token_id of the YES or NO outcome. For HIP-4: the base asset ticker (e.g. "BTC")
get_orderbook
Full orderbook depth (bids + asks) for any Polymarket market token. Shows liquidity at each price level.
Parameters (1)
token_idstringrequired
Polymarket token ID for the YES or NO side of a market
search_markets
Full-text search across all Polymarket and HIP-4 prediction markets. Returns ranked results with current odds.
Parameters (2)
querystringrequired
Keywords to search in market names and descriptions, e.g. "bitcoin ETF", "US election", "Fed pivot"
limitinteger
Maximum number of results to return (1–50, default: 10)
get_whale_positions
Positions of a specific Polymarket wallet, optionally filtered to one market. The /positions API requires a user (no public "all holders by market" endpoint), so pass the wallet address of the trader you want to inspect.
Parameters (3)
userstringrequired
Polygon wallet address (0x…) of the user whose positions you want.
condition_idstring
Optional — filter results to a specific market by condition_id.
min_size_usdcnumber
Minimum position size in USDC to include in results (default: 1,000).
get_movers
Top prediction markets ranked by 24h volume spike or biggest YES/NO price swing. Surfaces breaking news bets and momentum plays across Polymarket and HIP-4.
Parameters (1)
limitinteger
Number of top movers to return (1–20, default: 10)
get_markets_near_resolution
Polymarket markets resolving within the next N hours with a leading probability above threshold. Useful for resolution arbitrage and last-minute positioning.
Parameters (2)
hoursnumber
Maximum hours until resolution (default: 24h, max: 168h = 7 days)
min_probnumber
Minimum leading outcome probability to include (default: 0.7 = 70%)
get_volume_spikes
Polymarket markets with abnormal 24h volume vs their 7-day daily average. Volume spikes typically precede news events or informed positioning.
Parameters (2)
min_rationumber
Minimum ratio of 24h volume vs 7-day daily average to qualify as a spike (default: 3x)
limitinteger
Number of results to return (default: 15)
get_late_game_sports
Sports prediction markets on Polymarket closing within a few hours with a high-certainty leading outcome. Targets near-certain resolution for late-game positioning.
Parameters (2)
certainty_pctnumber
Minimum leading outcome probability as percentage, e.g. 85 = 85% (default: 85)
List of asset tickers to fetch, e.g. ["BTC", "ETH"]. Omit to fetch all available assets.
get_whale_trades
Recent large trades on Hyperliquid perps above a notional threshold. Includes side (long/short), size, price, and timestamp.
Parameters (2)
coinstringrequired
Asset ticker to fetch whale trades for, e.g. "BTC", "ETH"
min_notional_usdcnumber
Minimum trade size in USDC to qualify as a whale trade (default: 50,000)
get_top_funding_rates
Top Hyperliquid perps ranked by absolute funding rate, with OI and annualized yield. Useful for finding the most overcrowded longs/shorts and carry opportunities.
Parameters (2)
limitinteger
Number of top results to return (default: 10)
min_abs_ratenumber
Minimum absolute funding rate to include, e.g. 0.0001. Omit to include all.
get_oi_near_cap
Lists Hyperliquid perps that are currently at the open interest cap — new long positions cannot be opened. Use as a blacklist to avoid getting rejected on entry.
No parameters.
get_orderbook_depth
Full orderbook depth + slippage estimate for any Hyperliquid perp or HIP-4 market. Returns top of book, spread, cumulative depth at $100/$500/$1k/$5k tiers, and estimated slippage for a given order size. Critical for HIP-4 farming and low-liquidity assets where market orders get destroyed by slippage.
Parameters (3)
coinstringrequired
Asset ticker (BTC, ETH, SOL) or HIP-4 contract name (e.g. "BTC>81041@20260512-0600")
size_usdcnumber
Order size in USDC to estimate slippage for (default: 200)
sidestring
Order side: "buy" (taker into asks) or "sell" (taker into bids)
get_price_summary
One-call snapshot for an asset: mark price, 24h and 7d returns, 30d high/low, drawdown from high, rally from low, annualized realised volatility. Computed from 30d of HL hourly candles.
Parameters (1)
assetstringrequired
Asset ticker, e.g. "BTC", "HYPE"
get_basic_macro
DXY, US10Y yield, S&P 500, gold, VIX — direct from free Yahoo Finance. Raw values + 1d change. Pro adds BTC dominance, ETH/BTC, total crypto mcap, and a RISK_ON/OFF regime classifier.
No parameters.
get_recent_news
Recent crypto news headlines matching an asset ticker, from CoinDesk + The Block + Decrypt + Cointelegraph RSS feeds. Pro adds the 1h price move that followed each headline.
Parameters (3)
assetstringrequired
Asset ticker to filter on, e.g. "BTC", "ETH", "HYPE"
BTC or ETH options snapshot via free Deribit public feed: ATM implied volatility, total OI, 24h volume. Pro adds put-call skew + full term structure parsing.
Parameters (1)
assetstringrequired
Underlying — Deribit free feed supports BTC and ETH.
get_recent_signals
Server-detected events from the last hour: funding outliers (≥3x 7d baseline), whale trades (≥$100k), OI caps reached. Cursor-based — pass next_cursor back as since_id to receive only new events. The polling equivalent of the /sse/signals stream. Pro tool get_signal_history covers 7 days with forward-return outcomes.
Parameters (3)
since_idinteger
Cursor from a previous call — returns only events with id > since_id. Omit on first call.
coinstring
Filter to one coin, e.g. "BTC"
limitinteger
Max events (free tier cap: 20)
get_oi_history
Open-interest time series for a coin over the last 24h, from our continuous 5-min collector. Hyperliquid has NO OI-history endpoint — this data exists only on predmcp. Includes price + funding at each point. Pro tool get_oi_divergence classifies price-vs-OI regimes (squeeze/liquidation/new positioning) across all coins.
Parameters (2)
coinstringrequired
Coin, e.g. "BTC" (top ~30 by OI are tracked)
hoursinteger
Lookback window in hours (free tier max: 24)
get_market_regime
One-call market regime classifier: RISK_ON_TRENDING / RISK_OFF / SQUEEZE_RISK / CHOP_LOW_VOL / MIXED. Combines BTC trend + realized vol, Deribit IV premium, funding breadth, and OI-weighted crowding across the top 50 perps. Call this FIRST each session to condition strategy choice.
No parameters.
get_signals
Detect divergence signals between Hyperliquid perpetual funding/OI sentiment and HIP-4 on-chain prediction market odds. Returns BULLISH/BEARISH/DIVERGENCE signal with reasoning — e.g. perps long-biased while prediction market prices a decline.
Parameters (1)
coinstringrequired
Ticker of the asset to analyze, e.g. "BTC", "ETH", "SOL"
get_market_context
Unified intelligence snapshot for any topic, asset, or keyword: all matching Polymarket and HIP-4 prediction markets combined with live Hyperliquid perp data (price, funding, OI). One call replaces 3+ separate lookups.
Parameters (1)
querystringrequired
Topic, asset, or keyword to look up — e.g. "BTC", "Iran", "Fed rate cut", "Trump"
get_pm_hl_divergences
Markets where Polymarket implied probability diverges from Hyperliquid perpetual funding direction — e.g. PM prices bullish outcome but HL funding shows crowded longs (bearish pressure). The hardest signal to compute manually.
Parameters (2)
min_pctnumber
Minimum divergence percentage between PM implied probability and HL pricing to flag (default: 10%)
limitinteger
Number of divergences to return (default: 15)
get_hip4_vs_pm_arb
Finds the same underlying market priced on both HIP-4 (on-chain Hyperliquid) and Polymarket, flagging spreads above threshold. A spread means one venue is mispriced relative to the other.
Parameters (1)
min_spread_pctnumber
Minimum spread between HIP-4 and Polymarket YES prices to flag (percentage points, default: 3)
get_funding_outliers
Hyperliquid perps whose current funding rate deviates significantly from their 7-day average. A spike vs baseline is a stronger signal than raw rate.
Parameters (2)
daysinteger
Historical window in days to compute the baseline average (default: 7)
min_deviation_factornumber
Minimum ratio of |current_rate| / |avg_rate| to qualify as outlier (default: 2x)
get_liquidation_clusters
Estimated price levels where mass liquidations concentrate for a given Hyperliquid perp, computed from mark price and standard leverage multiples. Higher nearby orderbook liquidity = stronger support/resistance.
Parameters (1)
coinstringrequired
Asset ticker to analyze, e.g. "BTC", "ETH", "SOL"
get_signal_backtest
Find historical instances of a signal type on an asset over the last N days and compute forward returns (1h/4h/24h), win rate, and Sharpe. Lets an agent reason about EV before trading. Killer feature: turns predmcp from data API into edge-proven intelligence.
Parameters (6)
signal_typestringrequired
Which signal to backtest. funding_outlier = funding >= z×baseline; funding_extreme = abs(funding) >= threshold.
assetstringrequired
Asset ticker, e.g. "BTC", "HYPE"
lookback_daysinteger
How many days of history to scan (default: 90, max: 180)
z_scorenumber
For funding_outlier: minimum deviation factor vs the rolling mean (default: 3×)
min_abs_ratenumber
For funding_extreme: minimum absolute funding rate (default: 0.0005 = 0.05%)
min_separation_hoursinteger
Cluster consecutive triggers — at least N hours apart (default: 8h)
get_conviction_score
Aggregates funding outlier, whale imbalance, OI/volume ratio, and momentum into a single directional score (-100 short ↔ +100 long) plus a 0-100 strength score. One call replaces 6+ lookups, returns a clean number for LLM decisions.
Parameters (3)
assetstringrequired
Asset ticker to analyze, e.g. "BTC", "ETH", "HYPE"
whale_window_minutesinteger
Lookback window for whale trades (default: 60min)
min_whale_notional_usdcnumber
Whale trade threshold in USDC (default: 25,000)
get_funding_curve_anomaly
Term-structure analysis of Hyperliquid funding for an asset: current vs 8h avg vs 24h avg vs 7d baseline. Flags spikes, regime shifts, sign contradictions. More nuanced than raw funding rate.
Parameters (1)
assetstringrequired
Asset ticker, e.g. "BTC", "HYPE"
get_setup_quality
Execution-quality score (0-100, A-F grade) for entering a position right now: spread, slippage at desired size, orderbook depth, volatility regime, trend alignment, support/resistance proximity. Different from conviction (direction) — this scores ENTRY conditions.
Parameters (3)
assetstringrequired
Asset ticker, e.g. "BTC", "HYPE"
directionstringrequired
Trade direction you are considering
size_usdcnumber
Order size in USDC to evaluate slippage for (default: 200)
get_upcoming_catalysts
Lists upcoming market catalysts for an asset within a horizon: token unlocks, governance votes (Tally), ETF/SEC deadlines, FOMC dates. Helps agents avoid blind trades into known events. Free data sources (Tally + curated DB).
Live macro snapshot: DXY, US10Y yield, S&P 500, gold, VIX (Yahoo Finance free) + BTC dominance, ETH/BTC, total crypto market cap (CoinGecko free). Plus a coarse RISK_ON / RISK_OFF / MIXED regime.
No parameters.
get_macro_liquidity
Fiat-to-crypto liquidity gauge: BTC + ETH spot ETF flows (Farside) plus on-chain USDT + USDC mint/burn (Etherscan). Net inflow = bullish for risk assets.
No parameters.
get_cex_outflows
Net ETH outflows across known CEX hot wallets (Binance, Coinbase, OKX, Kraken, Bitfinex) over a window. Outflow = bullish (BTC moving to cold storage). Inflow = distribution pressure. Etherscan free tier.
Parameters (2)
window_hoursnumber
Lookback window in hours (default: 24h, max: 7d)
exchangestring
Filter to a single exchange or aggregate all (default: all)
get_news_correlation
Recent crypto news headlines mentioning an asset (CoinDesk, The Block, Decrypt, Cointelegraph) paired with the 1h price move that followed each. Lets agents filter news bias.
Parameters (2)
assetstringrequired
Asset ticker, e.g. "BTC", "ETH", "HYPE"
hours_backinteger
Lookback window for headlines (default: 24h, max: 7d)
get_portfolio_risk
Risk analytics for a list of positions: per-position beta to BTC and ETH, sector concentration, pairwise correlation matrix, portfolio annualized volatility, 1-day 95% parametric VaR. Uses 14d of 1h Hyperliquid candles.
Parameters (1)
positionsarrayrequired
Array of positions: { asset, side, notional_usd }. Max 20.
get_options_iv
BTC or ETH options snapshot via free Deribit feed: ATM implied volatility, put-call skew, term structure, total OI and 24h volume. Useful as a sentiment gauge — IV high = market expects big moves; skew indicates direction of hedging.
Parameters (1)
assetstringrequired
Underlying — Deribit only supports BTC and ETH for the free public feed.
get_whale_label
Look up an Ethereum address against our curated label DB (CEX hot wallets, known market makers, suspected funds). Lets agents distinguish mechanical MM flow from alpha-generating activity.
Parameters (1)
addressstringrequired
Ethereum address to look up (0x-prefixed, 40 hex chars).
get_signal_history
Server-detected signal events over up to 7 days (funding outliers, whale trades ≥$100k, OI caps), each joined with its measured forward returns (1h/4h/24h) once mature. Cursor-based. "What happened last time funding spiked on HYPE — and did it matter?" in one call.
Parameters (5)
coinstring
Filter to one coin, e.g. "BTC"
signal_typesarray
Filter to specific signal types
hours_backinteger
Lookback window in hours (default 24, max 168 = 7d)
since_idinteger
Cursor — only events with id > since_id
limitinteger
Max events (default 50)
get_signal_performance
Hit rates and average forward returns per signal type, measured on OUR actually-emitted production signals (not a backtest reconstruction). Use this to ground win_rate inputs for get_position_size. Sample sizes included — treat n < 10 as anecdotal.
Parameters (3)
signal_typestring
Filter to one signal type (default: all)
coinstring
Filter to one coin, e.g. "BTC"
daysinteger
Lookback window (default 30, max 90)
get_oi_divergence
Price-vs-OI regime per coin from our continuous snapshots: NEW_LONGS / SHORT_SQUEEZE / NEW_SHORTS / LONG_LIQUIDATION. Scan all tracked coins or analyze one. Impossible without OI history, which no public API provides — only predmcp records it.
Parameters (2)
coinstring
One coin (e.g. "BTC") — omit to scan all tracked coins
hoursinteger
Lookback window in hours (default 24, max 90d)
get_whale_flow
Cumulative whale buy/sell imbalance over hours-to-days from the durable trade tape (≥$25k trades persisted continuously, restart-proof). Returns imbalance ratio (-1..+1), BUY/SELL_DOMINANT verdict, and the largest recent prints. Longer horizons than get_whale_trades (1h buffer).
Parameters (3)
coinstringrequired
Coin, e.g. "BTC" (top ~10 by OI are taped)
hoursinteger
Lookback window in hours (default 24)
min_notional_usdcnumber
Threshold for the sample trades list (tape floor: $25k)
get_position_size
Turn a signal + bankroll into a concrete position: fractional-Kelly size capped by orderbook liquidity, ATR-based stop, liquidation price at chosen leverage, funding carry cost, and % bankroll at risk. Warns when liquidation sits inside the stop. Ground win_rate_pct with get_signal_performance or get_signal_backtest first.
Parameters (8)
assetstringrequired
Asset, e.g. "BTC"
directionstringrequired
Trade direction
bankroll_usdcnumberrequired
Total capital available in USDC
win_rate_pctnumber
Estimated win probability % (use get_signal_performance or get_signal_backtest to ground this)
payoff_rationumber
Avg win / avg loss ratio (default 1.5)
kelly_fractionnumber
Fraction of full Kelly to use (default 0.25 — quarter Kelly)
max_slippage_pctnumber
Max acceptable slippage % — caps size by orderbook depth
leveragenumber
Intended leverage (default 3x)
get_carry_scanner
Funding carry NET of costs: annualized funding minus (spread + 2x slippage at your size), with break-even holding period and a 7d funding-stability score from our snapshots. get_top_funding_rates shows gross — nobody trades gross.
Parameters (2)
size_usdcnumber
Intended position size in USDC — costs are computed at this size
top_ninteger
How many candidates to fully cost out (default 8 — each costs an orderbook call)
get_cross_venue_funding
Predicted funding spreads between Hyperliquid, Binance, and Bybit per asset (from HL's predictedFundings feed). Surfaces delta-neutral carry: long the venue with lowest funding, short the highest, collect the spread. Sorted by annualized spread.
Parameters (2)
min_spread_annual_pctnumber
Minimum annualized funding spread between venues to report (default 5%)
Safe, read-only market data for AI trading agents.
44 MCP tools that cross Polymarket prediction markets, Hyperliquid perps, and HIP-4 native predictions. Plug your agent into live trading data — without ever giving it the ability to execute orders.
Live, hosted, free during early access: predmcp.com
Why read-only matters
The #1 worry when wiring an LLM to a trading venue is the same in every conversation: "and it can't actually trade, right?" PredMCP is built so that question has a single answer.
No execution endpoint. Zero order-placement code exists in this codebase. Not gated, not commented out — not implemented. There is nothing to enable.
No private keys touched. We use the public Hyperliquid Info API and Polymarket Gamma API. Your wallet, your seed phrase, your accounts — never seen, never asked for.
44 tools, all queries. Markets, orderbooks, funding rates, whale activity, signals. Every tool is a read. Your agent reasons about markets; you stay the only one who can act on them.
When these diverge, it's a signal. get_signals computes it.
24h movers:
code
"Will Bitcoin hit $150k by June 30?" $5.8M traded in 24h
"US x Iran permanent peace deal" $3.2M in 24h (+4% move)
Athletics vs Phillies +55% price move
Use the hosted server (recommended)
Get a free API key (email, no credit card, 100 calls/day) at predmcp.com/signup, then drop into your claude_desktop_config.json:
Also works with Cursor, Windsurf, Claude.ai (OAuth), and any MCP client that supports HTTP transport.
Ask your agent:
"What are prediction markets saying about Iran right now?"
"Is there a divergence between BTC perp traders and prediction markets?"
"What markets moved the most in the last 24 hours?"
"Are any whales active on both Hyperliquid and Polymarket for BTC right now?"
Early access
We're in an open early-access phase: all 44 tools, no gating, no credit card. The first 50 signups stay grandfathered for 90 days when paid plans launch.
Self-host
The public OSS core covers the read-only data layer (Polymarket + Hyperliquid wrappers, MCP server, signup/auth). The intelligence/private tools (signals, conviction scores, macro flow) live in a private side module — the hosted version exposes them, the OSS one doesn't.
bash
git clone https://github.com/RavioleLabs/predmcp
cd predmcp
npm install
npm run build
IP_HASH_PEPPER="$(openssl rand -hex 32)" npm start
Server runs on http://localhost:3000/mcp. Public data sources require no upstream API keys.
Stack
TypeScript · Fastify · MCP SDK · SQLite (better-sqlite3) · Polymarket Gamma API · Hyperliquid Info API
