Overview

The Quicknode CLI allows users and agents to make RPC calls with stablecoins through x402 or MPP. This payment lane does not require a Quicknode account, API key, login, Tooling Access, or provisioned endpoint.

Starting with CLI 0.6.0, four payment paths are available:

Payment path	Command or flag	Best for
x402 per request	qn rpc call --x402	One-off EVM or Solana payments
MPP per request	qn rpc call --mpp	One-off payments on Tempo
x402 credit drawdown	qn rpc x402 and --x402-drawdown	Prepay once and consume credits over many calls
MPP payment channel	qn rpc mpp and --mpp-session	Deposit once and authorize calls with vouchers

These commands move funds

Use a dedicated, minimally funded wallet and set --max-amount to the most the CLI may spend on a single signed action. Paid calls are attempted once even if --retries is set, because retrying could charge the wallet twice. If the payment outcome is unknown, check the wallet before running the command again.

Install

On macOS, install the CLI with Homebrew:

brew install quicknode/tap/qn
qn --version

See the CLI overview for Windows, Linux, Docker, and source installation options.

Generate a payment wallet

Generate a local EVM wallet for x402 or MPP payments:

qn wallet generate --vm evm --name payer

For x402 payments on Solana, generate an SVM wallet instead:

qn wallet generate --vm svm --name sol-payer

The CLI stores the unencrypted key with 0600 permissions under ~/.config/qn/wallets/. Quicknode does not hold, back up, or recover the wallet. Back up the key file yourself and keep only the funds needed for RPC payments in it.

Manage stored wallets without an API key or login:

qn wallet list
qn wallet show payer
qn wallet rm payer

You can also provide an existing raw key from a file with --payment-key-file <PATH>. The CLI never accepts a private key as a flag value, environment variable, or inline configuration value.

Discover supported networks and assets

List the networks available for paid calls and the payment options accepted by each gateway:

qn rpc x402 supported-networks
qn rpc x402 supported-payments

qn rpc mpp supported-networks
qn rpc mpp supported-payments

Use a network slug from supported-networks as --network. Use the payment network and asset from supported-payments as --payment-network and --payment-asset.

The query network and payment network are independent. For example, a payment on Base Sepolia or Tempo Testnet can pay for an Ethereum Mainnet query.

Pay per request with x402

The following command signs an x402 payment in Base Sepolia USDC and requests an Ethereum Mainnet block:

qn rpc call eth_getBlockByNumber '["latest", false]' \
  --network ethereum-mainnet \
  --x402 \
  --payment-wallet payer \
  --payment-network base-sepolia \
  --payment-asset USDC \
  --max-amount 1000

x402 supports EVM and Solana payment wallets. For Solana, use an SVM wallet and an offered Solana payment network and asset. At sustained volume, pass --svm-rpc-url to avoid public RPC rate limits during payment construction.

Pay per request with MPP

MPP per-request payments use the same EVM wallet key format and settle on Tempo. Add --receipt when you need proof of the settlement alongside the RPC result:

qn rpc call eth_getBlockByNumber '["latest", false]' \
  --network ethereum-mainnet \
  --mpp \
  --receipt \
  --payment-wallet payer \
  --payment-network tempo-testnet \
  --payment-asset pathUSD \
  --max-amount 1000

Without --receipt, the CLI prints only the RPC result, matching an unpaid call. With --receipt, it wraps the output in result and payment_receipt. The receipt contains the payment method, status, timestamp, and settlement transaction hash in reference.

--max-amount is a safety ceiling in the selected asset's integer base units, not the amount the CLI always sends. The CLI rejects a payment offer above the ceiling before signing it.

Use x402 credit drawdown

Credit drawdown authenticates the wallet once, buys prepaid credits, and consumes one credit per successful RPC response.

For Base Sepolia testing, request funds from the faucet. The faucet is limited to one drip per account:

qn rpc x402 drip \
  --payment-wallet payer \
  --payment-network base-sepolia

Buy credits with the funded wallet:

qn rpc x402 buy-credits \
  --network ethereum-mainnet \
  --payment-wallet payer \
  --payment-network base-sepolia \
  --payment-asset USDC \
  --max-amount 10000000

Check the credit balance, then spend credits on RPC calls:

qn rpc x402 balance \
  --payment-wallet payer \
  --payment-network base-sepolia

qn rpc call eth_blockNumber \
  --network ethereum-mainnet \
  --x402-drawdown \
  --payment-wallet payer

The CLI caches the authenticated gateway session with 0600 permissions and refreshes it automatically. Credits are not scoped to the queried network.

Use an MPP payment channel

Open a channel by depositing funds into escrow:

qn rpc mpp open \
  --deposit 1000000 \
  --payment-wallet payer \
  --payment-network tempo-testnet \
  --payment-asset pathUSD \
  --max-amount 1000000

Pay for calls from the channel with cumulative off-chain vouchers:

qn rpc call eth_blockNumber \
  --network ethereum-mainnet \
  --mpp-session \
  --payment-wallet payer \
  --payment-network tempo-testnet \
  --payment-asset pathUSD \
  --max-amount 1000000

Inspect, add funds to, or close the channel:

qn rpc mpp status \
  --payment-wallet payer \
  --payment-network tempo-testnet \
  --payment-asset pathUSD \
  --max-amount 1000000

qn rpc mpp top-up \
  --deposit 500000 \
  --payment-wallet payer \
  --payment-network tempo-testnet \
  --payment-asset pathUSD \
  --max-amount 500000

qn rpc mpp close \
  --payment-wallet payer \
  --payment-network tempo-testnet \
  --payment-asset pathUSD \
  --max-amount 1000000

qn rpc mpp status reads the cached local record. Add --verify to ask the gateway and resynchronize accepted spend; verification consumes one request unit from the channel. Closing settles the channel onchain and refunds the unused deposit.

Save payment defaults

Store the reusable parameters in ~/.config/qn/config.toml:

[rpc.payment]
wallet = "payer"
payment_network = "base-sepolia"
payment_asset = "USDC"
max_amount = "10000"

Configuration supplies the payment values but never activates payments by itself. Select a payment path on each call:

qn rpc call eth_blockNumber --network ethereum-mainnet --x402

Next steps

• Review x402 Payments for supported payment networks, assets, and gateway behavior.
• Review MPP Payments for charge and session payment details.
• Run qn rpc x402 --help, qn rpc mpp --help, or qn wallet --help for the complete command reference.