--- title: x402 Payments description: Access Quicknode's blockchain infrastructure with wallet-authenticated, pay-per-request stablecoin payments using the x402 protocol. No account or API keys required. tags: [] --- ## Overview > For the complete documentation index, see [llms.txt](/docs/llms.txt) 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](https://x402.org/) 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](https://developers.circle.com/gateway/nanopayments). 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](https://www.quicknode.com/docs/platform/supported-chains-node-types#supported-chains--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. TL;DR - 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](/docs/build-with-ai/agent-subscriptions) 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 info x402 on Quicknode is currently in alpha. ```bash # 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. ```bash npm install @quicknode/x402 ``` **Pay-per-request** ### Pay-per-request **Pay-per-request** requires no authentication or session state. Each request includes a payment signature handled automatically by the client. ```typescript 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 **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. ```typescript 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 **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](https://developers.circle.com/gateway/references/supported-blockchains#required-block-confirmations) for confirmation times per chain. ```typescript 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? Use [`@quicknode/x402-solana`](https://github.com/quiknode-labs/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](https://www.quicknode.com/guides/solana-development/ai-agents/how-to-access-solana-rpc-with-x402-solana) guide for a full walkthrough. ```bash npm install @quicknode/x402-solana ``` See the [examples repo](https://github.com/quiknode-labs/qn-x402-examples) 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 | Yes | Yes | Yes | | REST | Yes | Yes | Yes | | gRPC-Web | No | Yes | No | | WebSocket | No | Yes | No | ## Pricing x402 on Quicknode supports three billing patterns: | | Pay-per-request | Credit Drawdown | Nanopayment | | --- | --- | --- | --- | | Cost | $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) | | Authentication | None | SIWX + JWT | None (Circle Gateway Wallet deposit required) | | Free Tier | Shared 1M API credits / month bucket | Shared 1M API credits / month bucket | Shared 1M API credits / month bucket | | Best for | 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 | | --- | --- | --- | --- | --- | | Base Sepolia | USDC | Yes | Yes | Yes | | Base Mainnet | USDC | Yes | Yes | No | | Polygon Amoy | USDC | Yes | Yes | Yes | | Polygon Mainnet | USDC | Yes | Yes | No | | XLayer Testnet | USDG | Yes | Yes | No | | XLayer Mainnet | USDG | Yes | Yes | No | | Arc Testnet | USDC | No | No | Yes | | Solana Devnet | USDC | Yes | Yes | No | | Solana Mainnet | USDC | Yes | Yes | No | To get testnet tokens: - **Base Sepolia / Polygon Amoy / Arc Testnet:** Use the [Circle faucet](https://faucet.circle.com/) 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](https://faucet.circle.com/). ## Authentication 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: - `domain` (`x402.quicknode.com`) - `address` (your wallet address) - `uri` (`https://x402.quicknode.com`) - `version` (`1`) - `chainId` (the chain ID of the network you pay on) - `nonce` (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 ` 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. The `@quicknode/x402` client handles the full payment flow automatically. Under the hood, the credit drawdown flow follows this sequence: 1. **Authenticate.** Sign a message with your wallet (SIWE for EVM, SIWX for Solana) and exchange it for a JWT token at the `/auth` endpoint. 2. **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. 3. **Pay when prompted.** When credits run out, the server returns HTTP 402. The client automatically signs a stablecoin payment and retries the request. 4. **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 | | --- | --- | --- | | Authentication | None (SIWX + JWT only for credit drawdown) | API key | | Billing | Per request (or credit bundle for drawdown) | [Monthly/Yearly subscription](https://www.quicknode.com/pricing) | | Setup required | Wallet + stablecoin | Account + API key | | Status | Alpha | Production SLA | | Best for | Agents, prototyping, permissionless access | Teams, production workloads | ## Resources [ Getting Started Guide Step-by-step walkthrough for x402 on Quicknode →](https://www.quicknode.com/guides/x402/access-quicknode-endpoints-with-x402-payments)[ Video Walkthrough How to get started with x402 on Quicknode →](https://www.youtube.com/watch?v=hDBiXRUme9M)[ Protocol Explainer Deep dive on how x402 works →](https://blog.quicknode.com/x402-protocol-explained-inside-the-https-native-payment-layer/)[ Example Implementations End-to-end demonstrations of the x402 payment protocol →](https://github.com/quiknode-labs/qn-x402-examples)[ Sample App Explore x402 payments through a simple UI →](https://www.quicknode.com/sample-app-library/x402-explorer)[ Protocol Specification Open-source x402 protocol by Coinbase →](https://github.com/coinbase/x402) tip For an alternative payment protocol, see [MPP Payments](/docs/build-with-ai/mpp-payments). For managing Quicknode infrastructure through natural language, see [Quicknode MCP](/docs/build-with-ai/quicknode-mcp). For giving AI coding agents accurate Quicknode API knowledge, see [Blockchain Skills](/docs/build-with-ai/quicknode-skills). ## We ❤️ Feedback! If you have any feedback or questions about this documentation, [let us know](https://airtable.com/shrfIppvMmbdWxHgC). We'd love to hear from you!