@quicknode/x402

Multi-chain payment client for Quicknode's x402 RPC proxy. Supports two payment models: per-request ($0.001/request, no auth) and credit drawdown (SIWX auth + bulk credits). Handles SIWX authentication, x402 stablecoin micropayments, JWT session management, and supports JSON-RPC, gRPC-Web, REST, and WebSocket protocols.

Installation

npm install @quicknode/x402

Quick Start

Per-Request (Simplest — No Auth)

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

const client = await createQuicknodeX402Client({
  baseUrl: 'https://x402.quicknode.com',
  network: 'eip155:84532', // Base Sepolia (payment network)
  evmPrivateKey: '0xYOUR_PRIVATE_KEY',
  paymentModel: 'pay-per-request',
});

// $0.001 per request — no auth, no credits, no session
const response = await client.fetch('https://x402.quicknode.com/ethereum-mainnet', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'eth_blockNumber', params: [] }),
});

const { result } = await response.json();
console.log('Block:', BigInt(result));

Credit Drawdown (High-Volume with Auth)

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

const client = await createQuicknodeX402Client({
  baseUrl: 'https://x402.quicknode.com',
  network: 'eip155:84532', // Base Sepolia
  evmPrivateKey: '0xYOUR_PRIVATE_KEY',
  preAuth: true, // SIWX auth during init
});

// Auth, payment, and session management handled automatically
const response = await client.fetch('https://x402.quicknode.com/base-sepolia', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'eth_blockNumber', params: [] }),
});

const { result } = await response.json();
console.log('Block:', BigInt(result));
console.log('Credits:', (await fetch('https://x402.quicknode.com/credits', {
  headers: { Authorization: `Bearer ${client.getToken()}` },
}).then(r => r.json())).credits);

Solana (Devnet)

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,
});

const response = 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: [] }),
});

Features

• Two Payment Models — Per-request ($0.001, no auth) or credit drawdown (SIWX auth + bulk credits)
• SIWX Authentication — Automatic Sign-In with X (EVM EIP-191 + Solana Ed25519) on 402 responses (credit drawdown)
• x402 v2 Payments — Automatic stablecoin micropayments when credits are exhausted
• No Billing for Errors — Per-request only settles payment after a successful upstream response
• Session Management — JWT caching, auto-extraction from settlement responses, expiry handling with 30s buffer
• Payment-in-flight Mutex — Prevents concurrent double-payments when multiple requests hit 402 simultaneously
• gRPC-Web Transport — Pre-configured Connect-RPC transport with x402 payment handling (credit drawdown only)
• WebSocket — Authenticated WebSocket connections with JWT query parameter (credit drawdown only)
• Composable Extensions — Standalone helpers for integrating with any x402 setup

API

createQuicknodeX402Client(config): Promise<QuicknodeX402Client>

Async factory that creates a fully-configured client. Async due to SVM key derivation and optional preAuth network call.

Config

