Agentic X402

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

| Command | Description | |---------|-------------| | x402 setup | Create or configure wallet | | x402 balance | Check USDC and ETH balances | | x402 pay | Pay for a gated resource | | x402 fetch | Fetch with auto-payment | | x402 create-link | Create payment link (seller) | | x402 link-info | Get payment link details |

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]

| Flag | Description | Default | |------|-------------|---------| | --json | Output as JSON (address, network, chainId, balances) | — | | --full | Show full wallet address instead of truncated | — | | -h, --help | Show help | — |

x402 pay

Pay for an x402-gated resource.

x402 pay  [options]

| Flag | Description | Default | |------|-------------|---------| | | The URL of the x402-gated resource (positional) | required | | --method | HTTP method | GET | | --body | Request body (for POST/PUT requests) | — | | --header | Add custom header (can be used multiple times) | — | | --max | Maximum payment in USD (overrides config) | from config | | --dry-run | Show payment details without paying | — | | -h, --help | Show help | — |

x402 fetch

Fetch with automatic payment.

x402 fetch  [options]

| Flag | Description | Default | |------|-------------|---------| | | The URL to fetch (positional) | required | | --method | HTTP method | GET | | --body | Request body (for POST/PUT) | — | | --header | Add header as "Key: Value" | — | | --json | Output as JSON only (for piping to other tools) | — | | --raw | Output raw response body only (no headers or status) | — | | -h, --help | Show help | — |

x402 create-link

Create a payment link.

x402 create-link --name  --price  [options]

| Flag | Description | Default | |------|-------------|---------| | --name | Name of the payment link | required | | --price | Price in USD (e.g., "5.00" or "0.10") | required | | --url | URL to gate behind payment | — | | --text | Text content to gate behind payment | — | | --desc | Description of the link | — | | --webhook | Webhook URL for payment notifications | — | | --json | Output as JSON | — | | -h, --help | Show help | — |

> 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  [--json]

| Flag | Description | Default | |------|-------------|---------| |

export EVM_PRIVATE_KEY=0x...

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

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

cat ~/.x402/.env | grep EVM_PRIVATE_KEY

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

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

"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:

Network mismatch

Ensure your wallet has funds on the correct network: