12 min read

Overview

The Quicknode CLI (qn) lets you manage Quicknode infrastructure from the terminal. Instead of clicking through the dashboard, you can run the same commands locally, in CI, or from coding agents.

In this guide, you'll install the CLI, make live RPC calls through Tooling Access or with supported stablecoin payments, build a deployment preflight that validates a specific Base endpoint, run it in GitHub Actions, and generate CLI context for coding agents.

TL;DR

• Use qn to turn an infrastructure check into a command your team can repeat.
• Use x402 or MPP with supported stablecoins when you want RPC access without an account or API key.
• Validate the exact Base endpoint your application depends on, not any active endpoint in the account.
• Run the same preflight locally and in GitHub Actions with explicit credentials and structured output.
• Give coding agents qn agent context, a read-only starting scope, and an approval boundary for mutations.

What you will do

• Confirm your Quicknode API key and Tooling Access configuration
• Make live RPC calls before creating an application project
• Pay for RPC calls with supported stablecoins through x402 or an MPP payment channel
• Build an endpoint-specific deployment preflight
• Run the preflight in GitHub Actions without exposing credentials
• Give coding agents machine-readable CLI instructions and bounded access

What you will need

• A Quicknode account and an API key from the API Keys page for the Tooling Access and deployment preflight sections; the paid RPC example does not require either
• A terminal on macOS or Linux, or Bash through WSL or Git Bash on Windows
• jq for the local and CI preflight examples
• (Optional) A GitHub repository and GitHub Actions
• (Optional) Codex, Claude Code, or another coding agent

Install qn and confirm your account

Install the CLI with the package manager that fits your system:

Recommended for macOS. Homebrew also works on Linux.

brew install quicknode/tap/qn

Confirm that the binary is available, then authenticate with an API key:

qn --version
qn auth login
qn auth whoami

qn auth whoami validates the resolved key against Quicknode and returns redacted account details. A successful result proves the key is usable, not merely present on disk.

For more installation options and the full command reference, see the Quicknode CLI documentation.

Use explicit credentials in automation

The CLI resolves credentials from --api-key, then --config-file, then its local config file. It does not automatically read an API key from an environment variable. In CI, read a secret into the shell and pass it to qn through --api-key or a temporary config file. Do not commit an API key or config file to your repository.

Check live chain access before building an integration

Tooling Access lets qn send read-only RPC requests without a dedicated endpoint. Use it to test an idea before you create a project.

Make a live request to Base:

qn rpc call eth_blockNumber --network base-mainnet

"0x..."

If Tooling Access is not enabled, the CLI asks you to enable it.

The result is the latest block number in hexadecimal. Change the method and --network to run the same workflow against another supported network. For example, this asks Solana for its current slot:

qn rpc call getSlot --network solana-mainnet

Run qn rpc list-networks when you need the available network keys.

Tooling Access is not application infrastructure

Tooling Access supports CLI and agent workflows. Use a dedicated endpoint for production application traffic that needs its own security controls, rate limits, add-ons, or traffic isolation.

Pay for RPC calls with supported stablecoins

The paid RPC lane is an alternative way to query supported networks without a Quicknode account, API key, or subscription. The CLI signs payments with a local wallet and a supported stablecoin through x402 or MPP. The network you pay on is independent of the network you query.

Make a no-signup RPC call with testnet USDC

This example uses USDC on Base Sepolia. Generate an EVM payment wallet. qn wallet stores payment wallets locally for --x402 and --mpp commands:

qn wallet generate --vm evm --name payer

Request testnet USDC from the Base Sepolia faucet:

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

Use that testnet USDC to pay for an Ethereum mainnet RPC call:

qn rpc call eth_blockNumber --network ethereum-mainnet --x402 \
  --payment-wallet payer --payment-network base-sepolia \
  --payment-asset USDC --max-amount 10000

--network selects the chain you query, while --payment-network selects the chain where you pay. --max-amount is a spend ceiling in the asset's integer base units; for USDC, 10000 is 0.01 USDC. The CLI does not sign an offered payment above this ceiling.

Check the available query networks and payment options instead of hardcoding them:

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

Choose a payment model

Use the payment model that fits how often you make requests:

Model	Setup	RPC flag	Repeated-call behavior
x402 pay per request	Fund or drip a payment wallet	--x402	Signs and settles each request
x402 prepaid credits	qn rpc x402 buy-credits	--x402-drawdown	Consumes credits without per-call signing
MPP payment channel	qn rpc mpp open	--mpp-session	Signs vouchers without an on-chain transaction

For repeated x402 calls, buy prepaid credits once and draw them down on any supported query network. The CLI authenticates the session and refreshes it automatically:

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

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

