Bitquery MCP server for AI agents: on-chain data your AI can actually use

AI agents are only as good as the data they can reach. Ask one about a token, a wallet or a hack without the right tools, and it guesses at API schemas, scrapes block explorers, or answers from stale training data.

Today we're giving agents a better option. The Bitquery MCP server is a hosted crypto MCP server that turns Bitquery's production on-chain dataset into tools any AI agent can call:

1. The MCP server: hosted at https://mcp.bitquery.io, with typed tools for DEX trades, prices, trader analytics, Hyperliquid perpetuals, fund tracing and address labels.
2. Playbooks: 15 guided workflows that tell an agent which tools to call, in what order, for jobs like an AML risk screen or a token dashboard.
3. Quick setup: OAuth sign-in for Claude, ChatGPT, Cursor, VS Code, Codex and Windsurf. No API key to paste and no server to run.

The result: you ask in plain English, the agent picks the right tool, and clean, structured rows come back.

Why AI agents struggle with on-chain data

On-chain data is huge, messy and changes every second. An agent without proper tools has three bad options:

• Write GraphQL or SQL from memory. It invents field names, gets the schema wrong, and burns tokens on retries.
• Scrape explorers and price sites. Slow, rate-limited, and one page layout change away from breaking.
• Answer from training data. Confident, fluent and months out of date.

MCP, the Model Context Protocol, fixes this. Instead of guessing a query, the agent calls a tool with a clear name and typed inputs, such as token_ohlcv or top_traders_by_token, and the server runs the query against Bitquery's data. No schema to learn. No curl. No guessing.

The tools also carry Bitquery's data hygiene with them: wash-traded pools and noisy pairs are deprioritised, look-alike tokens are flagged, and market caps come from prices someone could actually trade at, so the agent doesn't repeat a number that only exists because of one odd swap.

What the Bitquery MCP server gives an AI agent

The server covers two jobs: trading data and crypto investigations. Transfers can be traced on 19 chains, from Ethereum, Solana and Tron to Bitcoin, Cardano and the XRP Ledger. DEX trading data covers Ethereum, Solana, BSC, Base, Arbitrum, Optimism, Polygon, Tron, Robinhood Chain and Arc, with about 30 days of trade history.

Job	What the agent can do	Example tools
Market data	Prices, OHLCV candles, supply, market cap and the DEX venues a token trades on	token_price, token_ohlcv, pair_ohlcv, token_dex_venues
Discovery	Trending tokens, new launches, launch cohorts and early buyers	trending_tokens, new_tokens, launch_cohort, early_buyers
Trader analytics	Top and most profitable traders, wallet positions, trades and PnL	top_traders_by_token, profitable_traders_by_token, trader_profile, trader_positions
Fund tracing	Follow money hop by hop, find a wallet's first funder, map flows between addresses. Bitcoin-style chains (Bitcoin, Litecoin, Dogecoin and others) use transaction-flow and related-address tools instead	<chain>_address_flow_summary, <chain>_trace_next_hop, <chain>_first_funder, <chain>_flows_between
Labels and risk	Who owns an address: exchanges, mixers, scams, sanctioned entities	address_labels, labels_for_addresses, addresses_by_label
Prediction markets	Polymarket odds, trades, top traders and settlements	polymarket_market_odds, polymarket_top_traders
Perpetuals	Hyperliquid prices, funding, open interest, liquidations and trader PnL	hyperliquid_funding_rates, hyperliquid_liquidations, hyperliquid_trader_summary

The same data sits behind Bitquery's Hyperliquid API, Polymarket API and Address Labels API. The MCP server is the way an agent reaches it without writing a query.

Playbooks: guided workflows for AI agents

Tools give an agent access. Playbooks give it a procedure. The server ships 15 of them, each a step-by-step workflow for a common job. In clients that support MCP prompts you can start one directly, and any agent can fetch one with the prompt_playbook tool and follow its steps:

• Investigations: money_flow traces funds across multiple hops and draws a flow diagram; risk_screen runs a compliance and AML screen of an address or transaction; address_report builds a full dossier on one address; entity_report profiles a labelled entity such as an exchange or mixer
• Tokens and markets: token_dashboard, token_chart, token_scout, market_movers, compare_assets and arbitrage_scan
• Traders: trader_dashboard for one wallet's stats, positions and activity
• Prediction markets and perpetuals: prediction_market for Polymarket, plus hyperliquid_trader and hyperliquid_market
• Accounting: tax_ledger lists every movement in a period with its USD value, ready for Koinly or CoinTracker

A playbook doesn't guarantee the agent takes that path, but it gives it a tested route instead of an improvised one.

