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)
インストール @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

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?

使用方法 @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:

プロトコル	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
決済	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.

プロトコル	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.

対応している決済ネットワーク

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

Payment Network	トークン	Pay-per-request	Credit Drawdown	Nanopayment
ベース・セポリア	USDC	はい	はい	はい
Base Mainnet	USDC	はい	はい	いいえ
Polygon Amoy	USDC	はい	はい	はい
Polygon メインネット	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: 「」を使用してください 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.

仕組み

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 対スタンダード・クイックノード・プラン

	x402	Standard Plans
認証	None (SIWX + JWT only for credit drawdown)	API key
請求	Per request (or credit bundle for drawdown)	Monthly/Yearly subscription
セットアップが必要です	Wallet + stablecoin	アカウント + API キー
ステータス	アルファ	生産用SLA
こんな方に最適	エージェント、プロトタイピング、許可不要なアクセス	チーム、本番環境のワークロード

リソース

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

→

サンプルアプリ

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.

皆様からのフィードバックを心よりお待ちしております！❤️

このドキュメントについてご意見やご質問がございましたら、ぜひお知らせください。皆様からのご連絡を心よりお待ちしております！

概要​

Quick Start​

Pay-per-request​

Credit Drawdown​

Nanopayment​

Supported Protocols​

価格​

Credit Consumption Rates​

対応している決済ネットワーク​

認証​

仕組み​

x402 対 スタンダード・クイックノード・プラン​

リソース​

皆様からのフィードバックを心よりお待ちしております！❤️​

概要