x402-cli

Test x402 payment-gated APIs from your terminal. No ETH or SOL needed for gas.

Features

• Health Check — Validate x402 endpoints without a wallet
• Agent Discovery — Discover A2A protocol agent cards
• Multi-Chain Payments — Execute gasless EIP-3009 (EVM) and SPL token transfers (Solana)
• Batch Testing — Check multiple endpoints in parallel
• Network Explorer — List all supported networks, tokens, and explorers
• Keystore Support — Works with Foundry/Geth keystores and Solana keypairs
• Shell Completion — Tab completion for bash, zsh, fish, and PowerShell
• CI/CD Ready — JSON output, exit codes, and -y flag for automation
• Dry Run Mode — Preview payments before executing

Table of Contents

• Installation
• Quick Start
• Sample Output
• Commands
• Configuration
• Examples
• How x402 Works
• Creating a Wallet
• Development
• Contributing

Installation

Homebrew (macOS/Linux)

brew tap port402/tap
brew install x402-cli

Go Install

go install github.com/port402/x402-cli/cmd/x402@latest

Binary Download

Download pre-built binaries from the releases page.

Quick Start

Check if an endpoint is x402-enabled (no wallet needed)

x402 health api.example.com/resource                   # https:// auto-prefixed
x402 health https://api.example.com/resource --agent   # Also check for agent card

Discover A2A agent card

x402 agent https://api.example.com

Make a test payment (EVM)

x402 test https://api.example.com/resource --keystore ~/.foundry/keystores/my-wallet

Make a test payment (Solana)

x402 test https://api.example.com/resource --solana-keypair ~/.config/solana/id.json

Preview payment without executing

x402 test https://api.example.com/resource --keystore ~/.foundry/keystores/my-wallet --dry-run

Sample Output

Health Check (EVM + Solana)

$ x402 health https://jupiter.api.corbits.dev/ultra/v1/order

✓ https://jupiter.api.corbits.dev/ultra/v1/order

  Status:   402 Payment Required
  Protocol: v1 (legacy)
  Latency:  260ms
  Payment:  0.01 USDC on Solana Mainnet

  Checks:
    ✓ Endpoint reachable
    ✓ Returns 402
    ✓ Valid payment body
    ✓ Has payment options
    ✓ Has EVM option
    ✓ Has Solana option
    ✓ Known token

Health Check with Agent Discovery

$ x402 health https://api.example.com/endpoint --agent

