Make x402 payments to access gated APIs and content. Fetch paid resources, check wallet balance, and create payment links. Use when encountering 402 Payment Required responses or when the user wants to pay for web resources with crypto. Use when this capability is needed.
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.
| Command | Description |
|---|---|
x402 setup | Create or configure wallet |
x402 balance | Check USDC and ETH balances |
x402 pay <url> | Pay for a gated resource |
x402 fetch <url> | Fetch with auto-payment |
x402 create-link | Create payment link (seller) |
x402 link-info <addr> | Get payment link details |
npm i -g agentic-x402
Once installed, the x402 command is available globally:
x402 --help
x402 --version
Run the interactive setup to create a new wallet:
x402 setup
This will:
~/.x402/.envImportant: Back up your private key immediately after setup!
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
Use x402 pay to make the payment and access the content:
x402 pay https://api.example.com/paid-endpoint
The command will:
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.
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
Preview payment without executing:
x402 pay https://api.example.com/data --dry-run
Create payment links to monetize your own content using x402-links-server:
Add to .env:
X402_LINKS_API_URL=https://your-x402-links-server.com
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
x402 link-info 0x1234...5678
x402 link-info https://21.cash/pay/0x1234...5678
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 | — |
Pay for an x402-gated resource.
x402 pay <url> [options]
| Flag | Description | Default |
|---|---|---|
<url> | 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 | — |
Fetch with automatic payment.
x402 fetch <url> [options]
| Flag | Description | Default |
|---|---|---|
<url> | 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 | — |
Create a payment link.
x402 create-link --name <name> --price <usd> [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
--urlor--textis required. The link is deployed as a smart contract on Base.
Get payment link details.
x402 link-info <router-address> [--json]
| Flag | Description | Default |
|---|---|---|
<address> | Router contract address or full payment URL (positional) | required |
--json | Output as JSON | — |
-h, --help | Show help | — |
| Variable | Description | Default |
|---|---|---|
EVM_PRIVATE_KEY | Wallet private key (0x-prefixed) | required |
X402_NETWORK | mainnet (Base, chain 8453) or testnet (Base Sepolia, chain 84532) | mainnet |
X402_MAX_PAYMENT_USD | Safety limit — payments exceeding this are rejected unless --max is used | 10 |
X402_FACILITATOR_URL | Custom facilitator URL | Coinbase (mainnet) / x402.org (testnet) |
X402_SLIPPAGE_BPS | Slippage tolerance in basis points (100 bps = 1%) | 50 |
X402_VERBOSE | Enable verbose logging (1 = on, 0 = off) | 0 |
X402_LINKS_API_URL | Base URL of x402-links-server (e.g., https://21.cash) | — |
| Network | Chain ID | CAIP-2 ID |
|---|---|---|
| Base Mainnet | 8453 | eip155:8453 |
| Base Sepolia | 84532 | eip155:84532 |
All payments use USDC (USD Coin) on the selected network.
0x833589fCD6eDb6E08f4c7C32D4f71b54bdA029130x036CbD53842c5426634e7929541eC2318f3dCF7e402 Payment Required + payment detailsThe x402 protocol is gasless for buyers - the facilitator sponsors gas fees.
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.
Increase the limit:
x402 pay https://... --max 50
Fund your wallet with:
Ensure your wallet has funds on the correct network:
X402_NETWORK=mainnet → Base mainnetX402_NETWORK=testnet → Base SepoliaYour private key is stored in ~/.x402/.env. If lost, your funds cannot be recovered.
Password Manager (Recommended)
Encrypted File
# Encrypt with GPG
gpg -c ~/.x402/.env
# Creates ~/.x402/.env.gpg - store this backup securely
Paper Backup (for larger amounts)
cat ~/.x402/.env | grep EVM_PRIVATE_KEY
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
X402_MAX_PAYMENT_USD to cap exposureX402_NETWORK=testnet with test tokens before mainnet~/.x402/.env has 600 permissions; keep it that wayConverted and distributed by TomeVault | Claim this content