x402

name	x402
description	Set up, manage, and troubleshoot the x402 MCP payment server for Claude Code. Use when the user wants to configure x402 payments, check wallet status, manage budgets, fix MCP connection issues, or integrate paid APIs into their project.
argument-hint	[setup|status|budget|topup|troubleshoot]
disable-model-invocation	true
allowed-tools	Bash(node *), Read, Write, Edit, Glob, AskUserQuestion

/x402 — x402 Payment MCP Server Management

You are managing the x402 MCP Server — an MCP server that gives Claude the ability to call paid APIs automatically using the x402 protocol (HTTP 402 + ERC-3009 USDC payments on Base).

Skill resources

This skill bundles supporting files. Load them when needed — do NOT load all upfront.

File	When to load	Purpose
templates/mcp-config-project.json	During setup (Step 6)	Config template for .mcp.json — local dev entry point
templates/mcp-config-npm.json	During setup (Step 6)	Config template for npm-published @coinwall/mcp
examples/tool-responses.md	When interpreting MCP tool output	All 4 tool response formats with success/error variants
examples/usage-scenarios.md	When unsure how to present results	8 real-world interaction scenarios
scripts/generate-wallet.mjs	During setup (Step 3)	Generate a new wallet private key
scripts/validate-config.mjs	During troubleshoot	Validate MCP config structure and env vars
scripts/health-check.mjs	During troubleshoot	Spawn MCP server process and verify it responds

Scripts are executed via Bash: node ${CLAUDE_SKILL_DIR}/scripts/<name>.mjs

What x402 MCP provides

Once configured, Claude gains 4 MCP tools:

Tool	Purpose
fetch_paid_api	Fetch any URL with automatic x402 payment — probe for 402, sign ERC-3009, retry with payment header
check_balance	Query on-chain USDC balance and wallet address
check_price	Probe a URL's x402 pricing without paying
discover_resources	List available paid API resources on a gateway (Bazaar protocol)

Subcommand routing

Parse $ARGUMENTS to determine the action. Default to setup if empty.

Argument	Action
(empty) or setup	Full setup flow
status	Status check
budget	Budget management
topup	Top-up guide
troubleshoot	Troubleshooting

---

Setup flow

Step 1: Check existing configuration

Search for an existing x402 MCP server entry in these locations (in priority order):

1. .mcp.json in the current project directory
2. ~/.claude/settings.json (global user settings)

If found, display the current config (mask the private key: show first 6 + last 4 chars) and ask:

x402 MCP is already configured:

• Wallet: 0xABC...1234
• Network: Base Sepolia
• Budget: $0.01/call, $1.00/hour, $50.00 total

What would you like to do?

1. Reconfigure — start fresh
2. Update budget — change spending limits only
3. Keep current — no changes needed

If not found, proceed to Step 2.

Step 2: Choose installation scope

Ask:

Where should I configure the x402 MCP server?

1. This project only (.mcp.json) — recommended for project-specific use
2. All projects (~/.claude/settings.json) — available everywhere

Step 3: Wallet configuration

Ask:

To make payments on the Base network, you need a wallet with USDC.

1. Use existing wallet — paste your private key (0x...)
2. Generate new wallet — I'll create a fresh wallet (you'll need to fund it)

If generating a new wallet, run the bundled script:

node ${CLAUDE_SKILL_DIR}/scripts/generate-wallet.mjs

Show the user their private key and warn them to save it securely — it cannot be recovered.

To derive the address (if viem is available in the project):

node -e "const { privateKeyToAccount } = require('viem/accounts'); console.log(privateKeyToAccount('<PRIVATE_KEY>').address);"

If using an existing wallet, ask for the private key. Validate it starts with 0x and is 66 characters long.

Step 4: Network selection

Ask:

Which network?

1. Base Sepolia (testnet) — free test USDC, for development. Network ID: eip155:84532
2. Base Mainnet — real USDC, for production. Network ID: eip155:8453

Step 5: Budget limits

Ask:

Set spending safety limits (all in USDC, leave blank to skip):

• Max per call: Maximum for a single API request (recommended: 0.01)
• Max per hour: Rolling hourly cap (recommended: 1.00)
• Max total: Lifetime total cap (recommended: 50.00)

All limits are optional. If the user skips all, warn that there are no spending guardrails.

Step 6: Write configuration

Choose the config template based on the user's environment:

1. Check if developing locally: Look for src/sdk/mcp/index.ts in the current project.

   • If found → Read templates/mcp-config-project.json. Replace {{ENTRY_PATH}} with the absolute path to src/sdk/mcp/index.ts.
   • If not found (normal user) → Read templates/mcp-config-npm.json. Uses npx @coinwall/mcp (no local path needed).

