x402 Wallet — Claude Code MCP server: features and setup
Let an AI agent find x402 services, check prices, and pay for calls in USDC from a Solana wallet. Set a wallet key to enable payments.
claude mcp add --env SOLANA_SECRET_KEY=<SOLANA_SECRET_KEY> --env SOLANA_RPC_URL=<SOLANA_RPC_URL> --env MAX_PAY_USD=<MAX_PAY_USD> --env REQUIRE_CONFIRM=<REQUIRE_CONFIRM> --env THREE_WS_BASE=<THREE_WS_BASE> --transport stdio x402-mcp -- npx -y @three-ws/x402-mcpWhat x402 Wallet does
x402 Wallet gives an agent tools to search the x402 service directory, inspect an endpoint’s payment terms, and call a paid service. Named tools cover tasks such as weather forecasts, research and book searches, news, transit, and places. The server can also show wallet balances and payment totals.
Payments require SOLANA_SECRET_KEY; service discovery and endpoint inspection do not. The server settles only Solana exact-scheme payments and checks the price before funds move. It rejects amounts above MAX_PAY_USD, which defaults to $1. With REQUIRE_CONFIRM enabled, a payment call also needs confirm: true. Your key signs the payment.
For Claude Code, add the server with npx -y @three-ws/x402-mcp. You can configure SOLANA_RPC_URL, a spending cap, and confirmation requirements. Setup commands are also provided for Codex and other supported editors.
What it helps with
- search the x402 directory for paid HTTP and MCP services
- inspect an endpoint’s price before paying
- call a service and settle its fee in USDC
- check a wallet balance and review payment totals
Example prompts for the agent
- Find x402 services that can search academic papers.
- Inspect this endpoint’s payment terms without paying.
- Call the weather forecast service and return its result.
How to install x402 Wallet
Platform CLI
claude mcp add --env SOLANA_SECRET_KEY=<SOLANA_SECRET_KEY> --env SOLANA_RPC_URL=<SOLANA_RPC_URL> --env MAX_PAY_USD=<MAX_PAY_USD> --env REQUIRE_CONFIRM=<REQUIRE_CONFIRM> --env THREE_WS_BASE=<THREE_WS_BASE> --transport stdio x402-mcp -- npx -y @three-ws/x402-mcpReplace <…> with your own values
Platform CLI
codex mcp add x402-mcp --env SOLANA_SECRET_KEY=<SOLANA_SECRET_KEY> --env SOLANA_RPC_URL=<SOLANA_RPC_URL> --env MAX_PAY_USD=<MAX_PAY_USD> --env REQUIRE_CONFIRM=<REQUIRE_CONFIRM> --env THREE_WS_BASE=<THREE_WS_BASE> -- npx -y @three-ws/x402-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"x402-mcp": {
"command": "npx",
"args": [
"-y",
"@three-ws/x402-mcp"
],
"env": {
"SOLANA_SECRET_KEY": "<SOLANA_SECRET_KEY>",
"SOLANA_RPC_URL": "<SOLANA_RPC_URL>",
"MAX_PAY_USD": "<MAX_PAY_USD>",
"REQUIRE_CONFIRM": "<REQUIRE_CONFIRM>",
"THREE_WS_BASE": "<THREE_WS_BASE>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"x402-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@three-ws/x402-mcp"
],
"env": {
"SOLANA_SECRET_KEY": "<SOLANA_SECRET_KEY>",
"SOLANA_RPC_URL": "<SOLANA_RPC_URL>",
"MAX_PAY_USD": "<MAX_PAY_USD>",
"REQUIRE_CONFIRM": "<REQUIRE_CONFIRM>",
"THREE_WS_BASE": "<THREE_WS_BASE>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e SOLANA_SECRET_KEY=<SOLANA_SECRET_KEY> -e SOLANA_RPC_URL=<SOLANA_RPC_URL> -e MAX_PAY_USD=<MAX_PAY_USD> -e REQUIRE_CONFIRM=<REQUIRE_CONFIRM> -e THREE_WS_BASE=<THREE_WS_BASE> x402-mcp npx -y @three-ws/x402-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about x402 Wallet
How do I install x402 Wallet in Claude Code?
Run claude mcp add x402-mcp -e SOLANA_SECRET_KEY=<SOLANA_SECRET_KEY> -- npx -y @three-ws/x402-mcp. A second setup command adds SOLANA_RPC_URL, MAX_PAY_USD, REQUIRE_CONFIRM, and THREE_WS_BASE as environment values.
What does x402 Wallet do?
It lets an agent discover paid x402 services, inspect payment requirements, and make USDC payments for service calls. The server also includes tools for selected services and payment reporting.
Can I search services without a Solana key?
Yes. find_services and inspect_endpoint work without a key. pay_and_call uses SOLANA_SECRET_KEY, unless you use the session_token settlement mode.
