8 min read
Overview
@quicknode/x402-solana is an npm library that creates Solana RPC and WebSocket subscription clients using @solana/kit, paying for each request with USDC via the x402 payment protocol through Quicknode. It requires no API key, no account, and no subscription, only a Solana wallet file with USDC.
The library exports a single function, createSolanaX402Clients(), which returns standard Solana Kit rpc and rpcSubscriptions objects.
- What you'll build: Authenticated Solana RPC and WebSocket clients using
@quicknode/x402-solanawith no API key or account - What you'll learn: How to install, configure, and use wallet-based x402 payment for Solana RPC access through Quicknode
- End result: Working RPC clients that pay per request with USDC via the x402 protocol
What You Will Learn
This guide covers installing and configuring the library, choosing between the credit-drawdown and pay-per-request payment models, using devnet USDC to pay for mainnet RPC access during development, and understanding how the x402 protocol integrates with Solana Kit under the hood. By the end, you will have working RPC clients that pay automatically with USDC.
What You Will Need
- A basic understanding of x402 Payments
- A Solana keypair JSON file in the standard format produced by
solana-keygen new, typically at~/.config/solana/id.json(a JSON array of 64 numbers representing the private key bytes) - USDC in the wallet with at least $10 USDC on mainnet for
credit-drawdownmode, or from $0.01 on devnet. Forpay-per-requestmode, any amount works. - No Quicknode RPC account required. No signup, no API key, no subscription.
Dependencies Used in This Guide
| Dependency | Version |
|---|---|
| Node.js | 22+ |
| @quicknode/x402-solana | 0.1.0 |
| @solana/kit | 6.6.0 |
| @quicknode/x402 | 0.1.2 |
If you don't have a Solana keypair file, create one with the Solana CLI:
solana-keygen new
This creates a keypair at ~/.config/solana/id.json. If you plan to use devnet for payment, you will need devnet USDC. You can get some from the Circle Faucet.
Install and Use @quicknode/x402-solana
Install the package and create authenticated Solana clients in three lines of code.
npm install @quicknode/x402-solana
- Solana Kit
- Kite
// Solana Kit
import { createSolanaX402Clients } from "@quicknode/x402-solana";
import { address } from "@solana/kit";
import { homedir } from "node:os";
const keyPairFile = `${homedir()}/.config/solana/id.json`;
const { rpc, rpcSubscriptions } = await createSolanaX402Clients(
"mainnet",
keyPairFile,
);
// Make an RPC call to test the connection
const balance = await rpc
.getBalance(address("dDCQNnDmNbFVi8cQhKAgXhyhXeJ625tvwsunRyRc7c8"))
.send();
console.log("Balance:", balance.value);
Kite wraps Solana Kit with a simpler API:
// Kite
import { createSolanaX402Clients } from "@quicknode/x402-solana";
import { connect, loadWalletFromFile } from "solana-kite";
import { homedir } from "node:os";
const keyPairFile = `${homedir()}/.config/solana/id.json`;
const { rpc, rpcSubscriptions } = await createSolanaX402Clients(
"mainnet",
keyPairFile,
);
const connection = connect(rpc, rpcSubscriptions);
const wallet = await loadWalletFromFile(keyPairFile);
const balance = await connection.getBalance(wallet.address);
console.log("Balance:", balance);
Why Use @quicknode/x402-solana Instead of a Traditional RPC Provider?
Traditional Solana RPC providers require account creation, API key management, and subscription plans. @quicknode/x402-solana replaces all of that with a Solana wallet.
Here is a side-by-side comparison of the two approaches:
| @quicknode/x402-solana | Quicknode Platform | |
|---|---|---|
| Account setup | None — wallet only | Required (email, signup, verification) |
| API key management | None | Create, store, rotate, and secure keys |
| Billing | Pay-per-use with USDC | Subscription plan or prepaid credits |
| Rate limits | 1,000 req / 10s per network | Tier-based |
| CI/CD credentials | Wallet keypair only | Secrets management required |
| AI agent compatible | Yes (wallet native) | Partial (Using Quicknode MCP) |
| Auth model | Onchain USDC payment | API key in header |
| Products suite | API only (no Streams, Webhooks, etc.) | Full access (Streams, Webhooks, and more) |
| Best for | Agents, serverless, prototyping, CI | Production systems at scale, teams with existing accounts |
The library uses the x402 protocol, an open standard where servers respond with HTTP 402 Payment Required and payment instructions. The x402-enabled client automatically fulfills the payment with USDC and completes the request, all in a single round trip.
This is particularly useful for AI agents. Autonomous agents cannot sign up for accounts, manage subscriptions, or rotate API keys. They can, however, hold a wallet with USDC, making wallet-based authentication a natural fit for agent-driven blockchain access.
@quicknode/x402-solana API Reference
@quicknode/x402-solana exports a single async function:
const { rpc, rpcSubscriptions } = await createSolanaX402Clients(
network,
keyPairFile,
options?,
);
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
network | "mainnet" | "testnet" | "devnet" | Yes | - | Solana network to connect to |
keyPairFile | string | Yes | - | Path to a Solana keypair JSON file |
options.paymentNetwork | "mainnet" | "testnet" | "devnet" | No | Same as network | Network used for USDC payments |
options.paymentModel | "credit-drawdown" | "pay-per-request" | No | "credit-drawdown" | Payment model to use |
Return Value:
Returns { rpc, rpcSubscriptions }, which are standard @solana/kit Rpc and RpcSubscriptions objects that can be used with any Solana Kit or Kite API.
Choose a Payment Model
@quicknode/x402-solana supports two payment models: credit-drawdown (default) authenticates once and purchases credits in bulk, while pay-per-request pays individually for each RPC call.
| Aspect | credit-drawdown (default) | pay-per-request |
|---|---|---|
| Authentication | SIWX (Sign-In With X) one-time auth | None, payment attached to each request |
| Minimum balance | $10 USDC on mainnet, $0.01 on devnet | No minimum |
| Session management | Automatic JWT with auto-reauthentication | None |
| Upfront cost | Credit bundle purchase | None |
| Best for | Sustained usage, high-volume apps | Low-volume, sporadic, serverless |
Credit Drawdown Example
import { createSolanaX402Clients } from "@quicknode/x402-solana";
import { homedir } from "node:os";
const keyPairFile = `${homedir()}/.config/solana/id.json`;
// credit-drawdown is the default, no options needed
const { rpc, rpcSubscriptions } = await createSolanaX402Clients(
"mainnet",
keyPairFile,
);
Pay-Per-Request Example
import { createSolanaX402Clients } from "@quicknode/x402-solana";
import { homedir } from "node:os";
const keyPairFile = `${homedir()}/.config/solana/id.json`;
const { rpc, rpcSubscriptions } = await createSolanaX402Clients(
"mainnet",
keyPairFile,
{ paymentModel: "pay-per-request" },
);
Use credit-drawdown (the default) for most applications. Use pay-per-request when you need zero upfront commitment, are running in short-lived serverless functions, or are making fewer than around 50 requests per session.
Pay with Devnet USDC for Mainnet Solana RPC Access
You can pay for mainnet or testnet RPC access using devnet USDC by setting paymentNetwork: "devnet" in the options. This is useful for development and testing against real mainnet data without spending real money.
Configuration Combinations
| Configuration | network | paymentNetwork | Minimum USDC | Use case |
|---|---|---|---|---|
| Mainnet RPC, mainnet payment | "mainnet" | "mainnet" (default) | $10 | Production |
| Mainnet RPC, devnet payment | "mainnet" | "devnet" | $0.01 | Development against real mainnet data |
| Devnet RPC, devnet payment | "devnet" | "devnet" (default) | $0.01 | Full development/testing |
| Testnet RPC, devnet payment | "testnet" | "devnet" | $0.01 | Testnet development |
| Any network + pay-per-request | any | any | None | Low-volume or sporadic usage |
Cross-Network Payment Example
import { createSolanaX402Clients } from "@quicknode/x402-solana";
import { homedir } from "node:os";
const keyPairFile = `${homedir()}/.config/solana/id.json`;
// Connect to mainnet RPC, pay with devnet USDC
const { rpc, rpcSubscriptions } = await createSolanaX402Clients(
"mainnet",
keyPairFile,
{ paymentNetwork: "devnet" },
);
x402 Protocol and Solana Kit Integration
Under the hood, the library builds a standard Kit RpcTransport that speaks the x402 protocol. When a request hits an endpoint that requires payment, the server responds with HTTP 402 and a machine-readable payment requirement. The transport intercepts that response, fulfills the payment with USDC from your wallet, and retries the original request.
At initialization, the library reads your Solana keypair file and converts the private key to base58 format so it can sign payment transactions. It then creates an x402-authenticated HTTP client via @quicknode/x402 and wraps it as the Solana Kit transport layer.
In credit-drawdown mode, this includes a one-time SIWX (Sign-In With X) authentication step that purchases a USDC credit bundle upfront. Individual RPC calls don't each incur a separate on-chain transaction. If the bundle runs out mid-session, the library detects the lifetime_limit_reached error, reauthenticates, purchases a new bundle, and retries the request automatically.
In pay-per-request mode, there is no session or upfront purchase. Each call is settled individually.
@quicknode/x402-solana Compatibility
The clients returned by createSolanaX402Clients() are standard @solana/kit v6+ objects, compatible with any library or tool that accepts Solana Kit clients.
| Library / Tool | Compatible | Notes |
|---|---|---|
| Solana Kit (v6+) | Yes | Returns native Kit Rpc and RpcSubscriptions types |
| Kite | Yes | Pass rpc and rpcSubscriptions to connect() |
| web3.js (legacy) | No | Different API; requires @solana/kit v6+ |
| Browser environments | No | Uses Node.js fs to read keypair files |
When to Use @quicknode/x402-solana
Below are some real-world use cases where wallet-based RPC access unlocks new opportunities that traditional API key models don't support.
AI Agents That Need Autonomous Blockchain Access
AI agents can use @quicknode/x402-solana to access Solana RPC autonomously without human-provisioned API keys, requiring only a wallet with USDC. Since agents cannot sign up for accounts or manage subscriptions, wallet-based authentication through x402 is a natural fit for agent-driven blockchain interactions.
Serverless Functions and Ephemeral Environments
Serverless functions, Lambda, and containers can get Solana RPC access without pre-provisioning accounts, using only a keypair file. The pay-per-request model is ideal here with no session to manage, no upfront credit bundle, and costs scale to zero when the function is idle.
CI/CD and Integration Testing
CI pipelines can access live Solana RPC by storing a keypair as a repository secret (SOLANA_KEYPAIR), without managing separate RPC provider credentials. The library's own test suite uses this pattern.
Prototyping and Hackathons
You can get a working Solana RPC connection in under a minute: npm install @quicknode/x402-solana, point at a keypair file, and start making RPC calls.
CLI Tools and Developer Utilities
Build Solana CLI tools that work for anyone with a standard Solana keypair file (~/.config/solana/id.json), with zero configuration beyond what Solana developers already have.
Low-Volume Monitoring and Analytics
Use pay-per-request mode for scripts that periodically check on-chain state (balances, token accounts, program data). Costs stay proportional to actual usage with no minimum commitment.
When NOT to Use @quicknode/x402-solana
This library is not the right choice for every Solana application. In some cases, a traditional RPC provider with a dedicated endpoint and API key is a better fit. Some examples are:
- High-throughput, cost-sensitive production systems. If you are making millions of RPC calls per day and need the lowest possible per-call cost, a dedicated RPC endpoint with a negotiated plan will be cheaper.
- Applications that already have Quicknode accounts. If you already have a Quicknode subscription with API keys, use those directly. This library solves the "no account" problem.
- Browser or client-side applications. The library reads a keypair file from disk using Node.js
fs, so it only runs in Node.js server-side environments. It cannot run in browsers. - Applications needing custom RPC transport configuration. The library does not expose transport-level options like custom headers, timeouts, or retry policies beyond the built-in auto-reauthentication.
Test @quicknode/x402-solana in CI/CD
Store your Solana keypair JSON as a SOLANA_KEYPAIR repository secret and the test suite will detect it automatically.
- name: Run tests
env:
SOLANA_KEYPAIR: ${{ secrets.SOLANA_KEYPAIR }}
run: npm test
Locally, tests auto-detect ~/.config/solana/id.json and skip gracefully if the file is absent. In CI, the SOLANA_KEYPAIR environment variable is written to a temporary file and cleaned up after the test run. All tests are integration tests against live RPC endpoints, nothing is mocked.
Troubleshooting
Error: "lifetime_limit_reached"
This means your credit bundle is exhausted. In credit-drawdown mode, the library handles this automatically by reauthenticating and purchasing a new bundle. If this error propagates to your application, ensure your wallet has sufficient USDC ($10 minimum on mainnet, $0.01 on devnet).
Error Reading Keypair File
Ensure the keyPairFile path points to a valid Solana keypair JSON file, a JSON array of 64 numbers (bytes). The standard location is ~/.config/solana/id.json. Generate one with solana-keygen new if needed.
Insufficient USDC Balance
The credit-drawdown model requires at least $10 USDC on mainnet or $0.01 on devnet. The pay-per-request model has no minimum but requires enough USDC for each individual call.
WebSocket Subscriptions Not Connecting
WebSocket authentication uses a JWT token appended as a query parameter. This token comes from the SIWX authentication flow in credit-drawdown mode. If using pay-per-request, WebSocket connections may not have a valid token. Use credit-drawdown for applications that need WebSocket subscriptions.
Frequently Asked Questions
Do I need a Quicknode account or API key to use @quicknode/x402-solana?
No. @quicknode/x402-solana requires no Quicknode account, no API key, and no subscription. You only need a Solana wallet file with USDC. Payments are handled automatically via the x402 protocol.
How much does @quicknode/x402-solana cost?
Costs depend on the payment model. With credit-drawdown (the default), you purchase a credit bundle with a minimum of $10 USDC on mainnet or from $0.01 on devnet. With pay-per-request, each RPC call is paid individually with no minimum.
Can I use devnet USDC to pay for mainnet Solana RPC access?
Yes. Set paymentNetwork: "devnet" in the options to pay with devnet USDC while connecting to mainnet or testnet RPC endpoints. This is useful for development and testing against real mainnet data without spending real money.
What happens when my credits run out?
In credit-drawdown mode, the library automatically detects a lifetime_limit_reached error, reauthenticates, purchases a new credit bundle, and retries the request. No manual intervention is needed as long as the wallet has sufficient USDC.
What is the x402 protocol?
x402 is an open payment protocol based on the HTTP 402 Payment Required status code. When a server requires payment, it responds with a 402 status and payment instructions. An x402-enabled client automatically fulfills the payment (in this case, with USDC on Solana) and retries the request.
Wrapping Up
You now have everything you need to access Solana RPC through Quicknode without an account, API key, or subscription. With @quicknode/x402-solana, you can connect to any Solana network using only a wallet with USDC, choose between credit-drawdown and pay-per-request models based on your use case, and even pay with devnet USDC during development. Whether you are building AI agents, serverless functions, CLI tools, or rapid prototypes, wallet-based RPC access through the x402 protocol removes the friction of traditional provider onboarding.
Resources
- How to Access Quicknode Endpoints with x402 Payments for per-call pricing and additional x402 details
- x402 protocol specification
- Quicknode MCP
- Solana Kit GitHub
- Solana Kite
We ❤️ Feedback!
Let us know if you have any feedback or requests for new topics. We'd love to hear from you.