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

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.

의정서	평가
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	네	네	네
폴리곤 메인넷	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)
우리 (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 vs 표준 Quicknode 요금제

	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 vs 표준 Quicknode 요금제​

자료​

여러분의 피드백을 ❤️ 환영합니다!​

개요