12 min read

Overview

Quicknode's infrastructure powers billions of requests across all supported blockchain networks. With x402 on Quicknode, any client with a wallet can access that same infrastructure through three payment models built on the x402 protocol: pay-per-request, nanopayment, and credit drawdown. Pay with a supported stablecoin. No account, API keys, or subscription needed.

This opens up new possibilities for how developers and AI agents consume blockchain infrastructure. Instead of provisioning an endpoint upfront, you connect a wallet and start making calls immediately across JSON-RPC, REST, gRPC-Web, and WebSocket protocols.

This guide walks you through how x402 on Quicknode works, who it's for, and how to make your first x402-powered RPC request.

Alpha Release

x402 on Quicknode is currently in alpha. It's designed for experimentation and early adoption. While the underlying infrastructure is the same production-grade system that powers Quicknode's platform, the x402 access layer is new and evolving. Expect potential API changes, shifting rate limits, and ongoing feature refinement as the product matures.

Agentic Payments

Quicknode also supports MPP (Machine Payments Protocol) for agentic payments. MPP uses IETF Payment Authentication headers and offers charge and session-based access patterns. See the Agentic Payments overview for a side-by-side comparison.

• Compare the three payment models (pay-per-request, nanopayment, credit drawdown) and pick the right one for your use case
• Run the JSON-RPC example using credit drawdown to see the full authentication and payment cycle on Base Sepolia
• Explore multi-protocol examples across JSON-RPC, REST, gRPC-Web, and WebSocket

Subscribe to our YouTube channel for more videos!Subscribe

What You Will Need

• Node.js (v20 or higher) and npm
• Basic familiarity with blockchain concepts

That's it. You don't need a Quicknode account or API keys. The @quicknode/x402 package handles authentication, payment signing, and negotiation automatically (the specifics depend on which payment model you choose). For the credit drawdown example in this guide, you'll need a wallet with testnet USDC on Base Sepolia. You can get some from the Circle faucet.

Why x402 on Quicknode

x402 adds a new way to consume Quicknode's infrastructure alongside existing plans. x402 supports three access patterns: pay-per-request, nanopayment, and credit drawdown. It's designed for use cases where wallet-based, on-demand access is a better fit than traditional account setup:

• AI agents and autonomous bots that need to authenticate and pay without human intervention. An agent only needs a wallet with a supported stablecoin to start making calls.
• Developers building agent-based tools where end users interact with Quicknode infrastructure without needing their own accounts.
• Low-usage developers who want occasional access to high-quality endpoints across multiple chains without committing to a plan.
• Privacy-focused users who prefer wallet-based access over account registration.
• Experimentation and prototyping where developers want to test across networks quickly without setup overhead.

The key difference: existing plans are optimized for sustained usage with predictable billing. x402 is optimized for on-demand access where every request is individually funded.

How It Works

x402 on Quicknode supports three payment models. All three use the @quicknode/x402 client; the paymentModel option controls which one is active:

• Pay-per-request (paymentModel: 'pay-per-request'): No authentication required. Each request includes a payment signature handled automatically by the client.
• Nanopayment (paymentModel: 'nanopayment'): No authentication required. Batched payments via Circle Gateway. Requires a one-time USDC deposit into the Gateway Wallet contract; the Gateway API waits for chain-specific block confirmations before updating your balance. Payment chains are limited to selected EVM testnets (Base Sepolia, Polygon Amoy, Arc Testnet).
• Credit Drawdown (paymentModel: 'credit-drawdown', default): Authenticate once with SIWX, purchase a credit bundle, and consume credits per request. Required for gRPC-Web and WebSocket transports.

Regardless of which payment model or payment chain you use, you can query any of Quicknode's supported networks. See the Multi-Protocol Support section for protocol availability per model.

The diagram below shows the credit drawdown flow, which the example in this guide uses. For pay-per-request and nanopayment, steps 1 and 2 are skipped: each request includes a payment signature directly with no prior authentication.

Credit Drawdown: Step-by-Step