What this looks like in practice: three AI agent demos

A note on these demos: they run in Claude Code and go from open to structured. Example 1 is a single open-ended prompt, example 2 runs the same investigation both ways, and example 3 runs entirely on a playbook. They're here to show what the tools can do. Production AI agents run on a strictly defined path, with a detailed set of instructions that fixes which tools to call, in what order, and what to check before answering.

1. An AI agent breaks down a Hyperliquid liquidation cascade

"What happened on Hyperliquid in the last 24 hours? Find the markets with the biggest liquidations, tell me whether longs or shorts got wiped out, and for the biggest market check what funding and open interest were doing before and after. Who were the largest liquidated traders, and how much leverage were they running?"

Here's Claude Code answering that with the Bitquery MCP on 9 October 2026, covering the 24 hours to about 10:00 UTC. The video is sped up:

The agent went straight to the Hyperliquid tools. It ranked markets and traders with hyperliquid_liquidations, read the ETH move with hyperliquid_funding_rates and hyperliquid_candles, ran hourly breakdowns with hyperliquid_raw_sql, then checked the biggest liquidated accounts with hyperliquid_trader_summary and hyperliquid_trader_positions.

The event. One cascade did almost all the damage. Liquidations ran at a few million dollars an hour until 15:00 UTC on 8 October, when about $143M was liquidated in a single hour. ETH's 15:00 candle opened at $2,531 and closed at $2,434, a 4% drop on nearly half a billion dollars of volume, and bottomed near $2,408 at 17:00. Across all Hyperliquid markets, about $300M was liquidated in the window.

Market	Liquidated (24h)	Longs, share of liquidated fills
ETH	~$111M	88%
BTC	~$81M	77%
SKHX (HIP-3 equity perp)	~$12M	91%
SOL	~$10M	80%
NEAR	~$9M	91%

It was a long wipeout: on every major market, 77% to 91% of liquidated positions were longs, and none were passed to the backstop liquidator.

ETH funding and open interest, before and after. Before the drop, funding had sat at the hourly cap (about 11% annualised) for almost all of 7 October, and open interest peaked near 597,000 ETH (about $1.53B) with roughly 70.5% of accounts long: a crowded, expensive long side. During the cascade, funding turned negative (about −7% annualised at 16:00) and the long share fell to 66.6%. By 18:00 funding was back at the cap, and long share has rebuilt to 68%. About 6% of ETH open interest was cleared out, and longs are already paying the maximum rate again.

Account	Market	Liquidated	Leverage	Still holding
0x0392…d7d9	ETH	~$49.7M	8x, cross margin	~$106M ETH long
0x77dd…e0e9	ETH	~$19.9M	10x (fills tagged 20x to 25x)	~$99M ETH long
0x1fd4…9081	BTC	~$10.2M	20x	not checked
0x053f…a4d3	SKHX	~$8.6M	10x	not checked
0xcf70…516c	ETH	~$8.1M	25x	not checked

The agent's read on the traders: the two largest accounts were only partly liquidated and each still holds a roughly $100M ETH long, which is why open interest didn't fall further. And the biggest losers were at the low end of the leverage range. The problem was position size against a 4% hourly move, not extreme leverage.

That's a desk analyst's morning note on Hyperliquid, from one question, with every number traceable to a tool call. To make it a routine, the hyperliquid_market and hyperliquid_trader playbooks run the same kind of breakdown as a fixed set of steps.

2. Tracing stolen funds with an AI agent

"Trace the funds from the Bybit hack exploiter 0x47666fab8bd0ac7003bce3f5c3585383f09486e2 on Ethereum. Where did the ETH come from, how was it split, and where did it end up? Label any exchanges, bridges or mixers."

Here's Claude Code working through it with the Bitquery MCP. The run took about 10 minutes; the video is cut and sped up to about 1.5 minutes.

The agent planned a money-flow trace (where the ETH came from, how it fanned out, then the dominant paths) and worked hop by hop with eth_address_flow_summary, eth_trace_next_hop, eth_trace_dominant_path and labels_for_addresses, labelling around 90 wallets along the way. What it reconstructed:

1. The source. 401,347 ETH arrived in one transfer from an address Bitquery labels as Bybit Cold Wallet 1.
2. The first split. Between 15:48 and 15:54 UTC on 21 February 2025, exactly 400,000 ETH left as 40 transfers of 10,000 ETH to 40 fresh, unlabelled wallets.
3. Staking tokens swapped first. About 90,000 stETH and 8,000 mETH went through Paraswap and the Uniswap Universal Router into ETH, then into the same 10,000 ETH fan-out.
4. The peel chain. From 22 February to 3 March, the 10,000 ETH wallets sliced their balances into transfers of 250 to 700 ETH. The same intermediate wallets showed up under several branches: one person, running a script.
5. The exit. Every branch it followed ended at the THORChain router. About 20 relay wallets, live only from 27 February to 3 March, each cycled 15,000 to 48,000 ETH through it, consistent with the publicly reported conversion of the funds into Bitcoin.

