x402 Payments

Overview

x402 on Quicknode provides pay-per-request access to blockchain endpoints across all supported networks. Instead of creating an account and managing API keys, any application or AI agent with a wallet and a supported stablecoin can start making calls immediately.

x402 is an open payment standard by Coinbase built on the HTTP 402 "Payment Required" status code. Client libraries handle the payment negotiation automatically.

x402 on Quicknode supports three access patterns:

Pay-per-request: No authentication required. Each request includes a payment signature handled automatically by the client.
Credit drawdown: Authenticate once with SIWX, purchase a credit bundle, and consume credits per request. Required for gRPC-Web and WebSocket transports.
Nanopayment: Batched payments via Circle Gateway. The payment chain is limited to selected EVM testnets (Base Sepolia, Polygon Amoy, Arc Testnet).

Regardless of which payment model or payment chain you use, you can query any of Quicknode's supported networks.

x402 is an additive access method. It does not replace Quicknode's standard plans. Teams running production workloads benefit from standard plans with SLAs, dedicated support, and higher rate limits. x402 is designed for AI agents, rapid prototyping, and use cases where permissionless access is the priority.

info

x402 on Quicknode is currently in alpha.

# Fetch machine-readable x402 documentation for AI agents
curl https://x402.quicknode.com/llms.txt

Quick Start

Install the @quicknode/x402 package regardless of which payment model you choose, as the client supports all three patterns with configuration options.

npm install @quicknode/x402

Pay-per-request
Credit Drawdown
Nanopayment

Pay-per-request

Pay-per-request requires no authentication or session state. Each request includes a payment signature handled automatically by the client.

import { createQuicknodeX402Client } from '@quicknode/x402'

const client = await createQuicknodeX402Client({
	baseUrl: 'https://x402.quicknode.com',
	network: 'eip155:84532', // Base Sepolia (payment network)
	evmPrivateKey: process.env.PRIVATE_KEY as `0x${string}`,
	paymentModel: 'pay-per-request',
})

// The endpoint below is the chain you want to query (not the payment chain).
// You can call any Quicknode-supported network here regardless of which chain you pay on.
const response = await client.fetch('https://x402.quicknode.com/base-mainnet', {
	method: 'POST',
	headers: { 'Content-Type': 'application/json' },
	body: JSON.stringify({
		jsonrpc: '2.0',
		id: 1,
		method: 'eth_blockNumber',
		params: [],
	}),
})

const data = await response.json()
console.log('Block:', data.result)

Credit Drawdown

Credit drawdown authenticates once via SIWX to obtain a JWT, then purchases a credit bundle upfront. Credits are consumed per request. This is the only model that supports gRPC-Web and WebSocket transports.

import { createQuicknodeX402Client } from '@quicknode/x402'

const client = await createQuicknodeX402Client({
	baseUrl: 'https://x402.quicknode.com',
	network: 'eip155:84532', // Base Sepolia (payment network)
	evmPrivateKey: process.env.PRIVATE_KEY as `0x${string}`,
	paymentModel: 'credit-drawdown', // default if omitted
	preAuth: true, // pre-authenticates (SIWX + JWT) before the first request
})

// The endpoint below is the chain you want to query (not the payment chain).
// You can call any Quicknode-supported network here regardless of which chain you pay on.
const response = await client.fetch('https://x402.quicknode.com/base-mainnet', {
	method: 'POST',
	headers: { 'Content-Type': 'application/json' },
	body: JSON.stringify({
		jsonrpc: '2.0',
		id: 1,
		method: 'eth_blockNumber',
		params: [],
	}),
})

const data = await response.json()
console.log('Block:', data.result)

Nanopayment

Nanopayment uses Circle's Gateway infrastructure to batch payments with no per-request on-chain settlement. It requires a one-time USDC deposit into the Gateway Wallet contract before making requests. After depositing, the Gateway API waits for a chain-specific number of block confirmations before updating your unified balance. See Circle's supported blockchains reference for confirmation times per chain.

import { createQuicknodeX402Client } from "@quicknode/x402";

const client = await createQuicknodeX402Client({
  baseUrl: "https://x402.quicknode.com",
  network: "eip155:84532", // Base Sepolia (payment network; must be a nanopayment-eligible EVM testnet)
  evmPrivateKey: process.env.PRIVATE_KEY as `0x${string}`,
  paymentModel: "nanopayment",
});

// Check Gateway Wallet balance
if (client.gatewayClient) {
  const balances = await client.gatewayClient.getBalances();
  console.log("Gateway available:", balances.gateway.formattedAvailable);

  // 1 USDC = 1_000_000 base units (6 decimals)
  // If balance is low, deposit more USDC to avoid payment failures
  if (balances.gateway.available < 1_000_000n) {
    console.log("Depositing 1 USDC...");
    const deposit = await client.gatewayClient.deposit("1");
    console.log(`Deposit tx: ${deposit.depositTxHash}`);
  }
}

// $0.0001 per request, payments batched via Circle Gateway (no per-request auth)
// The endpoint below is the chain you want to query (not the payment chain).
// You can call any Quicknode-supported network here regardless of which chain you pay on.
const response = await client.fetch("https://x402.quicknode.com/base-mainnet", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "eth_blockNumber",
    params: [],
  }),
});

const data = await response.json();
console.log("Block:", data.result);

Building with Solana?

Use @quicknode/x402-solana, a dedicated Solana Kit integration that creates x402-enabled RPC and WebSocket clients directly from your Solana keypair. No account or API key required, just a wallet with USDC. Check out the How to Access Solana RPC with x402 guide for a full walkthrough.

npm install @quicknode/x402-solana

See the examples repo for reference implementations.

Supported Protocols

x402 endpoints support the same protocols as standard Quicknode endpoints. Protocol availability varies by payment model:

