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 a pay-per-request model built on the x402 protocol. Authenticate with your wallet, make calls (e.g., RPC, REST, gRPC-Web, WebSocket) across any supported network, and pay with stablecoins (USDC on Base, Polygon, or Solana; USDG on XLayer). 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.

• Understand how x402 enables wallet-based access to Quicknode endpoints (including RPC, REST, gRPC-Web, and WebSocket)
• Learn the authentication and payment flow (SIWX x402 Extension, JWT, credits, x402 settlement)
• Run the JSON-RPC example to make your first x402-powered call 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 wallet authentication (SIWX), JWT management, and x402 payment negotiation automatically. All you need is a wallet with USDC on Base Sepolia for the example in this guide. You can get testnet USDC from the Circle faucet.

Why x402 on Quicknode

x402 adds a new way to consume Quicknode's infrastructure alongside existing plans. x402 supports two access patterns: pay-per-request ($0.001 per call, no authentication needed) and credit drawdown ($10 for 1,000,000 requests via SIWX authentication). 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 follows a drawdown credit model: authenticate with your wallet, pay with a supported stablecoin (USDC or USDG) to receive credits, then consume those credits across requests. When credits run out, another payment is triggered automatically.

Step-by-Step Breakdown

The @quicknode/x402 package handles the entire 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 how much USDC to pay and on which 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

x402 on Quicknode supports stablecoin payments on Base, Polygon, XLayer, and Solana:

Option	Token	Best For	Pricing
Base Sepolia	USDC	Testing and experimentation	100 credits per $0.01, up to 10,000 credits per $1.00
Base Mainnet	USDC	Production usage	1,000,000 credits for $10
Polygon Amoy	USDC	Testing and experimentation	100 credits per $0.01, up to 10,000 credits per $1.00
Polygon Mainnet	USDC	Production usage	1,000,000 credits for $10
XLayer Testnet	USDG	Testing and experimentation	100 credits per $0.01, up to 10,000 credits per $1.00
XLayer Mainnet	USDG	Production usage	1,000,000 credits for $10
Solana Devnet	USDC	Testing and experimentation	100 credits per $0.01, up to 10,000 credits per $1.00
Solana Mainnet-beta	USDC	Production usage	1,000,000 credits for $10

This lets developers and agents interact with x402 flows in a test environment without risking real funds, and then seamlessly transition to mainnet when ready.

Note: We plan to add support for additional payment networks over time based on demand.

Supported Networks through x402

Once you've paid via x402, you can use your credits to make calls across 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

One of the most powerful aspects of x402 on Quicknode is that it works across multiple protocols. The same wallet-based authentication and payment flow applies whether you're making a standard JSON-RPC call, querying a REST API, streaming data over gRPC, or subscribing to real-time events via WebSocket.

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

This means a single wallet and a single authentication flow can give you access to any of Quicknode's supported chains across all four protocols. For example, EVM chains or Solana via JSON-RPC, Aptos via REST, Flow via gRPC, and real-time Ethereum data via WebSocket. The x402 payment layer works the same across all of them.

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

The fastest way to experience x402 on Quicknode is with the @quicknode/x402 package. We'll make eth_blockNumber calls on Base Sepolia and getSlot calls on Solana Devnet, showing the full authentication and payment cycle.

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() {
	// Create client — 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,
		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 SIWX authentication, JWT management, and x402 payment negotiation:

import { createQuicknodeX402Client } from '@quicknode/x402'

const client = await createQuicknodeX402Client({
	baseUrl: 'https://x402.quicknode.com',
	network: 'eip155:84532',
	evmPrivateKey: '0xYOUR_PRIVATE_KEY',
	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
preAuth	When true, the client pre-authenticates by signing the SIWX message and acquiring a JWT before the first request. This makes the payment flow faster (auth then pay, instead of: see 402, auth, then pay)

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-authenticated access with pay-per-request ($0.001/call) or credit drawdown ($10/1M requests). 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. Each one uses the same authentication and payment flow, so you can try them all with the credits you already have.

Move to Mainnet

Testnet payments on Base Sepolia, Polygon Amoy, XLayer Testnet, or Solana Devnet give you up to 10,000 free requests against Quicknode's production endpoints. After these credits are used up, switch to the corresponding mainnet for production usage. The authentication and 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, authenticate with a wallet, pay with a supported stablecoin (USDC or USDG), 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.