x402 Payments

概覽

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.

簡而言之

x402 can be used two ways: one-shot RPC calls with a funded wallet and no account (covered on this page), or paying for an Agent Subscription to create a Quicknode account and receive a full platform API key for the full product suite
Three one-shot access patterns: pay-per-request (self-contained per call), credit drawdown (SIWX auth + bundle, required for gRPC-Web and WebSocket), and nanopayment (Circle Gateway)
Install @quicknode/x402, which handles the full payment negotiation automatically; payment chain is independent of the RPC chain

資訊

x402 on Quicknode is currently in alpha.

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

快速入門

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?

使用 @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	是的	是的	是的
REST	是的	是的	是的
gRPC-Web	不	是的	不
WebSocket	不	是的	不

定價

x402 on Quicknode supports three billing patterns:

	Pay-per-request	Credit Drawdown	Nanopayment
成本	$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)
驗證	無	SIWX + JWT	None (Circle Gateway Wallet deposit required)
免費方案	Shared 1M API credits / month bucket	Shared 1M API credits / month bucket	Shared 1M API credits / month bucket
最適合	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. Each wallet gets a single free tier of 1,000,000 API credits / month across Quicknode's agentic payment surfaces, including all x402 payment models and MPP. RPC requests consume 1 API credit each, while SQL Explorer consumes the API credits used by the query. The bucket resets on the first of the month, and paid usage continues at the applicable per-model rate after the free tier is exhausted.

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
基礎塞波利亞	USDC	是的	是的	是的
Base Mainnet	USDC	是的	是的	不
Polygon Amoy	USDC	是的	是的	是的
Polygon Mainnet	USDC	是的	是的	不
XLayer Testnet	USDG	是的	是的	不
XLayer Mainnet	USDG	是的	是的	不
Arc Testnet	USDC	不	不	是的
Solana Devnet	USDC	是的	是的	不
Solana Mainnet	USDC	是的	是的	不

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

網域 (x402.quicknode.com)
地址 (your wallet address)
uri (https://x402.quicknode.com)
版本 (1)
chainId (the chain ID of the network you pay on)
非重複數 (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.

該 @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 終點。
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
驗證	None (SIWX + JWT only for credit drawdown)	API key
帳單	Per request (or credit bundle for drawdown)	Monthly/Yearly subscription
Setup required	Wallet + stablecoin	帳戶 + API 金鑰
狀態	Alpha	Production SLA
最適合	Agents, prototyping, permissionless access	Teams, production workloads

資源

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

→

提示

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.

我們 ❤️ 您的回饋！

如果您對這份文件有任何意見或疑問，請告訴我們。我們非常樂意聽取您的意見！

概覽​

快速入門​

Pay-per-request​

Credit Drawdown​

Nanopayment​

Supported Protocols​

定價​

Credit Consumption Rates​

Supported Payment Networks​

驗證​

How It Works​

x402 vs Standard Quicknode Plans​

資源​

我們 ❤️ 您的回饋！​

概覽