Protocol	Pay-per-request	Credit Drawdown	Nanopayment
JSON-RPC	Yes	Yes	Yes
REST	Yes	Yes	Yes
gRPC-Web	No	Yes	No
WebSocket	No	Yes	No

Pricing

x402 on Quicknode supports three billing patterns:

	Pay-per-request	Credit Drawdown	Nanopayment
Cost	$0.001 per request	$10 per 1,000,000 credits (~$0.00001 per request)	$0.0001 per request
Settlement	One on-chain payment per request	Upfront credit purchase, consumed per response	Batched via Circle Gateway (gasless after initial USDC deposit)
Authentication	None	SIWX + JWT	None (Circle Gateway Wallet deposit required)
Testnet cap	1,000 requests	1,000 credits	10,000 requests
Best for	Simple integrations, low volume	Sustained usage, streaming protocols	High-volume testing, sub-cent cost

Credit Consumption Rates

For the credit drawdown pattern, each successful response consumes credits based on the protocol used. When credits are depleted, the next request triggers an automatic payment for a new credit bundle.

Protocol	Rate
JSON-RPC (HTTP)	1 credit per successful (HTTP 200) response
REST (HTTP)	1 credit per successful response
gRPC-Web	1 credit upfront + 1 credit per 10 KB of response data
WebSocket	1 credit upfront + 1 credit per response message

Error responses, JSON-RPC errors, and non-200 HTTP status codes are not metered. Testnet caps are tracked independently per payment type.

Supported Payment Networks

These are the chains you pay on. The chain you pay on does not need to match the chain you query.

Payment Network	Token	Pay-per-request	Credit Drawdown	Nanopayment
Base Sepolia	USDC	Yes	Yes	Yes
Base Mainnet	USDC	Yes	Yes	No
Polygon Amoy	USDC	Yes	Yes	Yes
Polygon Mainnet	USDC	Yes	Yes	No
XLayer Testnet	USDG	Yes	Yes	No
XLayer Mainnet	USDG	Yes	Yes	No
Arc Testnet	USDC	No	No	Yes
Solana Devnet	USDC	Yes	Yes	No
Solana Mainnet	USDC	Yes	Yes	No

To get testnet tokens:

Base Sepolia / Polygon Amoy / Arc Testnet: Use the Circle faucet for USDC. Base Sepolia also has a built-in /drip endpoint on the x402 gateway.
XLayer Testnet: Pre-fund your wallet with USDG on XLayer Testnet.
Solana Devnet: Pre-fund your wallet with USDC on Solana Devnet via the Circle faucet.

Authentication

Authentication is required for credit drawdown only. Pay-per-request and nanopayment include the payment signature in each request and do not require a JWT.

For credit drawdown, the /auth endpoint accepts three authentication paths:

SIWE (EVM only): Post a signed EIP-4361 SIWE message. This is the original auth method and remains fully supported.
SIWX/EVM: Same SIWE message format with "type": "siwx" in the request body.
SIWX/Solana: A CAIP-122 / SIWS formatted message signed with Ed25519, encoded as Base58, with "type": "siwx".

All paths require the following fields in the signed message:

domain (x402.quicknode.com)
address (your wallet address)
uri (https://x402.quicknode.com)
version (1)
chainId (the chain ID of the network you pay on)
nonce (at least 8 random characters)
issuedAt (current ISO 8601 timestamp, within 5 minutes).

The auth response returns a JWT that expires in 1 hour. Include Authorization: Bearer <JWT> on all subsequent requests.

How It Works

The flow below describes the credit drawdown model. For pay-per-request and nanopayment, steps 1 and 2 are skipped; each request includes a payment signature directly with no prior authentication.

The @quicknode/x402 client handles the full payment flow automatically. Under the hood, the credit drawdown flow follows this sequence:

Authenticate. Sign a message with your wallet (SIWE for EVM, SIWX for Solana) and exchange it for a JWT token at the /auth endpoint.
Make requests. Send requests to POST /:network with the JWT in the Authorization: Bearer header. Requests work across JSON-RPC, REST, gRPC-Web, and WebSocket protocols.
Pay when prompted. When credits run out, the server returns HTTP 402. The client automatically signs a stablecoin payment and retries the request.
Repeat. Credits are consumed per successful response. When exhausted, the next request triggers a new payment automatically.

x402 vs Standard Quicknode Plans

	x402	Standard Plans
Authentication	None (SIWX + JWT only for credit drawdown)	API key
Billing	Per request (or credit bundle for drawdown)	Monthly/Yearly subscription
Setup required	Wallet + stablecoin	Account + API key
Status	Alpha	Production SLA
Best for	Agents, prototyping, permissionless access	Teams, production workloads

Resources

Getting Started Guide

Step-by-step walkthrough for x402 on Quicknode

→

Video Walkthrough

How to get started with x402 on Quicknode

→

Protocol Explainer

Deep dive on how x402 works

→

Example Implementations

End-to-end demonstrations of the x402 payment protocol

→

Sample App

Explore x402 payments through a simple UI

→

Protocol Specification

Open-source x402 protocol by Coinbase

→

tip

For an alternative payment protocol, see MPP Payments. For managing Quicknode infrastructure through natural language, see Quicknode MCP. For giving AI coding agents accurate Quicknode API knowledge, see Blockchain Skills.

We ❤️ Feedback!

If you have any feedback or questions about this documentation, let us know. We'd love to hear from you!

Overview​

Quick Start​

Pay-per-request​

Credit Drawdown​

Nanopayment​

Supported Protocols​

Pricing​

Credit Consumption Rates​

Supported Payment Networks​

Authentication​

How It Works​

x402 vs Standard Quicknode Plans​

Resources​

We ❤️ Feedback!​