Property	Type	Required	Description
baseUrl	string	Yes	Quicknode x402 proxy URL
network	string	Yes	CAIP-2 payment network (e.g., 'eip155:84532', 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1')
evmPrivateKey	`0x${string}`	*	Hex-encoded EVM private key. Creates both payment signer and SIWX signer.
svmPrivateKey	string	*	Base58-encoded Solana secret key (64 bytes). Creates both payment signer and SIWX signer.
evmSigner	ClientEvmSigner		Custom EVM payment signer. Overrides evmPrivateKey for payments.
svmSigner	ClientSvmSigner		Custom SVM payment signer. Overrides svmPrivateKey for payments.
siwxSigner	SIWxSigner		Custom SIWX auth signer. Overrides the signer derived from private key.
paymentModel	string		'pay-per-request' ($0.001/req, no auth) or 'credit-drawdown' (SIWX auth, bulk credits). Default: 'credit-drawdown'.
preAuth	boolean		If true, authenticates via POST /auth during initialization (credit drawdown only). Default: false.
statement	string		SIWX statement. Default: Quicknode ToS acceptance.

* Provide either evmPrivateKey or svmPrivateKey matching the network type. Alternatively, provide signer overrides. Per-request mode requires a payment signer but not a SIWX signer.

Client Methods

Method	Returns	Description
fetch(input, init?)	Promise<Response>	x402-enabled fetch with Bearer auth, SIWX auto-sign, payment, and session extraction
getToken()	string | null	Current cached session JWT
getAccountId()	string | null	CAIP-10 account ID from JWT
isTokenExpired()	boolean	Whether cached JWT is expired (with 30s buffer)
authenticate()	Promise<AuthResult>	Manually authenticate via POST /auth
createGrpcTransport(opts)	Transport	Connect-RPC gRPC-Web transport using x402 fetch
createWebSocket(network)	WebSocket	Authenticated WebSocket with JWT in query param
x402Client	x402Client	Underlying x402 client (for advanced scheme registration)
httpClient	x402HTTPClient	Underlying HTTP client (for advanced hook registration)

gRPC-Web Transport

import { createClient } from '@connectrpc/connect';
import { MyService } from './gen/my_service_pb.js';

const transport = client.createGrpcTransport({
  baseUrl: 'https://x402.quicknode.com/flow-mainnet',
});

const grpcClient = createClient(MyService, transport);
const result = await grpcClient.myMethod({ /* ... */ });

WebSocket

// Requires valid session (preAuth: true or prior x402 payment)
const ws = client.createWebSocket('base-mainnet');

ws.addEventListener('open', () => {
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    method: 'eth_subscribe',
    params: ['newHeads'],
    id: 1,
  }));
});

Composable Extensions

For users integrating with existing x402 setups without using the full factory:

import {
  // SIWX hook for x402HTTPClient
  createSIWxClientHook,
  // Extract quicknode-session JWT from any Response
  extractQuicknodeSession,
  // Wrap fetch with Bearer auth injection
  withBearerAuth,
  // Wrap fetch with session extraction callback
  withSessionExtraction,
  // JWT lifecycle manager
  SessionManager,
  // Signer factories
  createEvmSigners,
  createSvmSigners,
  detectNetworkType,
} from '@quicknode/x402';

Example: Custom x402HTTPClient Setup

import { x402Client, x402HTTPClient } from '@x402/core/client';
import { ExactEvmScheme } from '@x402/evm';
import {
  createSIWxClientHook,
  extractQuicknodeSession,
  createEvmSigners,
} from '@quicknode/x402';

const { paymentSigner, siwxSigner } = createEvmSigners('0xYOUR_KEY');

const client = new x402Client();
client.register('eip155:84532', new ExactEvmScheme(paymentSigner));

const httpClient = new x402HTTPClient(client)
  .onPaymentRequired(createSIWxClientHook(siwxSigner));

// Use httpClient with your own fetch wrapper, extracting sessions as needed

Supported Networks

Payment Networks (CAIP-2)

Network	CAIP-2 ID	Environment
Base Sepolia	eip155:84532	Testnet
Base Mainnet	eip155:8453	Mainnet
Polygon Amoy	eip155:80002	Testnet
Polygon Mainnet	eip155:137	Mainnet
Solana Devnet	solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1	Testnet
XLayer Testnet	eip155:1952	Testnet
XLayer Mainnet	eip155:196	Mainnet
Solana Mainnet	solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp	Mainnet

RPC Networks

140+ blockchain networks supported. See the x402 proxy documentation for the full list.

Types

Key types are re-exported for convenience:

import type {
  QuicknodeX402Config,
  QuicknodeX402Client,
  AuthResult,
  GrpcTransportOptions,
  ClientEvmSigner,
  ClientSvmSigner,
  SIWxSigner,
  EVMSigner,
  SolanaSigner,
} from '@quicknode/x402';

Requirements

• Node.js 18+
• A wallet with USDC or USDG on a supported payment network

License

MIT