x402 Wallet

@three-ws/x402-mcp

Give any AI agent a self-custodial x402 wallet — discover, inspect, and pay any paid service in USDC from your own Solana key.

---

A Model Context Protocol server that turns any AI assistant into an autonomous economic agent on the x402 network. Search the live bazaar for paid services, read an endpoint's price before committing money, and pay_and_call any x402 service in USDC — settled on Solana with your own key, never a custodial wallet.

This is the buyer side of the three.ws agent economy. The payment dance and Solana exact-scheme signing are handled by the real @x402/* libraries — nothing is mocked.

Install

npm install @three-ws/x402-mcp

Or run with npx:

SOLANA_SECRET_KEY=<base58> npx @three-ws/x402-mcp

Quick start

Claude Code, one line:

claude mcp add x402 --env SOLANA_SECRET_KEY=<base58> -- npx -y @three-ws/x402-mcp

Claude Desktop / Cursor (claude_desktop_config.json or mcp.json):

{
	"mcpServers": {
		"x402": {
			"command": "npx",
			"args": ["-y", "@three-ws/x402-mcp"],
			"env": {
				"SOLANA_SECRET_KEY": "<base58 secret of the wallet that holds USDC>",
				"SOLANA_RPC_URL": "https://your-rpc-provider",
				"MAX_PAY_USD": "1"
			}
		}
	}
}

SOLANA_SECRET_KEY is only needed to spend (pay_and_call, and x402_wallet defaulting to your wallet). find_services and inspect_endpoint work with no key.

Tools

Tool	Type	What it does
x402_wallet	read-only	A wallet's address + live SOL/USDC balance. Defaults to your signer wallet — confirm funds before paying.
find_services	read-only	Search the live x402 bazaar (PayAI + Coinbase CDP) for paid HTTP/MCP services with prices.
inspect_endpoint	read-only	Read any endpoint's 402 payment requirements (scheme, network, asset, price, pay-to) without paying.
pay_and_call	execution	Pay an x402 endpoint in USDC from your Solana key and return its result. Bounded by MAX_PAY_USD.
spending_report	read-only	Totals of everything pay_and_call and the named tools below have paid, by merchant and by day.

Plus 17 named tools, one per fixed three.ws x402 service, each cheaper for a model to call correctly than composing a raw pay_and_call(url):

Tool	Price	Endpoint
weather_forecast	$0.001	/api/x402/weather-guard-forecast
weather_go_no_go	$0.002	/api/x402/weather-guard-decision
carbon_now	$0.001	/api/x402/carbon-now
carbon_best_window	$0.002	/api/x402/carbon-best-window
domain_rdap_check	$0.001	/api/x402/domains-check
domain_rdap_check_bulk	$0.005	/api/x402/domains-bulk
research_search	$0.002	/api/x402/research-search
research_paper	$0.003	/api/x402/research-paper
research_bibliography	$0.005	/api/x402/research-bibliography
book_search	$0.001	/api/x402/books-search
book_read	$0.01	/api/x402/books-read
news_wire_search	$0.003	/api/x402/news-wire-query
news_wire_poll	$0.002	/api/x402/news-wire-pulse
transit_plan	$0.002	/api/x402/transit-plan
transit_delays	$0.001	/api/x402/transit-delays
places_search	$0.002	/api/x402/places-search
places_detail	$0.002	/api/x402/places-detail

Each takes the same arguments as its endpoint (see src/tools.json for the full schemas) and pays with the same SOLANA_SECRET_KEY / session_token settlement modes as pay_and_call, gated by the same MAX_PAY_USD cap and REQUIRE_CONFIRM flag. Prefer a named tool over pay_and_call whenever one exists for the endpoint you need: the fixed schema and stated price make the model far less likely to misdial the call.

Safety

pay_and_call carries destructiveHint: true, so annotation-aware clients (Claude Code, Claude Desktop, Cursor) prompt before running it. Beyond the client hint, every payment is bounded server-side: it probes the 402 first and refuses if the price exceeds max_usd or MAX_PAY_USD (default $1) before any money moves, and with REQUIRE_CONFIRM on (default) the call refuses until re-issued with confirm: true. Only the Solana (solana:*) exact-scheme requirement is settled — with the key you control.

Input parameters

x402_wallet — address (optional base58; defaults to the signer wallet).

find_services — query (required), type (http | mcp, default http), network (CAIP-2 filter), max_price_usdc, limit (1–100).

inspect_endpoint — url (required), method (GET | POST), body (object).

pay_and_call: url (required), method (GET | POST), body (object), max_usd (lowers the cap for this call), secret (per-call signer override), confirm (must be true when REQUIRE_CONFIRM is on), session_token, token, idempotency_key.

It has two settlement modes:

• Self-custodial (default). Signs with SOLANA_SECRET_KEY, or the per-call secret. You hold the key.
• Session-governed. Pass session_token, a three.ws Payment Session token, and the platform wallet signs on your behalf while enforcing that session's budget, host allowlist, and per-transaction cap. No private key needed. Solana USDC and Base USDC sessions are both supported, and secret and token are ignored in this mode.

token selects the settlement asset: usdc (default), or three for the $THREE platform token when the endpoint advertises it. idempotency_key deduplicates a call, which is recommended with session_token so a retry cannot double-charge.

Example

// inspect_endpoint — what does it cost? (no payment)
> { "url": "https://three.ws/api/x402/vanity?prefix=ab" }
{
  "ok": true, "paid": true,
  "accepts": [
    { "scheme": "exact", "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "asset": "EPjFW…", "price": 50000 }
  ],
  "payable_with_this_wallet": true
}

// pay_and_call — confirm:true required by default
> { "url": "https://three.ws/api/x402/vanity?prefix=ab", "confirm": true }
{ "ok": true, "paid": true, "payer": "Gx5E…", "price_usd": 0.05, "settlement": { … }, "result": { … } }

Examples

Runnable, no-payment examples live in examples/:

node examples/list-tools.mjs      # every tool with its full input schema
node examples/inspect-price.mjs   # find_services + inspect_endpoint on live data

Both spawn this server over stdio and hit the real bazaar. Neither reads a key or calls pay_and_call, so nothing is signed and nothing is spent. See examples/README.md for expected output.

Protocol versions

pay_and_call speaks both x402 wire formats on the same Solana key: v2 (CAIP-2 network strings, e.g. solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp) and v1 (flat network strings, e.g. solana), the format most of the open x402 bazaar, and services built on the original x402/x402-fetch packages, still speak. When a seller advertises both, v2 is always preferred. Settlement receipts come back in the same shape (success, transaction, network, payer) regardless of which version paid, so nothing downstream needs to know which one was used.

Requirements

• Node.js >= 20.
• A Solana mainnet RPC endpoint (https; only http://localhost is allowed for dev). Public cluster works for reads; bring your own for payment traffic.
• To pay: a Solana wallet holding USDC, as a base58 SOLANA_SECRET_KEY (or per-call secret).

Environment variables

Variable	Required	Default
SOLANA_SECRET_KEY	to pay only	—
SOLANA_RPC_URL	no	https://api.mainnet-beta.solana.com
MAX_PAY_USD	no	1
REQUIRE_CONFIRM	no	true
THREE_WS_BASE	no	https://three.ws
X402_MCP_LEDGER_PATH	no	~/.three-ws/x402-mcp-ledger.jsonl

X402_MCP_LEDGER_PATH points at the append-only JSON-lines file every settled payment (pay_and_call and the named tools) is recorded to; spending_report reads it back.

Links

• Homepage: https://three.ws
• MCP catalog: https://three.ws/docs/mcp
• Changelog: https://three.ws/changelog
• Issues: https://github.com/nirholas/three.ws/issues
• License: Apache-2.0, see LICENSE

---

_{Part of the three.ws SDK suite — 3D AI agents, on-chain identity, and agent payments.
Website · Changelog · GitHub}