The @quicknode/x402 package handles the entire credit drawdown flow automatically when you set preAuth: true. You don't need to implement these steps manually. Here's what happens under the hood:

1. Authenticate with SIWX

The client signs a Sign-In-With-X (SIWX) message using their wallet. This proves ownership of the wallet address without exposing any private keys. The proxy returns a JWT token (valid for one hour) that the client includes in subsequent requests.

2. First Request Returns 402

When you make your first call (or any call with zero credits), the proxy responds with HTTP 402 Payment Required. This response includes payment requirements following the x402 v2 specification, specifying the payment amount and network.

3. Pay and Receive Credits

The client signs a stablecoin payment authorization (EIP-712 for EVM, SPL transfer for Solana) and retries the request with the payment header. The x402 facilitator settles the payment on-chain, and the proxy credits your account with a request bundle.

4. Consume Credits

From that point, each request deducts one credit. When the balance hits zero, the next request triggers another 402, and the cycle repeats. The infrastructure behind the proxy is the same production system that powers all Quicknode endpoints.

Payment Options

Model	Cost	Testnet Cap	Best For
Pay-per-request	$0.001 per request	1,000 requests	Simple integrations, low volume
Nanopayment	$0.0001 per request	10,000 requests	High-volume testing, sub-cent cost
Credit Drawdown	Testnet: $1 for 1,000 credits. Mainnet: $10 for 1,000,000 credits	1,000 credits	Sustained usage, gRPC-Web, WebSocket

Testnet caps are tracked independently per payment model. After reaching a cap, switch to mainnet for production usage.

For the full list of supported payment networks and which models each one supports, see the Supported Payment Networks table in the x402 reference docs.

Supported Networks through x402

Regardless of which payment model or payment network you use, you can query any of Quicknode's supported blockchain networks, including Ethereum, Base, Solana, Arbitrum, Polygon, Aptos, Flow, and many more.

For the full list of supported chains, see Quicknode's supported chains page.

Multi-Protocol Support

x402 on Quicknode works across multiple protocols, though protocol availability depends on the payment model. Pay-per-request and nanopayment support JSON-RPC and REST only. gRPC-Web and WebSocket require credit drawdown.

Protocol	Pay-per-request	Nanopayment	Credit Drawdown	Use Case
JSON-RPC	Yes	Yes	Yes	Standard RPC calls (e.g., eth_blockNumber, getBlock)
REST	Yes	Yes	Yes	HTTP GET endpoints (e.g., /v1/blocks/by_height)
gRPC-Web	No	No	Yes	Unary calls and server-side streaming for high-performance chains (e.g., GetLatestBlock)
WebSocket	No	No	Yes	Real-time subscriptions (e.g., eth_subscribe, accountSubscribe)

A single wallet gives you access to any of Quicknode's supported chains across all four protocols: EVM chains or Solana via JSON-RPC, Aptos via REST, Flow via gRPC, and real-time Ethereum data via WebSocket.

The qn-x402-examples repository includes working scripts for each protocol. In the next section, we'll walk through a basic JSON-RPC example step by step, and you can explore the working scripts at your own pace.

Getting Started: JSON-RPC Example

This walkthrough uses the credit drawdown model to demonstrate the full authentication and payment cycle. If you prefer to skip authentication entirely, set paymentModel: 'pay-per-request' in the client config instead.

We'll make eth_blockNumber calls on Base Sepolia and getSlot calls on Solana Devnet using the @quicknode/x402 package.

The qn-x402-examples repository also includes its own JSON-RPC example along with REST, gRPC-Web, and WebSocket scripts, all with built-in faucet support for Base Sepolia. The guide below builds a standalone script from scratch so you can see each step clearly.

Step 1: Set Up the Project

mkdir x402-quickstart && cd x402-quickstart
npm init -y
npm install @quicknode/x402 tsx

Step 2: Create the .env File

Create a .env file in the root of your project and add your EVM private key (for Base Sepolia):

.env

PRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE

