@node4all/x402-agent-toolkit

MCP server that gives AI agents a wallet for the x402 payment protocol on Base.

Connect it to Claude Desktop and the agent can autonomously sign off-chain payment authorizations for any x402 v2 endpoint — no hardcoded payment logic. An x402 facilitator handles on-chain settlement and gas on the agent's behalf.

Tools

| Tool | Purpose | |------|---------| | x402_request | HTTP client that auto-handles x402 v2 payment challenges. On 402, signs an EIP-3009 authorization and retries. Returns the final response (binary content like PDFs is base64-encoded with body_format: "base64") + decoded settlement receipt. Supports multipart_form for file uploads. | | x402_quote | Probe an x402 v2 endpoint and return its price quote without paying — useful for budget-aware planning before calling x402_request. | | wallet_balance | Check ETH + USDC balances on Base Sepolia or Base Mainnet. Use it to confirm the agent has enough USDC before calling a paid endpoint. |

Quick start

1. Prepare a dedicated wallet

Generate a fresh key — or reuse an existing wallet:

node -e "console.log('0x' + require('node:crypto').randomBytes(32).toString('hex'))"

Fund it for testnet or mainnet. For Testnet you can use a Faucet to get some funds, for mainnet you'll need to purchase or deposit tokens.

• USDC (+ sometimes ETH): Circle faucet — drips Base Sepolia USDC
• ETH (optional): Alchemy faucet — only needed if you want to sign things outside the x402 flow; the facilitator pays gas for actual payments

2. Add to Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "x402-agent-toolkit": {
      "command": "npx",
      "args": ["-y", "@node4all/x402-agent-toolkit"],
      "env": {
        "PRIVATE_KEY": "0x_YOUR_PRIVATE_KEY",
        "MAX_USDC_PER_REQUEST": "0.10"
      }
    }
  }
}

Restart Claude Desktop — the three tools will appear.

Windows note: if Claude Desktop fails to start the server, replace "command": "npx" with "command": "npx.cmd". Claude Desktop spawns subprocesses without shell resolution, and Windows needs the .cmd extension. See Windows setup for a direct-node alternative.

3. Try it

Ask Claude:

Check my wallet balance on base-sepolia, then call https://sandbox.node4all.com/v1/x402-test on base-sepolia — pay if required.

Claude will:

1. Call wallet_balance → see that USDC is available.
2. Call x402_request with the URL and network: "base-sepolia".

Inside step 2 the tool:

1. Gets 402 Payment Required with a base64-encoded PAYMENT-REQUIRED header.
2. Checks the asked amount against MAX_USDC_PER_REQUEST.
3. Signs an EIP-3009 transferWithAuthorization with the agent wallet.
4. Retries with a base64-encoded PAYMENT-SIGNATURE header.
5. The x402 facilitator verifies + settles on-chain.
6. Returns the 200 response, a decoded PAYMENT-RESPONSE receipt (settled tx hash), and the endpoint body.

All from one tool call.

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | PRIVATE_KEY | yes | Agent wallet private key (0x-prefixed, 64 hex chars). | | MAX_USDC_PER_REQUEST | no | Per-request USDC cap, decimal string (e.g. "0.10"). If a 402 quotes an amount above the cap, the tool filters that payment option out. If the server advertised no cheaper option, payment fails before any signature is produced. Strongly recommended on mainnet. |

A hallucinating or jailbroken agent can still attempt to call any URL it's told about, but it can never authorize a transfer above the cap.

Networks

| Network | Chain ID (CAIP-2) | USDC contract | |---------|--------------------|---------------| | base-sepolia | eip155:84532 | 0x036CbD53842c5426634e7929541eC2318f3dCF7e | | base-mainnet | eip155:8453 | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |

The tool maps the network argument to the right viem chain + USDC contract automatically. Solana support will arrive when servers advertise SVM payment options in their accepts[].

Security

• Private key stays on your machine — read from env vars, never transmitted.
• Use a dedicated agent wallet.
• On mainnet, always set MAX_USDC_PER_REQUEST.
• Keep the wallet balance small. Top it up as needed.
• The x402 facilitator is the only third party that ever sees the signed authorization.

Windows setup

Claude Desktop spawns MCP servers as raw subprocesses (no shell), which trips up npx resolution on Windows. Two fixes:

Option A — use npx.cmd:

"command": "npx.cmd",
"args": ["-y", "@node4all/x402-agent-toolkit"]

Option B — install globally once, then call the installed binary:

npm install -g @node4all/x402-agent-toolkit

"command": "x402-agent-toolkit.cmd"

Either works. Remember to escape backslashes in any Windows path inside JSON: "C:\\path\\to\\thing".

Development

git clone https://github.com/MadeCode/x402.git
cd x402/x402-agent-toolkit
npm install
npm run build

Run from source via Claude Desktop:

{
  "mcpServers": {
    "x402-agent-toolkit": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "/absolute/path/to/x402-agent-toolkit",
      "env": {
        "PRIVATE_KEY": "0x_YOUR_KEY",
        "MAX_USDC_PER_REQUEST": "0.10"
      }
    }
  }
}

For local testing on Windows, point node at the built file directly — this sidesteps the npx issue entirely:

{
  "mcpServers": {
    "x402-agent-toolkit-local": {
      "command": "node",
      "args": ["C:\\absolute\\path\\to\\x402-agent-toolkit\\dist\\index.js"],
      "env": {
        "PRIVATE_KEY": "0x_YOUR_KEY",
        "MAX_USDC_PER_REQUEST": "0.10"
      }
    }
  }
}

Requirements

• Node.js >= 20 (Node >= 22 recommended)

Links

• node4all.com — x402 documentation & sandbox
• /.well-known/x402.json — machine-readable discovery catalogue
• /llms.txt — agent-friendly service description
• x402 fundamentals blog post
• x402 protocol — spec
• GitHub

License

MIT