For MPP, open a Tempo payment channel once. Subsequent calls update a cumulative payment voucher instead of submitting an on-chain transaction for every request:

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

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

Run qn rpc mpp supported-networks and qn rpc mpp supported-payments to discover the current MPP options.

Protect payment wallets

Use a dedicated, minimally funded wallet for paid RPC calls. The locally stored private key is the only copy, and deleting the wallet with qn wallet rm cannot be undone. Never commit payment keys or the CLI wallet directory to a repository.

Build an endpoint-specific deployment preflight

Application code can be ready while its deployment dependency is not. A revoked API key, paused endpoint, wrong network, or unreachable RPC URL can turn a routine release into a rollback.

An endpoint-specific preflight converts those assumptions into a fast pass-or-fail check. Run it before a release to verify that the exact endpoint your application depends on is active and serving RPC requests. Teammates, CI, and coding agents can run the same diagnostic without opening the dashboard or interpreting a manual checklist.

Tooling Access confirms that your account can make a chain request. This preflight goes further by checking the endpoint your application actually uses.

Run qn endpoint list and copy the ID of an active Base mainnet endpoint:

qn endpoint list

Create scripts/check-quicknode.sh. The script validates four things in order: the API key works, the selected endpoint exists, that endpoint is active on Base mainnet, and a live RPC request succeeds through its HTTP URL.

scripts/check-quicknode.sh

#!/usr/bin/env bash
set -euo pipefail

: "${QUICKNODE_API_KEY:?Set QUICKNODE_API_KEY from your secret manager}"
: "${QUICKNODE_ENDPOINT_ID:?Set QUICKNODE_ENDPOINT_ID to a Base mainnet endpoint ID}"

umask 077
CONFIG_FILE="$(mktemp)"
trap 'rm -f "$CONFIG_FILE"' EXIT

printf '[api]\nkey = "%s"\n' "$QUICKNODE_API_KEY" > "$CONFIG_FILE"

QN=(qn --config-file "$CONFIG_FILE" --format json)

account="$("${QN[@]}" auth whoami)"
jq -e '.validated == true' <<< "$account" > /dev/null

endpoint="$("${QN[@]}" endpoint show "$QUICKNODE_ENDPOINT_ID")"

if ! jq -e '.status == "active"' <<< "$endpoint" > /dev/null; then
  echo "Quicknode endpoint $QUICKNODE_ENDPOINT_ID is not active." >&2
  exit 1
fi

if ! jq -e '.chain == "base" and .network == "mainnet"' <<< "$endpoint" > /dev/null; then
  echo "Quicknode endpoint $QUICKNODE_ENDPOINT_ID is not a Base mainnet endpoint." >&2
  exit 1
fi

endpoint_url="$(
  jq -er '.http_url | select(type == "string" and length > 0)' <<< "$endpoint"
)"

rpc_result="$(
  "${QN[@]}" rpc call eth_blockNumber --endpoint-url "$endpoint_url"
)"
block_number="$(
  jq -er 'select(type == "string" and startswith("0x"))' <<< "$rpc_result"
)"

jq -n \
  --arg endpoint_id "$QUICKNODE_ENDPOINT_ID" \
  --arg network "base-mainnet" \
  --arg block_number "$block_number" \
  '{
    status: "ok",
    endpoint_id: $endpoint_id,
    network: $network,
    latest_block: $block_number
  }'

Make the script executable. Prompt for the API key so it does not appear in shell history, then run the preflight against the endpoint ID:

chmod +x scripts/check-quicknode.sh

read -rsp "Quicknode API key: " QUICKNODE_API_KEY && echo
export QUICKNODE_API_KEY
QUICKNODE_ENDPOINT_ID="<BASE_ENDPOINT_ID>" ./scripts/check-quicknode.sh
unset QUICKNODE_API_KEY

{
	"status": "ok",
	"endpoint_id": "<BASE_ENDPOINT_ID>",
	"network": "base-mainnet",
	"latest_block": "0x..."
}

The script never prints the self-authenticating endpoint URL. umask 077 restricts the temporary config file to the current user, and the exit trap removes it. The script also avoids account mutations: an unattended check should report a missing prerequisite instead of changing infrastructure.

Run the preflight in GitHub Actions

A local preflight still depends on someone remembering to run it. GitHub Actions moves the check into the review path. Every trusted pull request gets the same result before merge, and a failure identifies whether credentials, endpoint state, or RPC connectivity caused the problem.

Add the following workflow after committing scripts/check-quicknode.sh. It pins the CLI release, limits the workflow token to read access, passes credentials only to the preflight step, and runs for manual dispatches or pull requests from the same repository.