Step 3: Create the Script

Create a file called index.ts. This script creates a client with @quicknode/x402, makes repeated eth_blockNumber and getSlot calls to consume credits, and logs the remaining credits after each call.

index.ts

import { createQuicknodeX402Client } from '@quicknode/x402'

const X402_BASE_URL = 'https://x402.quicknode.com'
const NETWORK = 'eip155:84532' // Base Sepolia

async function main() {
	// Credit drawdown: preAuth speeds up payment by authenticating (SIWX + JWT) upfront
	const client = await createQuicknodeX402Client({
		baseUrl: X402_BASE_URL,
		network: NETWORK,
		evmPrivateKey: process.env.PRIVATE_KEY || undefined,
		paymentModel: 'credit-drawdown',
		preAuth: true,
	})

	console.log('Client ready. Payment will be made with USDC on Base Sepolia.')
	console.log(
		'Making calls: eth_blockNumber on Base Sepolia and getSlot on Solana Devnet...\n'
	)

	// Make requests in a loop to see credit consumption
	for (let i = 1; i <= 10; i++) {
		const evmResponse = await client.fetch(`${X402_BASE_URL}/base-sepolia`, {
			method: 'POST',
			headers: { 'Content-Type': 'application/json' },
			body: JSON.stringify({
				jsonrpc: '2.0',
				id: i,
				method: 'eth_blockNumber',
				params: [],
			}),
		})

		const evmData = await evmResponse.json()
		const block = BigInt(evmData.result)
		console.log(`Request #${i}: Block ${block}`)
		console.log(
			'Credits:',
			(
				await fetch('https://x402.quicknode.com/credits', {
					headers: { Authorization: `Bearer ${client.getToken()}` },
				}).then(r => r.json())
			).credits
		)

		const solanaResponse = await client.fetch(
			'https://x402.quicknode.com/solana-devnet',
			{
				method: 'POST',
				headers: { 'Content-Type': 'application/json' },
				body: JSON.stringify({
					jsonrpc: '2.0',
					id: 1,
					method: 'getSlot',
					params: [],
				}),
			}
		)
		const solanaData = await solanaResponse.json()
		const slot = solanaData.result
		console.log(`Request #${i}: Solana Slot ${slot}`)
		console.log(
			'Credits:',
			(
				await fetch('https://x402.quicknode.com/credits', {
					headers: { Authorization: `Bearer ${client.getToken()}` },
				}).then(r => r.json())
			).credits
		)

		console.log('\n')
	}
}

main().catch(console.error)

Step 4: Run It

Testnet USDC Required

Your wallet needs Base Sepolia USDC before making x402 payments. You can get testnet USDC from the Circle faucet. Alternatively, the qn-x402-examples repo includes a setupExample helper with built-in auto-faucet logic for an automated flow.

npx tsx --env-file=.env index.ts

On the first run, the client will:

1. Create a client with the provided private key and configuration
2. Pre-authenticate via SIWX (with preAuth: true) by signing a message and acquiring a JWT upfront
3. Make eth_blockNumber and getSlot calls, consuming one credit per successful response
4. Handle the 402 payment automatically when credits run out

Expected output

Client ready. Payment will be made with USDC on Base Sepolia.
Making calls: eth_blockNumber on Base Sepolia and getSlot on Solana Devnet...

Request #1: Block 38357505
Credits: 99
Request #1: Solana Slot 445776251
Credits: 98

Request #2: Block 38357506
Credits: 97
Request #2: Solana Slot 445776252
Credits: 96

# ... if you run the script multiple times, you'll see the 402 payment flow in action when credits run out:

Request #4: Block 38375819
Credits: 1
Request #4: Solana Slot 445872102
Credits: 0

Request #5: Block 38375821
Credits: 99
Request #5: Solana Slot 445872112
Credits: 98

Solana Prerequisites

To use x402 with Solana, you need a wallet with Devnet USDC. The /drip faucet is EVM-only, so Solana wallets must be funded manually.

