circuit-mcp

Give any AI agent Circuit's real-time Solana data and agent-swarm intelligence as tools — auto-paid per call in CIRC over x402. No API keys, no signup. Add it to Claude Desktop, Claude Code, or any agent runtime with one line.

Website · Data API · Circuit SDK · Telegram · X / Twitter

Beta software. circuit-mcp is under active development — expect breaking changes, incomplete features, and rough edges. Paid tools spend real CIRC per call; start with the free tools (or a small spend cap) until you're comfortable with how it behaves.

What it does

A thin Model Context Protocol server over @circuit-llm/data. It exposes Circuit's real-time Solana data as tools any MCP client can call — and auto-pays for them per call in CIRC over x402. Free tools return data directly; paid tools are auto-paid from your wallet, bounded per call and per session. No API keys, no accounts.

The differentiator is the swarm_* tools: live signals, consensus, leaderboard, holdings, and a crowd-sourced rug blacklist from Circuit's running trading-agent fleet — data no generic price API has.

29 data tools (14 free) + dllm_chat (decentralized LLM inference) + pay_settle, 3 guided prompts, and 5 free ambient resources. Every tool is read-only.

Quick Start

Add it to any MCP client (Claude Desktop, Claude Code, an agent runtime):

// claude_desktop_config.json → "mcpServers"
{ "circuit": { "command": "npx", "args": ["-y", "@circuit-llm/mcp"],
    "env": { "CIRCUIT_WALLET": "<base58 secret funded with CIRC>" } } }   // omit → free tools only

Then ask your agent "what's the swarm's consensus on this mint?" or "audit this token for rug risk." The paid tools settle on Solana in ~400ms behind the scenes. Without CIRCUIT_WALLET, the free tools still work — and paid tools return an x402 quote you can pay from your own wallet and complete with pay_settle (see pass-through).

Tools

Free — price & market data

| Tool | What | |------|------| | circuit_quote | live price list for every tool (call this first) | | token_price | aggregated USD price (Jupiter + DexScreener + CoinGecko) | | live_prices | sub-second batch prices (≤20 mints) from the gRPC indexer | | sol_price | current SOL/USD oracle price | | token_candles | OHLCV candlesticks (1m/5m/1h/1d) from the on-chain feed | | scan | on-chain dip-reversal scanner | | slippage_buy / slippage_sell | pre-trade price-impact estimate | | x402_accepted_tokens | tokens accepted to pay Circuit's x402 endpoints (universal adapter) |

Free — swarm intelligence ⭐ (the differentiator)

| Tool | What | |------|------| | swarm_leaderboard ⭐ | agents ranked by reputation — whose signals to trust | | swarm_holdings ⭐ | what the fleet is holding right now (live smart-money positioning) | | swarm_blacklist ⭐ | crowd-sourced rug/scam avoid-list with reasons | | swarm_blacklist_check ⭐ | fast single-token "is this flagged?" check | | swarm_stats ⭐ | live fleet activity + signal volume |

Paid (auto-paid in CIRC via x402)

| Tool | Cost | What | |------|------|------| | swarm_feed ⭐ | ~$0.002 | live buy/sell/rug signals from the swarm | | swarm_consensus ⭐ | ~$0.002 | reputation-weighted swarm view on one token | | swarm_insights ⭐ | ~$0.002 | aggregated patterns the swarm is seeing | | token_security | ~$0.003 | rug-risk audit — authorities, LP lock, risk flags | | token_overview | ~$0.003 | price + metadata + security + pools in one call | | token_info | ~$0.005 | metadata + market data (supply, mcap, FDV, liquidity) | | token_holders | ~$0.005 | holder count + top-5/10/20 concentration | | token_top_traders | ~$0.005 | top traders by volume (Birdeye) — wallet, whale tags, buy/sell, USD volume | | trending | ~$0.002 | trending tokens across sources | | new_tokens | ~$0.002 | freshly launched tokens (discovery feed) | | wallet_pnl | ~$0.01 | realized/unrealized P&L for any wallet | | wallet_analytics | ~$0.01 | behavioral profile — win rate, hold times, sizing | | market_regime | ~$0.002 | risk-on/risk-off macro read | | market_sentiment | ~$0.002 | fear/greed gauge | | market_overview | ~$0.002 | broad market snapshot + top movers | | nft_market | ~$0.002 | global NFT market snapshot — collections, listings, bid coverage, arb count, median floor | | nft_floors | ~$0.003 | all Tensor collection floors + listing counts, sortable | | nft_collection | ~$0.003 | one collection: floor, cheapest listings, top bid, royalty, net spread | | nft_arb | ~$0.005 | mark-to-market NFT arb — floor ≤ best bid, ranked by net spread | | nft_asset | ~$0.002 | inspect one NFT by mint (listed?, price, floor, sellable-into-bid) | | nft_bids | ~$0.003 | full standing collection-bid depth (highest first) | | nft_search | ~$0.002 | resolve a collection by name → on-chain address + floor | | nft_sales | ~$0.003 | recent listing activity (velocity read, not confirmed sales) | | wallet_nfts | ~$0.005 | a wallet's NFTs + floor mark-to-market total |

Prices are live from circuit_quote (/api/quote); a few paid endpoints are intermittently ungated (free).

Paid — decentralized inference

| Tool | Cost | What | |------|------|------| | dllm_chat | ~$0.03 | chat completion from Circuit's decentralized LLM (Qwen2.5-72B) over x402 |