It also knew where to stop. Past the THORChain router, the trail runs into Binance hot wallets, but the agent recognised that as THORChain paying out to its other users, not the hacker, and didn't follow it. It closed with its own caveats: it followed the largest flows rather than every one of several hundred wallets, so its figures are lower bounds.

The same trace, with the money_flow playbook

"Use the money_flow playbook from the Bitquery MCP on 0x47666fab8bd0ac7003bce3f5c3585383f09486e2 (Ethereum), following ETH. Where did the ETH come from, how was it split, and where did it end up? Label any exchanges, bridges or mixers."

Same address, same questions, same model and the same effort setting. The only difference is that the prompt names a playbook, so the agent follows money_flow's fixed steps instead of choosing its own route. The open run took about 10 minutes. This one finished in 4 minutes:

It reached the same conclusion: 401,346.77 ETH from Bybit Cold Wallet 1, split into 40 × 10,000 ETH on 21 February 2025, with every branch it expanded ending at the THORChain router. What changed is the shape of the answer. Instead of a narrative built up as the agent went, the playbook produced a report:

• The headline figures in a table: the inflow, the 40-way split, a second residual split of about 1,613 ETH across 14 wallets on 3 March, and how many sampled branches reached THORChain (6 of 6).
• Where it came from: the source wallet and its labels, plus a detail the open run didn't surface. The ETH arrived as an internal transfer, moved by contract code rather than a plain send, which matches the known takeover of Bybit's multisig wallet.
• A flow diagram from the Bybit cold wallet through the exploiter and the relay layers to THORChain.
• A hop-by-hop table listing each wallet, the next address, the amount, the asset and the date.
• Branch verdicts: no exchange or mixer label on any relay, the end point of every branch, and the look-alike token transfers set aside as address poisoning.
• Caveats: only 6 of the 40 first-layer branches were expanded, a missing label isn't proof a wallet isn't a service, and the result is on-chain analysis, not a legal conclusion.

That's the trade-off. An open prompt suits an investigator digging into something new: it went wider and mapped about 20 relay wallets. A playbook takes less than half the time and returns the same report layout every time, which is what a compliance team can file or hand to an analyst. For a step-by-step walkthrough of a single wallet, see how to investigate an Ethereum address with AI, and for the fully managed version, Bitquery AI Investigations.

3. Trader analytics: two dashboards from one playbook

"Use the trader_dashboard playbook from the Bitquery MCP on these two Solana wallets over the last 30 days, one dashboard per wallet: 6jz6evaLNRDJkXUypB6coiTZoFHtVTck4cJBpQ78kXnq and GuRfuByNZoFb2TJKj3x6SZEwaZzt8rn2MG1PAgEzWizm. Then compare them: who made money, and why?"

This time the whole job runs on a playbook. trader_dashboard tells the agent exactly what to pull for each wallet: its profile with trader_profile, its positions and profit per token with trader_positions, a daily timeline with trader_activity, and its swaps with trader_trades. In about 3.5 minutes it built and published a live dashboard for each wallet, then answered the question:

Each dashboard opens with a one-line read of the wallet, then stat cards (realized PnL, win rate, volume, net cash flow, median hold), its recent swaps and a day-by-day activity table, with a note on how PnL is calculated. The comparison:

	6jz6…kXnq	GuRf…Wizm
Realized PnL	+$88,967	−$226,757
Win rate (by token)	75% (3 of 4)	16% (3 of 19)
Swaps	72	1,297
Volume	$3.0M	$23.0M
Tokens traded	6	20
Median hold	about 9 days	about 6 hours

And the why:

• One good trade. Almost all of 6jz6's profit came from a single PUMP position: bought on 2 October at about $0.0054, sold on 5 October at about $0.0064, an 18.5% return worth $82k. It took few positions, sized them large and held for days.
• Too many trades. GuRf also traded that PUMP move and made $35.7k on it, but losses elsewhere swamped it. CARDS alone cost $121k: it bought at an average of $0.279, sold at $0.238, then bought back near $0.28.

The agent ended up with two shareable pages and a clear answer, and the next run on two other wallets will produce the same layout. That's a playbook working as a repeatable routine.

Want to run these prompts yourself? Connect the Bitquery MCP server to your agent using the steps below.

Connect the MCP server to your AI agent in 60 seconds