1. Set up a Solana wallet: Generate a new keypair or use an existing Base58-encoded secret key.

   To generate a new Solana keypair:

   npm install tweetnacl bs58
   npx tsx -e "
   import nacl from 'tweetnacl'; import bs58 from 'bs58';
   const kp = nacl.sign.keyPair();
   console.log('Public key:', bs58.encode(Buffer.from(kp.publicKey)));
   console.log('Secret key:', bs58.encode(Buffer.from(kp.secretKey)));
   "

2. Fund with Solana Devnet USDC: Visit faucet.circle.com and request Devnet USDC (mint: 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU) for your wallet address. You do not need SOL. The x402 facilitator pays transaction fees.

3. Create the client with Solana config:

import { createQuicknodeX402Client } from '@quicknode/x402'

const client = await createQuicknodeX402Client({
	baseUrl: 'https://x402.quicknode.com',
	network: 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1', // Solana Devnet
	svmPrivateKey: '<YOUR_BASE58_SECRET_KEY>',
	preAuth: true,
})

The svmPrivateKey parameter accepts a Base58-encoded secret key. For EVM chains, use evmPrivateKey with a hex-encoded key instead.

Then, you can make calls to any chain (not just Solana) using the same client, and payments will be made with your Solana Devnet USDC.

Understanding the Code

Let's look at the key parts of how the example works.

Client Setup

The createQuicknodeX402Client function creates a client that handles payment negotiation across all three models. For credit drawdown, it also manages SIWX authentication and JWT sessions:

import { createQuicknodeX402Client } from '@quicknode/x402'

const client = await createQuicknodeX402Client({
	baseUrl: 'https://x402.quicknode.com',
	network: 'eip155:84532',
	evmPrivateKey: process.env.PRIVATE_KEY as `0x${string}`,
	paymentModel: 'credit-drawdown',
	preAuth: true,
})

Parameter	Description
baseUrl	The x402 gateway URL. Default: https://x402.quicknode.com
network	CAIP-2 chain identifier for the payment network (e.g., eip155:84532 for Base Sepolia, solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 for Solana Devnet)
evmPrivateKey	Hex-encoded private key for EVM chains. For Solana, use svmPrivateKey with a Base58-encoded key
paymentModel	'pay-per-request', 'nanopayment', or 'credit-drawdown' (default). Controls authentication and payment behavior
preAuth	Credit drawdown only. When true, pre-authenticates (SIWX + JWT) before the first request, making the payment flow faster

Making Requests

The client.fetch method matches the standard Fetch API. Authentication and payments are handled transparently:

const evmResponse = await client.fetch(`${X402_BASE_URL}/base-sepolia`, {
	method: 'POST',
	headers: { 'Content-Type': 'application/json' },
	body: JSON.stringify({
		jsonrpc: '2.0',
		id: i,
		method: 'eth_blockNumber',
		params: [],
	}),
})

const evmData = await evmResponse.json()
const block = BigInt(evmData.result)
console.log(`Request #${i}: Block ${block}`)

const solanaResponse = await client.fetch(
	'https://x402.quicknode.com/solana-devnet',
	{
		method: 'POST',
		headers: { 'Content-Type': 'application/json' },
		body: JSON.stringify({
			jsonrpc: '2.0',
			id: 1,
			method: 'getSlot',
			params: [],
		}),
	}
)
const solanaData = await solanaResponse.json()
const slot = solanaData.result
console.log(`Request #${i}: Solana Slot ${slot}`)

Use the URL format https://x402.quicknode.com/{network} to target different chains. The payment network (set in network during client creation) does not need to match the chain you are querying.

Exploring Other Request Types

After running the example in the guide, explore the other scripts in the qn-x402-examples repository to see x402 in action across different protocols and chains. All examples use @quicknode/x402.

REST API

The rest.ts script demonstrates x402 with REST API endpoints on Aptos Mainnet. It makes standard HTTP GET requests to endpoints like /v1/ (ledger info), /v1/blocks/by_height/{h}, and /v1/accounts/0x1.

