@quicknode/x402

Multi-chain payment client for Quicknode's x402 RPC proxy. Handles SIWX authentication, x402 USDC micropayments, JWT session management, and supports JSON-RPC, gRPC-Web, REST, and WebSocket protocols.

Installation

npm install @quicknode/x402

Quick Start

EVM (Base Sepolia)

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

// Make paid RPC calls — 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

• SIWX Authentication — Automatic Sign-In with X (EVM EIP-191 + Solana Ed25519) on 402 responses
• x402 v2 Payments — Automatic USDC micropayments when credits are exhausted
• 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
• WebSocket — Authenticated WebSocket connections with JWT query parameter
• 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. | | preAuth | boolean | | If true, authenticates via POST /auth during initialization. Default: false. | | statement | string | | SIWX statement. Default: Quicknode ToS acceptance. |

* Provide either evmPrivateKey or svmPrivateKey matching the network type. Alternatively, provide signer overrides.

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 | | 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 on a supported payment network

License

MIT