✓ https://api.example.com/endpoint

  Status:   402 Payment Required
  Protocol: v2 (current)
  Latency:  120ms
  Payment:  0.01 USDC on Base

  Checks:
    ✓ Endpoint reachable
    ✓ Returns 402
    ✓ Valid payment header
    ✓ Has payment options
    ✓ Has EVM option
    ✓ Known token

  Agent:    Recipe Agent v1.0.0
            Agent that helps with recipes
  Provider: Example Inc (https://example.com)

  Skills:
    • recipe-search
      Find recipes by ingredients or cuisine type
    • meal-plan
      Generate weekly meal plans based on preferences

  Capabilities: streaming

Dry Run

$ x402 test https://x402-dotnet.azurewebsites.net/resource/middleware \
    --keystore ~/.foundry/keystores/test --dry-run

✓ x402 endpoint detected (v2)

Payment Requirements:
  Network:   Base Sepolia (eip155:84532)
  Token:     USDC (0x036c...cf7e)
  Amount:    0.001000 USDC
  Recipient: 0xB889...64fc

⚠ Dry run mode - no payment will be made

Successful Payment

$ x402 test https://x402-dotnet.azurewebsites.net/resource/middleware \
    --keystore ~/.foundry/keystores/test

✓ x402 endpoint detected (v2)

Payment Requirements:
  Network:   Base Sepolia (eip155:84532)
  Token:     USDC (0x036c...cf7e)
  Amount:    0.001000 USDC
  Recipient: 0xB889...64fc

? Proceed with payment? [y/N] y

  • Loading wallet...
  • Signing payment authorization...
  • Sending payment...

✓ Payment successful!
  Transaction: 0xb945a8c...
  Explorer:    https://sepolia.basescan.org/tx/0xb945a8c...

Response (200 OK):
{
  "message": "Access granted",
  "timestamp": "2026-01-12T10:30:00Z"
}

Agent Discovery (Found)

$ x402 agent https://api.example.com

✓ Agent card found (/.well-known/agent.json)

Agent:
  Name:        Recipe Agent
  Version:     1.0.0
  Description: Agent that helps with recipes

Skills:
  • recipe-search — Find recipes by ingredients
  • meal-plan — Generate weekly meal plans

Docs: https://docs.example.com/agent

Agent Discovery (Not Found)

$ x402 agent https://example.com

⚠ No agent card found

Tried:
  • /.well-known/agent.json (404)
  • /.well-known/agent-card.json (404)
  • /.well-known/agents.json (404)

Hint: Use --card-url to specify a custom location

Commands

x402 health <url>

Check if an endpoint is x402-enabled and validate its payment requirements.

x402 health https://api.example.com/endpoint
x402 health https://api.example.com/endpoint --json          # JSON output
x402 health https://api.example.com/endpoint --method POST   # POST-only APIs
x402 health https://api.example.com/endpoint --agent         # Also discover agent card

Flag	Description
--agent	Also discover A2A agent card from the endpoint
--method	HTTP method (default: GET)
--timeout	Request timeout in seconds (default: 30)

x402 agent <url>

Discover A2A (Agent-to-Agent) protocol agent cards from endpoints.

x402 agent https://api.example.com                           # Auto-discover
x402 agent https://api.example.com --json                    # JSON output
x402 agent https://api.example.com --card-url /custom/agent.json  # Custom path

Flag	Description
--card-url	Custom agent card path (overrides discovery)
--timeout	Request timeout in seconds (default: 5)

Discovery paths (tried in order):

1. /.well-known/agent.json (A2A v0.1)
2. /.well-known/agent-card.json (A2A v0.2+)
3. /.well-known/agents.json (Wildcard spec)

x402 test <url>

Make a test payment to an x402 endpoint.

# EVM payments (Base, Ethereum, etc.)
x402 test <url> --keystore <path>                    # Interactive mode
x402 test <url> --keystore <path> --dry-run          # Preview only
x402 test <url> --keystore <path> --max-amount 0.05  # Safety cap

# Solana payments
x402 test <url> --solana-keypair ~/.config/solana/id.json

Flag	Description
--keystore	Path to EVM Web3 keystore file
--wallet	Hex-encoded EVM private key (or PRIVATE_KEY env)
--solana-keypair	Path to Solana keypair file (JSON array or Base58)
--solana-rpc	Custom Solana RPC endpoint URL
--dry-run	Show payment details without executing
-y, --no-confirm	Skip payment confirmation prompt
--skip-payment-confirmation	Skip payment confirmation prompt (alias)
--max-amount	Maximum payment amount (safety cap)
--method	HTTP method (GET, POST, PUT)
--header	Custom HTTP header (repeatable)
--data	Request body for POST/PUT
--timeout	Request timeout in seconds

Chain Selection:

• If --solana-keypair is provided and endpoint supports Solana, Solana is preferred
• If only EVM wallet is provided, EVM network is used
• If endpoint supports both and both wallets provided, Solana is preferred

x402 batch-health <file>

Check multiple endpoints from a JSON file.

x402 batch-health urls.json
x402 batch-health urls.json --parallel 5    # Parallel execution
x402 batch-health urls.json --fail-fast     # Stop on first failure

Input formats:

["https://api1.example.com", "https://api2.example.com"]

[{"url": "https://api.example.com", "method": "POST"}]

x402 networks

List all supported blockchain networks with their CAIP-2 identifiers, tokens, and explorers.

x402 networks            # Table output
x402 networks --json     # JSON output

x402 completion

Generate shell completion scripts for tab-completion support.

x402 completion bash        # Bash
x402 completion zsh         # Zsh
x402 completion fish        # Fish
x402 completion powershell  # PowerShell

# Example: enable for current bash session
source <(x402 completion bash)

# Example: persist for zsh
x402 completion zsh > "${fpath[1]}/_x402"

x402 version

x402 version
x402 version --json

Configuration

EVM Private Key Sources (priority order)

1. --keystore ~/.foundry/keystores/my-wallet
2. --wallet 0xac0974...
3. PRIVATE_KEY=0xac0974... environment variable
4. Stdin: echo "0xac0974..." | x402 test ...

Solana Keypair Sources

1. --solana-keypair ~/.config/solana/id.json (JSON array format)
2. --solana-keypair ~/.config/solana/id.json (Base58 string format)

Supported keypair formats:

• JSON array: [1,2,3,...64 bytes...] (Solana CLI format)
• Base58 string: Encoded 64-byte keypair

Supported Networks

Run x402 networks to see all supported networks with their tokens and explorers.

EVM Networks

Network	Chain ID
Ethereum	eip155:1
Base	eip155:8453
Base Sepolia	eip155:84532
Polygon	eip155:137
Arbitrum One	eip155:42161
Optimism	eip155:10

Solana Networks

Network	CAIP-2 Identifier
Solana Mainnet	solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
Solana Devnet	solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
Solana Testnet	solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z

Supported Tokens

USDC on all supported networks (EVM and Solana).

Exit Codes

Code	Meaning
0	Success
1	General failure
2	Input validation error
3	Network error
4	Protocol error
5	Payment rejected

Examples

CI/CD Integration

# Health check with JSON parsing
x402 health https://api.example.com/endpoint --json | jq '.exitCode'

# Dry-run in CI (use -y to skip confirmation)
x402 test https://api.example.com/endpoint \
  --keystore ./test-wallet.json \
  --dry-run -y

Batch Testing Script

#!/bin/bash
for url in "https://api1.example.com" "https://api2.example.com"; do
  x402 test "$url" \
    --keystore ~/.foundry/keystores/test \
    --max-amount 0.01 -y
done

Getting Test USDC

For EVM (Base Sepolia)

1. Go to Circle's Faucet
2. Select Base Sepolia
3. Choose USDC
4. Enter your wallet address

For Solana (Devnet)

1. Go to Circle's Faucet
2. Select Solana Devnet
3. Choose USDC
4. Enter your Solana wallet address

How x402 Works

The x402 protocol enables payment-gated APIs using HTTP 402 responses with gasless token transfers:

• EVM chains: Uses EIP-3009 gasless USDC transfers
• Solana: Uses SPL token transfers with facilitator-paid fees

┌─────────┐                    ┌─────────┐                    ┌─────────────┐
│  Client │                    │  Server │                    │ Facilitator │
└────┬────┘                    └────┬────┘                    └──────┬──────┘
     │                              │                                │
     │  1. GET /resource            │                                │
     │ ───────────────────────────> │                                │
     │                              │                                │
     │  2. 402 Payment Required     │                                │
     │     + payment requirements   │                                │
     │ <─────────────────────────── │                                │
     │                              │                                │
     │  3. Sign EIP-3009 auth       │                                │
     │     (gasless, off-chain)     │                                │
     │                              │                                │
     │  4. GET /resource            │                                │
     │     + X-PAYMENT header       │                                │
     │ ───────────────────────────> │                                │
     │                              │                                │
     │                              │  5. Verify & settle payment    │
     │                              │ ──────────────────────────────>│
     │                              │                                │
     │                              │  6. Payment confirmed          │
     │                              │ <──────────────────────────────│
     │                              │                                │
     │  7. 200 OK + resource        │                                │
     │ <─────────────────────────── │                                │
     │                              │                                │

Key Concepts

Term	Description
HTTP 402	Status code indicating payment is required
EIP-3009	Gasless token transfer standard (no ETH needed)
Facilitator	Service that verifies and settles payments on-chain
X-PAYMENT	Header containing the signed payment authorization

Learn More

• x402 Protocol
• Coinbase x402 Docs
• Solana x402 Guide
• A2A Protocol — Agent-to-Agent discovery standard
• EIP-3009 Spec
• EIP-712 Spec

Creating a Wallet

The test command requires a wallet. Choose based on your target network:

EVM Wallet (Base, Ethereum, etc.)

Using Foundry (Recommended)

# Install Foundry
curl -L https://foundry.paradigm.xyz | bash
foundryup

# Create a new keystore
cast wallet new ~/.foundry/keystores/

# Or import existing key
cast wallet import my-wallet --interactive

Using Geth

geth account new --keystore ~/.keystores/

Solana Keypair

Using Solana CLI (Recommended)

# Install Solana CLI
sh -c "$(curl -sSfL https://release.solana.com/stable/install)"

# Create a new keypair
solana-keygen new --outfile ~/.config/solana/id.json

# View your address
solana address

Using an existing keypair

The CLI supports two formats:

• JSON array: [1,2,3,...64 bytes...] (default Solana CLI format)
• Base58 string: Encoded 64-byte keypair

Security: Never share your keystore, keypair, or password. Use dedicated wallets with only test funds.

Development

Building from Source

git clone https://github.com/port402/x402-cli.git
cd x402-cli
make build

Make Targets

Target	Description
make build	Build the binary
make test	Run tests
make lint	Run linter
make check	Run all checks
make help	Show all targets

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Security

Report vulnerabilities via SECURITY.md. Do not open public issues for security concerns.

License

MIT — see LICENSE