2. Replace all {{PLACEHOLDER}} values with user input from previous steps. Omit env vars that the user left blank — do not include keys with empty string values.

3. Merge, don't overwrite: If the target config file already exists, read it first, merge the x402 entry into the existing mcpServers object, then write back. Do not clobber other MCP servers.

For ~/.claude/settings.json (global scope): same mcpServers.x402 structure nested under the global settings format.

Step 7: Verify and report

After writing the config:

1. Tell the user to restart Claude Code (or run /mcp to reload MCP servers)
2. Show a summary:

x402 payment configured!

• Wallet: 0xABC...1234
• Network: Base Sepolia (testnet)
• Budget: $0.01/call, $1.00/hour, $50.00 total
• Config: .mcp.json

Next steps:

1. Restart Claude Code to load the MCP server
2. Fund your wallet with USDC on Base Sepolia
3. Ask me to fetch any x402 paid API — I'll handle payment automatically

Quick test after restart:

Check my x402 wallet balance

---

Status check

When the user runs /x402 status:

1. Read the MCP config from .mcp.json or ~/.claude/settings.json
2. If not configured, suggest running /x402 setup
3. If configured, display:
   • Wallet address (derive from private key if possible, otherwise mask key)
   • Network
   • Budget limits
   • Config file location
4. Try to invoke check_balance MCP tool if available to show live balance

---

Budget management

When the user runs /x402 budget:

1. Read current config
2. Show current limits
3. Ask which limits to change
4. Update the config file in place (preserve all other settings)

---

Top-up guide

When the user runs /x402 topup:

1. Read config, extract wallet address and network
2. Provide network-specific funding instructions:

Base Sepolia (testnet):

To get test USDC on Base Sepolia:

1. Get testnet ETH from Base Sepolia Faucet
2. Get test USDC from a USDC faucet or bridge
3. Send to your wallet: <address>

Base Mainnet:

To fund your wallet with real USDC:

1. Send USDC on Base network to: <address>
2. You can bridge USDC from Ethereum/other chains via Base Bridge
3. Minimum recommended: $5 USDC for testing

---

Troubleshooting

When the user runs /x402 troubleshoot:

Automated checks

Run the bundled validation script first:

node ${CLAUDE_SKILL_DIR}/scripts/validate-config.mjs

This checks: config file exists → JSON valid → x402 entry present → wallet key format → network ID → budget values. Report the output verbatim.

If all checks pass but the MCP server still isn't working, run the health check:

node ${CLAUDE_SKILL_DIR}/scripts/health-check.mjs <path-to-entry-from-config>

This spawns the MCP server process and verifies it responds to an initialize handshake.

Manual checks (if scripts fail)

1. Config exists? — Read .mcp.json and ~/.claude/settings.json. Report if x402 entry is found.
2. Config valid? — Check command, args, COINWALL_WALLET_KEY (starts with 0x, 66 chars), COINWALL_NETWORK (valid CAIP-2).
3. Entry point exists? — Verify the file path in args resolves to an existing file.
4. Dependencies? — Run node -e "require('@modelcontextprotocol/sdk')" etc.

Common issues

Symptom	Cause	Fix
"COINWALL_WALLET_KEY is required"	Missing env var in MCP config	Add COINWALL_WALLET_KEY to the env section
MCP server not showing up	Config not loaded	Restart Claude Code or run /mcp
"insufficient_balance" on every call	Wallet has no USDC	Run /x402 topup for funding instructions
"budget_exceeded"	Spending limit hit	Run /x402 budget to adjust limits, or wait for hourly window reset
"payment_failed"	Server rejected payment	Check network matches the API's expected network
Tool calls timeout	MCP process crashed	Check args path is correct, try running the entry point manually

Report all findings with pass/fail status and actionable fixes for any failures.

---

Environment variable reference

Variable	Required	Default	Description
COINWALL_WALLET_KEY	Yes	—	Wallet private key (0x...) for ERC-3009 signing
COINWALL_NETWORK	No	eip155:84532	CAIP-2 network ID (Base Sepolia or Base Mainnet)
COINWALL_MAX_PER_CALL	No	unlimited	Max USDC per single API call
COINWALL_MAX_PER_HOUR	No	unlimited	Max USDC per rolling hour window
COINWALL_MAX_TOTAL	No	unlimited	Max USDC lifetime total
COINWALL_RPC_URL	No	public Base RPC	Custom RPC endpoint for balance queries