npm run start:rest

gRPC-Web

The grpc.ts script showcases both unary calls (Ping, GetLatestBlock) and server-side streaming (SubscribeBlocksFromLatest) on Flow Mainnet using @connectrpc/connect-web.

npm run start:grpc

WebSocket

The websocket.ts script subscribes to newHeads on Base Mainnet via eth_subscribe, receiving real-time block headers as they're produced. It uses a non-blocking credit poller to track remaining credits without interrupting the data stream. When credits are exhausted, the connection handles the 4402 close code and can re-authenticate automatically.

npm run start:ws

For full details on each script, including configuration options and network overrides, see the examples repo README.

Building with AI on Quicknode

x402 is one layer of Quicknode's AI and agent tooling. Each tool addresses a different part of the workflow: discovering documentation, generating correct code, accessing endpoints, and managing infrastructure. The Build with AI docs cover the full suite:

• LLM-Optimized Docs: llms.txt indexes that help LLMs discover the right Quicknode content for any question.
• Blockchain Skills: A lightweight reference package that gives AI coding agents accurate Quicknode API knowledge. One command to install: npx skills add quiknode-labs/blockchain-skills.
• x402 Payments: Wallet-based access with three payment models (pay-per-request, nanopayment, credit drawdown). What this guide covers.
• MPP Payments: Pay-per-request access using IETF Payment Authentication headers, with per-request ($0.001) and session-based ($0.00001/request) pricing.
• Quicknode MCP: Manage Quicknode infrastructure through natural language in Claude Code, Cursor, Codex, and other MCP-compatible agents.

Try x402 for Hyperliquid Datasets

Quicknode's open-source HyperCore CLI also supports x402 access. Developers can stream and backfill Hyperliquid datasets directly from the terminal, paying per request with a wallet instead of needing a Quicknode account.

Next Steps

Now that you've seen x402 on Quicknode in action, here are some ways to go further:

Try the Other Protocols

This guide walked through a JSON-RPC example, but the qn-x402-examples repository includes working scripts for REST, gRPC-Web, and WebSocket as well. gRPC-Web and WebSocket require credit drawdown; JSON-RPC and REST work with all three payment models.

Move to Mainnet

Testnet accounts have a lifetime cap per payment model (1,000 credits for credit drawdown, 1,000 requests for pay-per-request, 10,000 requests for nanopayment). These caps are tracked independently. After reaching a cap, switch to the corresponding mainnet for production usage. The payment mechanics are identical, just with real funds.

Build Agent Workflows

Integrate x402 into your AI agent or bot. The @quicknode/x402 package handles authentication and payments automatically, so any application that uses fetch can be adapted with minimal changes. Since the entire flow is HTTP-based, any client that can sign messages and make HTTP requests can use it.

Dive Deeper into x402

For a technical deep dive into the x402 protocol itself, check out:

• x402 Protocol Specification: The open-source protocol spec by Coinbase
• x402 on Quicknode: Instant Blockchain Access for Developers and AI Agents: Quicknode's announcement blog post on x402
• How to Implement a Crypto Paywall with x402: Build your own x402-powered paywall
• x402 Payment Integration with Rails: Server-side x402 integration for Ruby on Rails
• x402 Protocol Explained: Quicknode's deep dive blog post on x402

Conclusion

x402 on Quicknode opens a new way to consume blockchain infrastructure, designed for agents, bots, and developers who want on-demand access with wallet-based authentication. Install @quicknode/x402, pay with a supported stablecoin using pay-per-request, nanopayment, or credit drawdown, and access all supported networks using JSON-RPC, REST, gRPC-Web, or WebSocket. No signup required.

This is an alpha release, and we're actively iterating based on developer and agent feedback. If you have questions, ideas, or run into issues, reach out on our Discord server or provide feedback using the form below. Stay up to date by following us on X and our Telegram announcement channel.

We ❤️ Feedback!

Let us know if you have any feedback or requests for new topics. We'd love to hear from you.