Set up Quicknode with an AI agent

name: agents
title: Quicknode for AI Agents
description: Authenticate, pay for, and operate Quicknode infrastructure from an AI agent.
canonical: https://www.quicknode.com/agents.md
last-updated: 2026-08-23

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

Machine-readable surfaces

• Quicknode OpenAPI spec: https://www.quicknode.com/openapi.json
• Quicknode API versioning: https://www.quicknode.com/versioning.md
• Quicknode auth: https://www.quicknode.com/auth.md
• Quicknode MCP server card: https://www.quicknode.com/.well-known/mcp/server-card.json
• Quicknode MCP server: https://mcp.quicknode.com/mcp
• Quicknode agent plugins: https://github.com/quicknode/agent-plugins
• Quicknode CLI: https://www.quicknode.com/cli (brew install quicknode/tap/qn)
• Quicknode webhooks: https://www.quicknode.com/webhooks

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 the Build Web3 plugin
• AI assistant managing infrastructure? → Connect MCP Server

Authentication

Full authentication discovery: https://www.quicknode.com/auth.md

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.

Fastest path: Quicknode CLI

brew install quicknode/tap/qn
qn wallet generate --vm evm --name payer
qn rpc x402 drip --payment-wallet payer --payment-network base-sepolia
qn rpc call eth_blockNumber \
  --network ethereum-mainnet \
  --x402 \
  --payment-wallet payer \
  --payment-network base-sepolia \
  --payment-asset USDC \
  --max-amount 1000

CLI guide: https://github.com/quicknode/cli#micropayments

SDK path

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
• Quicknode SDK guide: https://github.com/quicknode/sdk/blob/main/npm/README.md#crypto-micropayment-lane-rpccall (Rust, Python, Node.js, Ruby)
• 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.

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.

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 <credential>). 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 the Build Web3 plugin (for AI coding agents)

Give your agent accurate knowledge of Quicknode's full API surface. The plugin bundles the build-web3 skill with the Quicknode MCP server.

Claude Code — plugin (skill + Quicknode MCP):

/plugin marketplace add quicknode/agent-plugins
/plugin install build-web3@quicknode-agent-plugins

Codex — plugin (skill + Quicknode MCP):

codex plugin marketplace add https://github.com/quicknode/agent-plugins.git
codex plugin add build-web3@quicknode-agent-plugins

Any agent — skill only, no account needed:

npx skills add quicknode/agent-plugins --skill build-web3

Works with: Claude Code, Cursor, Codex, OpenCode, Windsurf

Docs: https://www.quicknode.com/docs/build-with-ai/build-web3-plugin

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
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:

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.

# 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

auth.md

Authentication discovery file per the auth.md spec. Describes supported registration methods, identity types, credential types, and payment endpoints for agents.

• URL: https://www.quicknode.com/auth.md
• Fetch with Accept: text/markdown or directly as a static file.

agent-card.json

Google A2A agent discovery spec. Declares available skills, auth methods, supported interfaces, and natural language examples.

• URL: https://www.quicknode.com/.well-known/agent-card.json

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
• Build Web3 plugin: https://www.quicknode.com/docs/build-with-ai/build-web3-plugin
• Build Web3 skill (skills.sh): https://www.skills.sh/quicknode/agent-plugins/build-web3
• 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