Create .github/workflows/quicknode-preflight.yml:

.github/workflows/quicknode-preflight.yml

name: Quicknode preflight

on:
  pull_request:
  workflow_dispatch:

permissions:
  contents: read

env:
  QN_VERSION: v0.5.0

jobs:
  quicknode-preflight:
    if: >-
      github.event_name == 'workflow_dispatch' ||
      github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    steps:
      - name: Check out the repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Install the Quicknode CLI
        run: |
          curl -fL -o qn_amd64.deb \
            "https://github.com/quicknode/cli/releases/download/${QN_VERSION}/qn_amd64.deb"
          sudo apt install ./qn_amd64.deb
          qn --version

      - name: Verify Quicknode infrastructure
        env:
          QUICKNODE_API_KEY: ${{ secrets.QUICKNODE_API_KEY }}
          QUICKNODE_ENDPOINT_ID: ${{ vars.QUICKNODE_ENDPOINT_ID }}
        run: ./scripts/check-quicknode.sh

Add QUICKNODE_API_KEY as a repository or environment secret. Add QUICKNODE_ENDPOINT_ID as a repository variable. Use a Viewer API key for routine read-only checks; use an Admin key only for commands that require account changes.

GitHub does not pass repository secrets to workflows triggered from forks. The job-level condition skips those pull requests instead of running with an empty credential. If you need to validate an external contribution, review it first, then run the preflight with workflow_dispatch from a trusted branch. See Using secrets in GitHub Actions for secret behavior and configuration.

Pinning QN_VERSION keeps CI reproducible. Update it intentionally after reviewing a new Quicknode CLI release.

Keep CI mutations intentional

Read-only commands can retry transient network failures. Commands that create, update, pause, archive, or delete resources do not automatically retry because repeating them could apply a change twice. Before adding a mutation to CI, inspect the current resource, use an approval boundary, and verify the result after the command completes.

Pair qn with the Build Web3 plugin

The Build Web3 plugin gives coding agents two Quicknode tools. The build-web3 skill helps an agent plan and build a Web3 app. The optional Quicknode MCP lets supported clients manage Quicknode resources through tool calls.

The plugin and qn work best together. The build-web3 skill helps the agent translate an application idea into the Quicknode resources and integration code it needs. The agent can choose the right building block, generate the project, inspect live account and chain state, create approved resources, verify them, and connect their IDs and settings to the application.

Use qn when the agent needs terminal commands for that workflow. qn agent context provides current command behavior, credential rules, structured output, confirmation boundaries, and retry behavior. The agent works from explicit infrastructure context instead of guessing which resource, command, or flag it needs.

Generate the self-contained agent guide in your project:

mkdir -p .ai
qn agent context > .ai/quicknode-cli.md

qn agent context makes no network request and does not require authentication. It tells the agent which commands are read-only, which commands need confirmation, and how qn returns data.

When an agent needs a compact result, use the toon output format:

qn tooling-access status -o toon

Use a short prompt that states the result and approval boundary:

Read .ai/quicknode-cli.md for qn details.
Use qn and the Build Web3 plugin to build a small TypeScript Base wallet alert app.
Ask for approval before you create or change any Quicknode resource.

Install the Build Web3 plugin for your agent client by following its installation instructions.

Start agent access with read-only commands

Point agents to development resources first. Allow commands such as qn endpoint list, qn webhook list, qn stream test-filter, qn sql query, qn usage summary, and qn rpc call. Require explicit approval before a create, update, pause, archive, or delete command, especially if it includes --yes.

Read-only does not mean zero-cost. RPC calls, SQL queries, and other data operations can consume API credits. Never paste an API key into a prompt or commit it to the repository.

Extend the workflow with other qn commands

The preflight is the main artifact in this guide. Use the following commands when you need to investigate or validate another part of your Quicknode setup:

Goal	Command or workflow
Read current chain state	qn rpc call through Tooling Access
Explore indexed Hyperliquid data	qn sql query and qn sql schema
Verify a simple event alert	qn webhook create, show, and pause
Test filtering, backfills, or batching	qn stream test-filter
Investigate a running endpoint	qn endpoint logs, metrics, and usage summary

Explore indexed Hyperliquid data

Use RPC for current chain state. Use SQL Explorer when you need historical or indexed Hyperliquid data:

qn sql query "SELECT * FROM hyperliquid_trades LIMIT 10" \
  --cluster-id hyperliquid-core-mainnet \
  --format json

qn sql schema hyperliquid-core-mainnet

For production queries, filter by time, market, address, contract, or another relevant value instead of scanning more data than you need.

Validate Webhook and Stream logic

