x402 Agent Skill

Pay for x402-gated APIs and content using USDC on Base. This skill enables agents to autonomously make crypto payments when accessing paid web resources.

Quick Reference

Installation

npm i -g agentic-x402

Once installed, the x402 command is available globally:

x402 --help
x402 --version

Setup

Run the interactive setup to create a new wallet:

x402 setup

This will:

1. Generate a new wallet (recommended) or accept an existing key
2. Save configuration to ~/.x402/.env
3. Display your wallet address for funding

Important: Back up your private key immediately after setup!

Manual Configuration

Alternatively, set the environment variable directly:

export EVM_PRIVATE_KEY=0x...your_private_key...

Or create a config file:

mkdir -p ~/.x402
echo "EVM_PRIVATE_KEY=0x..." > ~/.x402/.env
chmod 600 ~/.x402/.env

Verify setup:

x402 balance

Paying for Resources

When you encounter HTTP 402 Payment Required

Use x402 pay to make the payment and access the content:

x402 pay https://api.example.com/paid-endpoint

The command will:

1. Check payment requirements
2. Verify amount is within limits
3. Process the payment
4. Return the gated content

Automatic payment with fetch

Use x402 fetch for seamless payment handling:

x402 fetch https://api.example.com/data --json

This wraps fetch with x402 payment handling - if the resource requires payment, it's handled automatically.

Payment limits

By default, payments are limited to $10 USD. Override with --max:

x402 pay https://expensive-api.com/data --max 50

Or set globally:

export X402_MAX_PAYMENT_USD=25

Dry run

Preview payment without executing:

x402 pay https://api.example.com/data --dry-run

Creating Payment Links (Seller)

Create payment links to monetize your own content using x402-links-server:

Setup for link creation

Add to .env:

X402_LINKS_API_URL=https://your-x402-links-server.com

Create a link

Gate a URL:

x402 create-link --name "Premium API" --price 1.00 --url https://api.example.com/premium

Gate text content:

x402 create-link --name "Secret" --price 0.50 --text "The secret message..."

With webhook notification:

x402 create-link --name "Guide" --price 5.00 --url https://mysite.com/guide --webhook https://mysite.com/payment-hook

Get link info

x402 link-info 0x1234...5678
x402 link-info https://21.cash/pay/0x1234...5678

Command Reference

x402 balance

Check wallet balances.

x402 balance [--json] [--full]

x402 pay

Pay for an x402-gated resource.

x402 pay \x3Curl> [options]

x402 fetch

Fetch with automatic payment.

x402 fetch \x3Curl> [options]

x402 create-link

Create a payment link.

x402 create-link --name \x3Cname> --price \x3Cusd> [options]

Note: Either --url or --text is required. The link is deployed as a smart contract on Base.

x402 link-info

Get payment link details.

x402 link-info \x3Crouter-address> [--json]

Environment Variables

Supported Networks

Payment Token

All payments use USDC (USD Coin) on the selected network.

• Base Mainnet: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
• Base Sepolia: 0x036CbD53842c5426634e7929541eC2318f3dCF7e

How x402 Works

1. Client requests a resource
2. Server responds with 402 Payment Required + payment details
3. Client signs a payment authorization (USDC transfer)
4. Client retries request with payment signature
5. Server verifies payment via facilitator
6. Server settles payment on-chain
7. Server returns the gated content

The x402 protocol is gasless for buyers - the facilitator sponsors gas fees.

Troubleshooting

"Missing required environment variable: EVM_PRIVATE_KEY"

Set your wallet private key:

export EVM_PRIVATE_KEY=0x...

Or create a .env file in your working directory, or install globally and use ~/.x402/.env.

"Payment exceeds max limit"

Increase the limit:

x402 pay https://... --max 50

Low balance warnings

Fund your wallet with:

• USDC for payments
• ETH for gas (small amount, ~0.001 ETH)

Network mismatch

Ensure your wallet has funds on the correct network:

• X402_NETWORK=mainnet → Base mainnet
• X402_NETWORK=testnet → Base Sepolia

Backup Your Private Key

Your private key is stored in ~/.x402/.env. If lost, your funds cannot be recovered.

Recommended Backup Methods

1. Password Manager (Recommended)

   • Store in 1Password, Bitwarden, or similar
   • Create a secure note with your private key
   • Tag it for easy retrieval

2. Encrypted File

   # Encrypt with GPG
   gpg -c ~/.x402/.env
   # Creates ~/.x402/.env.gpg - store this backup securely
   

3. Paper Backup (for larger amounts)

   • Write down the private key
   • Store in a safe or safety deposit box
   • Never store digitally unencrypted

View Your Private Key

cat ~/.x402/.env | grep EVM_PRIVATE_KEY

Recovery

To restore from backup:

mkdir -p ~/.x402
echo "EVM_PRIVATE_KEY=0x...your_backed_up_key..." > ~/.x402/.env
chmod 600 ~/.x402/.env
x402 balance  # verify

Security Best Practices

• Use a dedicated wallet — Never use your main wallet with automated agents
• Limit funds — Only transfer what you need for payments
• Set payment limits — Configure X402_MAX_PAYMENT_USD to cap exposure
• Test first — Use X402_NETWORK=testnet with test tokens before mainnet
• Protect the config — ~/.x402/.env has 600 permissions; keep it that way
• Never share — Your private key gives full access to your wallet

Links

• x402 Protocol Docs
• x402 GitHub
• npm: agentic-x402
• Base Network