# 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.

## Choose Your Path

- **Autonomous agent, no account?** → x402 or MPP (pay-per-request with stablecoins)  
- **Agent with a Quicknode account?** → API Key  
- **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

## 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 data pipelines → **Streams**  
- Need Hyperliquid order book or trade data? → **HyperCore gRPC**  
- Need ad-hoc analytics across historical 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 | \~15 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 | \~15 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, Aptos, Dogecoin, Litecoin, Stellar |
| Tier 2 | 20 credits | Ethereum, Base, Arbitrum, Optimism, Polygon, BNB, Hyperliquid, \+30 more |
| Tier 3 | 30 credits | Solana, Monad, TRON, Gnosis, zkSync, \+5 more |
| Tier 4 | 40 credits | Cosmos, Sui, TON, Polkadot, Stacks, XRP, \+6 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, Solana getAsset |
| Large | 4x | txpool\_content, trace\_replayBlockTransactions |

**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
   
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
```

Each step uses standard RPC (20 credits on Ethereum). Simulation uses Advanced API (40 credits). Total cost for this flow: ~~160 credits (~~$0.0001 at Build plan rates).

## 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 (TRADES, ORDERS, BOOK\_UPDATES, TWAP, EVENTS, BLOCKS, WRITER\_ACTIONS) |
| Webhooks | Simple event-driven HTTP notifications | Standard | Best-effort |

## 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  
- 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  
- Status page: https://status.quicknode.com  
- Contact sales: https://www.quicknode.com/contact-us