The server is hosted, so there's nothing to install or run. Add the URL to your client, and sign in with your Bitquery account the first time a tool runs. New accounts get a free 7-day trial, no card needed.

Claude Code

claude mcp add --transport http bitquery https://mcp.bitquery.io

Then run /mcp and finish the browser login.

Codex

codex mcp add bitquery --url https://mcp.bitquery.io

Claude.ai, Claude Desktop and ChatGPT

Open Settings, then Connectors, add a custom connector named Bitquery with the URL https://mcp.bitquery.io, and sign in when prompted.

Cursor

Open Settings, then MCP, then Add new MCP server, and enter the URL https://mcp.bitquery.io. Or add this to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "bitquery": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.bitquery.io/mcp"]
    }
  }
}

Restart Cursor, then sign in when the first tool runs.

VS Code

Add a new MCP server with the URL https://mcp.bitquery.io.

Windsurf

Open Settings, then MCP, add a custom server with the URL https://mcp.bitquery.io, and reload. If Windsurf asks for a JSON config, use the same mcp-remote block as Cursor.

Sign-in uses OAuth 2.1, so no API key ends up in a prompt or a config file. Tokens are cached for about 30 days. Step-by-step guides for each client are in the MCP docs.

Pricing and limits

You can try it free: new accounts get a 7-day trial with 100 credits, no card required. After that there are two MCP plans (full details on the pricing page):

• Trading MCP: $19 a month for 25k credits, covering the 32 trading tools.
• AI Investigation MCP: $149 a month for 200k credits, covering all 314 tools, including fund tracing and address labels.

Yearly billing takes 30% or more off, and quotas and billing are shared with your regular Bitquery plan. Trading history goes back about 30 days, and the server is read-only: it can't sign or send transactions, and it never holds keys.

Start building

Bitquery gives agents the on-chain data layer they need, for trading research and investigations alike, across 19 chains plus Hyperliquid and Polymarket. Teams building their own agents can see how the MCP server and the APIs fit together on the on-chain data for AI agents page.

• Connect your agent: https://mcp.bitquery.io, or start from the Bitquery MCP server page
• Read the docs: docs.bitquery.io/docs/mcp/mcp-server
• See the plans: Bitquery pricing
• Talk to us: sales@bitquery.io or Telegram support

Built something with it? Tell us. We'd love to feature it.

FAQ

What is the Bitquery MCP server?

A hosted Model Context Protocol server at https://mcp.bitquery.io. It gives AI agents typed tools for Bitquery's on-chain data: DEX trades, prices and candles, trader analytics, fund tracing, address labels, Polymarket and Hyperliquid. The agent picks the tool; you ask in plain English.

Is there a free trial?

Yes. New Bitquery accounts get a 7-day trial with 100 credits, and no card is needed. After that, plans start at $19 a month. See the pricing page.

Which AI clients and agents does it work with?

Claude.ai, Claude Desktop, Claude Code, ChatGPT (with custom connectors), Cursor, VS Code, OpenAI Codex and Windsurf, plus custom agents built on the Anthropic or OpenAI SDKs. Clients that only support local (stdio) servers can connect through the mcp-remote bridge.

Which blockchains does it cover?

Transfer tracing covers 19 chains, including Ethereum, Solana, Tron, Bitcoin, Cardano and the XRP Ledger. DEX trading data covers Ethereum, Solana, BSC, Base, Arbitrum, Optimism, Polygon, Tron, Robinhood Chain and Arc. Polymarket and Hyperliquid have their own toolsets.

Can an AI agent analyse Hyperliquid data?

Yes. The server has a dedicated set of Hyperliquid tools for perpetual and spot markets: prices and candles, funding rates, open interest, liquidations, order flow, and trader positions, fills and PnL. The hyperliquid_market and hyperliquid_trader playbooks package them into a market report or a trader report. The tools are read-only and can't place orders.

Can I use it for crypto investigations and AML checks?

Yes. The investigation tools trace funds hop by hop, find first funders and label exchanges, mixers and sanctioned entities. Playbooks such as money_flow, risk_screen, address_report and entity_report turn those into repeatable reports. These tools are part of the AI Investigation MCP plan.

How is it different from the Bitquery GraphQL API?

It's the same data. With GraphQL you write each query yourself, which suits apps and streaming. With MCP the agent chooses typed tools and chains several lookups in one answer, with no schema to learn. Both run on the same Bitquery account.

Can the agent trade or move funds?

No. The server is read-only. It can't sign or send transactions, place orders, or hold keys.

How fresh is the data?

Near real time: data is updated as new blocks are processed. Trading history goes back about 30 days.