Start with a Webhook when you need a simple event alert sent to one HTTP endpoint. Capture its ID, inspect the created resource, and pause or delete it after the test:

WEBHOOK_ID="$(
  qn --format json webhook create \
    --name "base-wallet-alerts" \
    --network base-mainnet \
    --url https://your-server.example/webhooks/quicknode \
    --compression none \
    --template evm-wallet \
    --wallet 0x0000000000000000000000000000000000000000 \
  | jq -r '.id'
)"

qn webhook show "$WEBHOOK_ID"

# After testing:
qn webhook pause "$WEBHOOK_ID"
# Or remove the test resource:
# qn webhook delete "$WEBHOOK_ID"

Run this workflow only after your HTTP endpoint can receive requests. Before production, implement HMAC verification so the receiver can validate incoming messages.

Use a Stream when you need batching, backfills, advanced filtering, data transformations, or a non-HTTP destination. Test a filter against a past block before you create or update a Stream:

filters/events.js

function main(stream) {
	const block = stream.data[0]

	return {
		blockNumber: block.number,
		timestamp: block.timestamp,
	}
}

qn stream test-filter \
  --network ethereum-mainnet \
  --dataset block \
  --block 17811625 \
  --filter-file filters/events.js \
  --filter-language javascript \
  --format json

Return null when you do not want Streams to send data to the destination. Filters reduce bandwidth, storage, and downstream processing, but they do not reduce block-based API credit usage. See Streams billing before a large backfill.

Inspect infrastructure as data

Use structured output when a script needs to evaluate endpoint state:

qn endpoint list --format json | jq '.data[] | {
  id: .id,
  label: .label,
  status: .status,
  chain: .chain,
  network: .network
}'

The same pattern works for operational checks:

qn endpoint metrics <ENDPOINT_ID> \
  --metric response_status_breakdown \
  --period day

qn webhook enabled-count
qn stream enabled-count
qn usage summary --from 7d

Treat endpoint output as sensitive

Endpoint output can include self-authenticating endpoint URLs. Project only the fields you need before saving command output to a file, issue, pull request, or CI artifact.

Final thoughts

You now have one endpoint-specific preflight that works locally, in GitHub Actions, and as a bounded task for a coding agent. It verifies the Quicknode credential, inspects the Base endpoint your application uses, and makes a live RPC request without printing the endpoint URL.

The supporting qn commands extend the same pattern to Hyperliquid SQL Explorer, Webhooks, Streams, metrics, and usage. Start with a read, inspect the result, and add approval before any command changes infrastructure.

Next steps

• Replace the Base RPC method with a read that reflects your application's real dependency.
• Add endpoint metrics or usage thresholds to the preflight when they represent a deployment requirement.
• Explore the Quicknode CLI examples for endpoints, Streams, Webhooks, Key-Value Store, SQL Explorer, billing, and teams.
• Install the Build Web3 plugin and give your agent .ai/quicknode-cli.md before it starts a new project.
• Use the Quicknode MCP guide when you want an agent to work with Quicknode through tool calls rather than shell commands.

Frequently asked questions

Can I use qn before I have a Web3 project?

Yes. Use qn rpc call to read live chain data through Tooling Access, then use qn sql to explore indexed Hyperliquid data. This lets you validate an idea or give a coding agent current context before you create an application project.

Do I need a dedicated endpoint before using qn rpc call?

No. qn rpc call can use Tooling Access for read-only CLI and developer-tooling requests. Use a dedicated endpoint for production application traffic that requires independent security settings, rate limits, add-ons, or traffic isolation.

What does the deployment preflight validate?

It validates the API key, fetches one endpoint by its ID, confirms that endpoint is active on Base mainnet, and makes an eth_blockNumber request through its HTTP URL. It does not pass merely because another endpoint in the account is active.

Why does the preflight use a temporary config file?

The CLI does not automatically read API keys from environment variables. The script receives QUICKNODE_API_KEY from a secret store, writes a user-restricted temporary qn config file, passes it with --config-file, and removes it when the script exits.

Why does the GitHub Actions job skip forked pull requests?

GitHub does not pass repository secrets to workflows triggered from forks. The example runs for same-repository pull requests and trusted manual dispatches so an untrusted fork cannot access the Quicknode API key.

When should I use the CLI instead of the dashboard, SDK, or Quicknode MCP?

Use the CLI for repeatable terminal work, debugging, scripts, and CI. Use the dashboard for visual exploration and account configuration. Use an SDK or REST API from application code at runtime. Use Quicknode MCP when an agent should work with Quicknode through tool calls instead of shell commands.

We ❤️ Feedback!

Let us know if you have any feedback or requests for new topics. We'd love to hear from you.