dllm_chat pays per call in CIRC — the same x402 rail as the data tools, not model credits. Pass prompt (single turn, optional system) or full OpenAI-style messages. The result includes a backend field: mesh = the decentralized DLLM, openrouter-fallback = a hosted fallback model served while the mesh is offline (so a paid call never dead-ends). Point it elsewhere with CIRCUIT_INFERENCE_URL (default https://inference.circuitllm.xyz).

Settlement — pay_settle: when the server has no wallet, a paid tool returns an x402 quote instead of paying. Pay it on Solana yourself (CIRC to the recipient, or any registered token to its collector), then call pay_settle with the same { tool, args } and your transaction signature to get the data. With a funded CIRCUIT_WALLET, paid tools auto-pay and you never need this.

Prompts

Guided workflows that chain the right tools for a single intent:

| Prompt | Args | What it does | |--------|------|--------------| | rug_check | mint | blacklist + security + holders + consensus → SAFE / CAUTION / AVOID | | ape_check | mint, solAmount? | consensus + security + slippage + regime → GO / NO-GO | | swarm_pulse | — | stats + holdings + leaderboard + fresh buy signals → what the fleet is doing |

Resources

Free, read-only ambient context a client can pull without a tool call: circuit://quote, circuit://swarm/leaderboard, circuit://swarm/holdings, circuit://swarm/blacklist, circuit://x402/accepted-tokens.

Configuration

All configuration is via environment variables.

| Variable | Default | Purpose | |----------|---------|---------| | CIRCUIT_WALLET | — | base58 secret key that funds micropayments (omit → free tools only) | | CIRCUIT_MCP_MAX_SPEND_CIRC | 1000 | per-call CIRC spend cap | | CIRCUIT_MCP_MAX_TOTAL_CIRC | 50000 | per-process CIRC cap — the runaway-spend guard; paid tools stop once reached | | CIRCUIT_MCP_TIMEOUT_MS | 120000 | outer per-tool-call backstop (a genuinely stuck call returns a clean error) | | CIRCUIT_TREASURY | — | if set, only ever pay this address (recipient allow-list — recommended) | | CIRCUIT_DATA_URL | https://api.circuitllm.xyz | override the data API base | | CIRCUIT_INFERENCE_URL | https://inference.circuitllm.xyz | override the DLLM inference gateway base (dllm_chat) | | CIRCUIT_RPC_URL | public RPC | Solana RPC used to send payments — set your own; the public default rate-limits | | CIRCUIT_PAYMENT_MINT | — | pay in a registered token instead of CIRC (see Paying in another token) | | CIRCUIT_MCP_MAX_PAYTOKEN | — | required with CIRCUIT_PAYMENT_MINT: per-call ceiling in the token's own base units (fail-closed) | | CIRCUIT_MCP_MAX_TOTAL_PAYTOKEN | — | optional cumulative foreign-token ceiling (base units) — the drain guard |

Paying in another token

Circuit's Universal x402 Adapter lets any registered token pay Circuit's x402 endpoints — the token is swapped to CIRC on the back end. To have this server pay for tools in a registered token instead of CIRC, set CIRCUIT_PAYMENT_MINT to that mint (call x402_accepted_tokens to see what's registered) and CIRCUIT_MCP_MAX_PAYTOKEN to a per-call ceiling in the token's base units. The ceiling is mandatory — without it the server fails closed and keeps paying CIRC. Any endpoint that doesn't accept the token also falls back to CIRC automatically. Requires a funded CIRCUIT_WALLET that holds the token.

Safety

• Spend is bounded two ways — CIRCUIT_MCP_MAX_SPEND_CIRC per call and CIRCUIT_MCP_MAX_TOTAL_CIRC per process (the drain guard against a looping agent). Set CIRCUIT_TREASURY to pin the payee so a hostile endpoint can't redirect funds.
• Read-only — every tool is a data fetch; none move funds beyond the micropayment.
• No bypass — this package always pays per call; the internal-key bypass is a Circuit-hosted concern, never a user knob (see docs/HOSTING.md).
• Protocol-safe — all logs go to stderr; stdout is reserved for the MCP channel.

How it works

Each paid tool call hits the Circuit Data API: a free endpoint returns data; a paid one answers 402 Payment Required with a CIRC quote. @circuit-llm/data pays the quote from your wallet on Solana and retries — the spend caps and CIRCUIT_TREASURY allow-list bound where and how much.

Pass-through (no wallet). Without CIRCUIT_WALLET, the server doesn't pay — it returns that 402 quote to the caller. You pay it yourself and finish with pay_settle; the data API verifies the signature on-chain (single-use, ≤5 min), so the server never holds funds. This is how a wallet-free hosted endpoint (like mcp.circuitllm.xyz) lets each caller pay per call in their own token. For a Circuit-fronted hosted deployment, see docs/HOSTING.md.

Develop

git clone https://github.com/Circuit-LLM/MCP && cd MCP
npm install
npm run smoke    # spawn the server via a real MCP client, list tools, exercise the free tools (no spend)
npm start        # run the server over stdio

Built on @circuit-llm/data + @circuit-llm/wallet + the MCP TypeScript SDK.

Part of the Circuit Stack

• circuit-mcp — this repo, Circuit data + swarm intel as x402-paid MCP tools
• circuit-sdk — the TypeScript SDK (x402 · data · wallet · agent · inference)
• circuit-data-api — the x402-gated Solana data aggregator these tools serve
• circuit-agent — the autonomous trading agent behind swarm_feed
• circuitllm.xyz — website and data terminal

License

MIT — see LICENSE.