# Quicknode for AI Agents Multi-chain blockchain infrastructure for AI agents. RPC access, transaction simulation, token data, real-time streams, and SQL queries across 80+ chains and 130+ networks. ## Quickstart: provision an endpoint For autonomous agents with a funded EVM wallet and no Quicknode account. 1. **Pay → receive API key.** `POST https://www.quicknode.com/api/v1/agent/subscriptions` with `PAYMENT-SIGNATURE` (x402) or `Authorization: Payment` (MPP). POST with no body to receive a 402 listing all plans, networks, and payment accepts. Response returns a `QN_*` API key. 2. **Use key → create endpoint.** `POST https://api.quicknode.com/v0/endpoints` with body `{"chain":"base","network":"base-mainnet"}` and header `x-api-key: QN_*`. Admin API. Returns an RPC URL. 3. **Use the RPC.** Standard JSON-RPC POSTs to the returned URL. Full runnable walkthrough (every field, curl, response shape): https://www.quicknode.com/agents/create-endpoint.md Admin API full spec: https://www.quicknode.com/api-docs/v0/swagger.json ## Choose Your Path - **Autonomous agent, no account?** → x402 or MPP (pay-per-request with stablecoins) - **Autonomous agent needs to create endpoints via its own subscription?** → Agent Subscription API + Admin API (pay → API key → create endpoint). See Quickstart above. - **Agent with a Quicknode account?** → API Key - **AI coding agent generating Quicknode code?** → Install Blockchain Skills - **AI assistant managing infrastructure?** → Connect MCP Server ## Authentication ### x402 — No Account Required Use x402 if you want agents to authenticate and pay using only a wallet, no accounts or API keys required. It's an open standard (developed by Coinbase) built on HTTP 402, using SIWX (Sign-In with X) for authentication. Agents sign a SIWE (EVM) or SIWX (Solana) message, receive a JWT, and pay in stablecoins. Fully programmatic. No human in the loop. ```javascript import { createQuicknodeX402Client } from "@quicknode/x402"; const client = await createQuicknodeX402Client({ baseUrl: "https://x402.quicknode.com", network: "eip155:84532", // pay on Base Sepolia evmPrivateKey: "0x...", }); const response = await client.fetch( "https://x402.quicknode.com/ethereum-mainnet", { method: "POST", body: JSON.stringify({ jsonrpc: "2.0", method: "eth_blockNumber", params: [], id: 1, }), } ); ``` - Three payment models: - **Per-request**: $0.001 per request — no auth required, pay on every call - **Nanopayment**: $0.0001 per request via Circle Gateway — sub-cent payments (Quicknode is the first infra provider with Circle Nanopayments via x402) - **Credit drawdown**: $10 USDC \= 1,000,000 credits on mainnet — authenticate via SIWX, consume credits per request - Payment networks: Base, Solana, Polygon (USDC), XLayer (USDG). The payment chain determines how you pay, not which networks you can query — pay on Base and query Solana, or any other combination across 80+ chains. - Auth: SIWE (EVM) or SIWX (multi-chain including Solana). The `@quicknode/x402` SDK handles SIWX auth, payment negotiation, and JWT session management automatically. - Access: Per-request and nanopayment support JSON-RPC and REST only. For WebSocket or gRPC streaming connections, use credit drawdown mode. - On credit exhaustion: requests return HTTP 402\. The SDK auto-signs a payment and retries. Or top up wallet manually. - NPM: `@quicknode/x402` (recommended), `@x402/fetch`, `@x402/evm`, `@x402/svm` - Docs: https://www.quicknode.com/docs/build-with-ai/x402-payments ### MPP — No Account Required Machine Payments Protocol (IETF Internet-Draft by Tempo Labs and Stripe). A second wallet-based payment option alongside x402. No signup, no API key. ```javascript import { Mppx, tempo } from "mppx/client"; import { privateKeyToAccount } from "viem/accounts"; const account = privateKeyToAccount("0x..."); // Polyfills globalThis.fetch — all subsequent fetch() calls handle 402 automatically Mppx.create({ methods: [tempo({ account })], }); const response = await fetch("https://mpp.quicknode.com/ethereum-mainnet", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", method: "eth_blockNumber", params: [], id: 1, }), }); ``` - Payment methods: PathUSD on Tempo or USDC on Solana - Two intents: - **Charge**: $0.001 per request — simple one-time payment per call - **Session**: $0.00001 per request — open a payment channel, send off-chain vouchers per request (100x cheaper, best for high-volume agents) - Same 130+ network coverage as x402 - On payment required: HTTP 402 with `WWW-Authenticate: Payment` challenge. The `mppx` SDK handles payment negotiation automatically. - NPM: `mppx` (Tempo), `solana-mpp` (Solana) - Docs: https://www.quicknode.com/docs/build-with-ai/mpp-payments ### API Key Standard authentication with a Quicknode account. ```shell curl https://YOUR_ENDPOINT.quiknode.pro/ \ -X POST \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' ``` - Get a key: https://www.quicknode.com/signup - On auth failure: HTTP 401\. Verify API key and endpoint URL. - Pricing: https://www.quicknode.com/pricing.md ### Agent Subscription API Create a Quicknode subscription programmatically to obtain a `QN_*` API key. RPC endpoints are then created via the Admin API using that key — see Quickstart at the top of this document for a runnable 3-step example. Use this flow when an agent needs a full account; for one-off RPC calls use x402 or MPP above. Base URL: `https://www.quicknode.com`. Pay via x402 v2 (`PAYMENT-SIGNATURE` header) or MPP (`Authorization: Payment `). Call any endpoint without payment to get a 402 listing required fields, plans, and accepted payment methods. - `POST /api/v1/agent/subscriptions` — create account + plan. Returns a one-time `QN_*` API key. - `POST /api/v1/agent/top_up` — add credit. Requires API key + payment. Idempotent on payment tx hash. - `GET /api/v1/agent/balance` — current balance. Requires API key. After subscription, create RPC endpoints via the Admin API at `https://api.quicknode.com`: - `POST https://api.quicknode.com/v0/endpoints` — body: `{"chain","network"}`; auth: `x-api-key: QN_*`. Full spec: https://www.quicknode.com/api-docs/v0/swagger.json API key auth: `x-api-key: QN_*` or `Authorization: Bearer QN_*`. Rate limits: `/subscriptions` 20/min/IP + 5/hour/email; `/top_up` 30/min; `/balance` 60/min. ## Quick Start ### 1\. Install Blockchain Skills (for AI coding agents) Give your agent accurate knowledge of Quicknode's full API surface: ``` npx skills add https://github.com/quiknode-labs/blockchain-skills --skill quicknode-skill ``` Works with: Claude Code, Cursor, Codex, OpenCode, Windsurf ### 2\. Connect MCP Server (for AI assistants) Manage Quicknode infrastructure through natural language. The MCP server is hosted remotely and authenticates via OAuth — no API key needed. **Recommended — Remote server (OAuth):** ``` claude mcp add quicknode --transport http https://mcp.quicknode.com/mcp ``` On first connect, a browser window opens to log in with your Quicknode account. Works with: Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Zed. **Alternative — Local server (API key):** ``` npx -y @quicknode/mcp ``` Requires a `QUICKNODE_API_KEY` environment variable. Use this if you prefer local execution or can't use browser-based OAuth. MCP capabilities: create endpoints, configure security, set rate limits, review billing, monitor usage. Does NOT provide blockchain data access — use x402 or RPC endpoints for on-chain reads/writes. - Docs: https://www.quicknode.com/docs/build-with-ai/quicknode-mcp - NPM: https://www.npmjs.com/package/@quicknode/mcp ### 3\. Access Chains via x402 or MPP (for autonomous agents) No account needed. See x402 and MPP auth sections above. ## Picking the Right Tool ### By task - Need real-time Solana monitoring? → **Yellowstone gRPC** - End-to-end EVM/Solana/UTXO/Hypercore data pipelines → **Streams** - Need Hyperliquid order book or trade data? → **HyperCore gRPC** - Need ad-hoc analytics on Hyperliquid trading data? → **SQL Explorer** - Need simple event-driven alerts? → **Webhooks** - Need to read balances, blocks, or transaction receipts? → **RPC Call** - Need to validate a transaction before broadcasting? → **Transaction Simulation** ### By chain type | | EVM Chains | Solana | Hyperliquid | Bitcoin/UTXO | | :---- | :---- | :---- | :---- | :---- | | RPC | JSON-RPC \+ REST (Beacon) | JSON-RPC \+ WebSocket | JSON-RPC \+ Info API | JSON-RPC | | Real-time data | Streams | Streams \+ Yellowstone gRPC | HyperCore gRPC | Streams | | Tx model | Account-based, EVM opcodes | Account-based, programs | Perp/spot orders | UTXO | | Key difference | `eth_call` for reads | `getAccountInfo` for reads | `/info` for market data, `/hypercore` for blocks | No smart contracts | | Archive data | Yes | Yes | Yes | Yes | | Trace & Debug | Yes (paid plans) | No — use program logs and tx metadata instead | N/A | N/A | | Finality | \~15 min (2 epochs) | \~400ms | \~1s | \~60 min (6 confirmations) | ### Block finality Agents acting on blockchain state must account for finality. Reading unfinalized data can lead to bad decisions — a transaction that appears confirmed may be reorged away. | Chain | Time to Finality | Safe to Act On | | :---- | :---- | :---- | | Ethereum | \~13 minutes (2 epochs, 64 slots × 12s each) | `finalized` block tag for high-value actions | | Solana | \~400ms | `confirmed` commitment for most reads, `finalized` for critical actions | | Base/Arbitrum/Optimism | \~13 min (inherits L1 finality) | Use L1 finality for withdrawals, L2 confirmation for reads | | Bitcoin | \~60 minutes (6 blocks) | 1 confirmation for small amounts, 6 for high-value | | Hyperliquid | \~1 second | Near-instant for trading actions | Rule of thumb: use `finalized` or equivalent for any action involving value transfer. Use `latest`/`confirmed` for read-only queries where speed matters more than certainty. ## API Credit Costs Every API call costs credits. Cost depends on chain and method type. | Chain Group | Base Credits | Chains | | :---- | :---- | :---- | | Tier 1 | 10 credits | Bitcoin, Bitcoin Cash, Aptos, Dogecoin, Flow, Fuel, Litecoin, Stellar | | Tier 2 | 20 credits | Ethereum, Base, Arbitrum, Optimism, Polygon, BNB, Hyperliquid, [+42 more](https://www.quicknode.com/api-credits) | | Tier 3 | 30 credits | Solana, Monad, TRON, Gnosis, zkSync, \+5 more | | Tier 4 | 40 credits | Cosmos, Sui, TON, Polkadot, Stacks, XRP, \+7 more | | Tier 5 | 50 credits | NEAR, Polygon zkEVM | ### Multipliers | Method Type | Multiplier | Example Methods | | :---- | :---- | :---- | | Standard | 1x | eth\_blockNumber, eth\_getBalance, getAccountInfo | | Advanced | 2x | Trace & Debug, Token API, NFT API, arbtrace, txpool, Solana getAsset methods, TRON Enhanced methods | | Large | 4x | txpool\_content, trace\_replayBlockTransactions, trace\_replayTransaction, Arbitrum: arbtrace\_replayTransaction / arbtrace\_replayBlockTransactions, Solana: getLargestAccounts / getSupply | **Cost formula:** Base Credits x Multiplier \= Credits Per Call Examples: - `eth_getBalance` on Ethereum \= 20 credits x 1x \= **20 credits** - `debug_traceTransaction` on Ethereum \= 20 credits x 2x \= **40 credits** - `getAccountInfo` on Solana \= 30 credits x 1x \= **30 credits** ### SQL Explorer SQL Explorer queries use API credits from your plan. Credit cost scales with query complexity and data scanned — simple queries cost standard rates, complex aggregations across large block ranges cost more. Same credit pool as RPC calls, no separate pricing. Full method-level reference: https://www.quicknode.com/api-credits ## Rate Limits and Error Handling ### Rate limits by plan | Plan | Requests/sec | Behavior at limit | | :---- | :---- | :---- | | Free | 15 | HTTP 429 — back off and retry | | Build | 50 | HTTP 429 — back off and retry | | Accelerate | 125 | HTTP 429 — back off and retry | | Scale | 250 | HTTP 429 — back off and retry | | Business | 500 | HTTP 429 — back off and retry | | x402 | No fixed ceiling | Throttled by credit balance and network capacity. HTTP 402 on exhaustion, 429 if upstream saturated. | | Enterprise | Custom | Custom | ### Error handling | HTTP Code | Meaning | Agent Should | | :---- | :---- | :---- | | 200 | Success | Process response | | 402 | Payment required (x402/MPP) | Top up wallet with stablecoins, retry | | 401 | Unauthorized | Check API key or re-authenticate (SIWX for x402) | | 429 | Rate limited | Exponential backoff, start at 1s, max 30s | | 500 | Server error | Retry with backoff, max 3 attempts | | 503 | Service unavailable | Retry after 5s, check status.quicknode.com | ### Backoff strategy ``` wait = min(2^attempt * 1000ms, 30000ms) ``` On 429: respect `Retry-After` header if present. Otherwise use exponential backoff. On credit exhaustion (x402): requests fail with 402 until the wallet is topped up. Monitor credit balance proactively. ### Parallelism When fanning out concurrent requests, stay under 70% of your plan's req/sec limit to leave headroom for retries and spikes. Example: on the Build plan (50 req/sec), cap parallel requests at \~35. Use a semaphore or token bucket to enforce this client-side. ## Example Workflow: Token Swap Safety Check A concrete multi-step flow for an agent validating a swap: ``` 1. CHECK BALANCE → eth_getBalance(wallet) — verify sufficient funds 2. GET TOKEN PRICE → Token API: get current price + slippage estimate 3. BUILD TRANSACTION → Construct swap calldata for DEX router (client-side, no API call) 4. SIMULATE → Transaction Simulation: check for reverts, gas estimate, state diffs → If simulation reverts: STOP. Return revert reason to user. 5. BROADCAST → eth_sendRawTransaction(signedTx) 6. MONITOR → Streams or Webhooks: watch for tx confirmation → If not confirmed in 3 blocks: alert user, check mempool ``` Credit breakdown on Ethereum: - Step 1: `eth_getBalance` — Standard (1x) = **20 credits** - Step 2: Token API — Advanced (2x) = **40 credits** - Step 3: Client-side — **0 credits** - Step 4: Transaction Simulation — Advanced (2x) = **40 credits** - Step 5: `eth_sendRawTransaction` — Standard (1x) = **20 credits** - Step 6: Webhook — **30 credits** per matched block Total: **~150 credits** for full flow. ## Example Workflow: Solana Wallet Monitor Watch a wallet for incoming SPL token transfers using Yellowstone gRPC and trigger an action: ``` 1. CONNECT → Open Yellowstone gRPC stream to Solana endpoint → Subscribe to account updates for target wallet 2. FILTER → Watch for token account changes (SPL Token Program) → Parse transfer instruction from transaction metadata 3. VALIDATE → getTransaction(signature) — confirm transfer details → Check: sender, token mint, amount, finality (use "confirmed" commitment) 4. ACT → If amount > threshold: trigger downstream action → If unknown token mint: flag for review, do not act 5. HANDLE ERRORS → On stream disconnect: reconnect with exponential backoff → On missed slot: use getSignaturesForAddress to backfill ``` Yellowstone gRPC connection pattern: ```javascript const { Client } = require("@quicknode/yellowstone-grpc"); const client = new Client( "https://YOUR_ENDPOINT.solana-mainnet.quiknode.pro", "YOUR_API_KEY" ); const stream = await client.subscribe(); stream.on("data", (update) => { // Handle account update if (update.account) { const accountData = update.account; // Parse SPL token transfer from account data } }); // Subscribe to account updates await stream.write({ accounts: { wallet: { account: ["TARGET_WALLET_ADDRESS"], }, }, }); ``` Credit cost: Yellowstone gRPC uses Streams payloads, not per-call RPC credits. Payload allocations vary by plan — see https://www.quicknode.com/pricing.md for current limits. ## Real-time Data Options | Method | Best For | Latency | Delivery | | :---- | :---- | :---- | :---- | | Streams | EVM/Solana real-time and historical data pipelines | Standard | Guaranteed, with reorg handling | | Yellowstone gRPC | Solana account & tx monitoring | Sub-second | Streaming | | HyperCore gRPC | Hyperliquid order book & trade data | Lowest | Streaming (10 stream types — see HyperCore gRPC Streams below) | | Webhooks | Simple event-driven HTTP notifications | Standard | Best-effort | ### HyperCore gRPC Streams 10 stream types across two access modes. All streams available via gRPC; a subset also via JSON-RPC/WSS. | Stream | Description | Access | Use Cases | | :---- | :---- | :---- | :---- | | TRADES | All executed trades with price, size, and direction | gRPC \+ JSON-RPC/WSS | Trading analytics, price tracking | | ORDERS | Order lifecycle events (18+ status types including fills, cancellations) | gRPC \+ JSON-RPC/WSS | Order management, execution monitoring | | BOOK\_UPDATES | Order book changes with bid/ask prices and quantities | gRPC \+ JSON-RPC/WSS | Market depth analysis, liquidity monitoring | | TWAP | TWAP execution data and algorithm progress | gRPC \+ JSON-RPC/WSS | Algorithmic trading, execution analytics | | EVENTS | Balance changes, transfers, deposits, withdrawals, vault operations | gRPC \+ JSON-RPC/WSS | Fund flow analysis, account monitoring | | WRITER\_ACTIONS | HyperCore ↔ HyperEVM asset transfers and bridge data | gRPC \+ JSON-RPC/WSS | Cross-environment asset tracking, DeFi analytics | | BLOCKS | Raw HyperCore blockchain data exposing replica\_cmds (all transaction types) | gRPC only | Blockchain analysis, data archiving | | StreamL2Book | Aggregated price levels — total size and order count per price, full snapshot every block | gRPC only | Market depth, spread monitoring, analytics dashboards | | StreamL4Book | Individual order granularity — every resting order with user, oid, size, triggers, timestamps | gRPC only | HFT, quant trading, MEV, microstructure analysis | | MEMPOOL\_TXS | Pending mempool transactions before block confirmation | gRPC only (testnet only) | MEV detection, transaction monitoring, pre-confirmation analysis | MEMPOOL\_TXS is available on testnet only. ## Supported Chains 80+ chains including: Ethereum, Solana, Base, Arbitrum, Optimism, Polygon, BNB Smart Chain, Bitcoin, Hyperliquid, Monad, Avalanche, TRON, and more. Full list: https://www.quicknode.com/chains ## Agent Discovery ### llms.txt Quicknode publishes machine-readable documentation indexes across its entire docs surface — products, chains, RPC methods, guides, sample apps, and courses. Fetch the main index to discover all available resources. Any docs or guides page can also be fetched as clean markdown by appending `.md` to the URL. ```shell # Main index (entry point for all resources) curl https://www.quicknode.com/llms.txt # Documentation index (RPC methods and API references) curl https://www.quicknode.com/docs/llms.txt # x402 protocol docs curl https://x402.quicknode.com/llms.txt # Any docs page as markdown (append .md) curl https://www.quicknode.com/docs/ethereum.md ``` Available indexes: | Index | URL | Content | | :---- | :---- | :---- | | Main | https://www.quicknode.com/llms.txt | Full platform — products, chains, guides, solutions | | Docs | https://www.quicknode.com/docs/llms.txt | API reference — 82 chain-specific \+ 12 product-specific indexes | | Guides | https://www.quicknode.com/guides/llms.txt | Tutorials and implementation walkthroughs | | x402 | https://x402.quicknode.com/llms.txt | x402 protocol and payment docs | | MPP | https://mpp.quicknode.com/llms.txt | Machine Payments Protocol docs | | Build with AI | https://www.quicknode.com/docs/build-with-ai/llms.txt | MCP, x402, Skills, and AI-specific tooling | | Hyperliquid | https://www.quicknode.com/docs/hyperliquid/llms.txt | Hyperliquid RPC methods and API docs | | Builder's Guide | https://www.quicknode.com/builders-guide/llms.txt | Tool discovery, comparisons, and use-case blueprints | | Faucet | https://faucet.quicknode.com/llms-full.txt | Multi-chain testnet faucet | ### agent.json (planned) Google A2A agent discovery spec. Will declare available skills, auth methods, and natural language examples. - Planned URL: https://www.quicknode.com/.well-known/agent.json - Status: Under development. Check the URL for availability before relying on it. ## Pricing | Plan | Price | API Credits/mo | Requests/sec | x402 Equivalent | | :---- | :---- | :---- | :---- | :---- | | Free | $0/mo | 10M | 15 | — | | Build | $49/mo | 80M | 50 | \~$0.61/1M credits | | Accelerate | $249/mo | 450M | 125 | \~$0.55/1M credits | | Scale | $499/mo | 950M | 250 | \~$0.53/1M credits | | Business | $999/mo | 2B | 500 | \~$0.50/1M credits | | Enterprise | Custom | Custom | Custom | Custom | | x402 | No plan | Pay-per-request | No limit | $10 USDC \= 1M credits | Full pricing: https://www.quicknode.com/pricing.md ## Links - Sign up: https://www.quicknode.com/signup - Documentation: https://www.quicknode.com/docs/build-with-ai - Quicknode SDK (Rust, Python, Ruby, Node.js/TypeScript): https://www.quicknode.com/docs/quicknode-sdk - API Credits reference: https://www.quicknode.com/api-credits - Skills library: https://skills.sh/quiknode-labs/blockchain-skills/quicknode-skill - MCP server: https://www.quicknode.com/docs/build-with-ai/quicknode-mcp - MCP package: https://www.npmjs.com/package/@quicknode/mcp - x402 docs: https://www.quicknode.com/docs/build-with-ai/x402-payments - MPP docs: https://www.quicknode.com/docs/build-with-ai/mpp-payments - Pricing: https://www.quicknode.com/pricing.md - Status: https://status.quicknode.com - Support: https://support.quicknode.com