This server turns any AI agent into an autonomous x402 buyer, capable of discovering, inspecting, and paying for services on the x402 network using USDC on Solana — with a self-custodial wallet or a session token.
x402_wallet: View any Solana wallet's address and its live SOL and USDC balances. Defaults to the configured signer wallet.
find_services: Search the live x402 bazaar (PayAI + Coinbase CDP) for paid HTTP APIs and MCP tools. Filter by query, service type, network (CAIP-2), and maximum USDC price.
inspect_endpoint: Probe any x402 endpoint to read its full payment requirements (scheme, network, asset, price, pay-to address) without spending any money. Returns the result directly if the endpoint is free.
pay_and_call: Pay an x402 endpoint and retrieve its result in one step. Supports:
Self-custodial mode: Signs with your own SOLANA_SECRET_KEY or a per-call secret key.
Session-governed mode: Uses a three.ws Payment Session token (pss_…) so the platform wallet signs on your behalf — no private key required.
Payment in USDC (default) or $THREE (if the endpoint supports it).
Built-in safety guards: price cap (MAX_PAY_USD, default $1), confirmation requirement (REQUIRE_CONFIRM), pre-flight 402 probe before payment, and idempotency key support to avoid double-charges.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@x402-mcp search for affordable text-to-speech APIs"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_callany 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.
npm install @three-ws/x402-mcpOr run with npx:
SOLANA_SECRET_KEY=<base58> npx @three-ws/x402-mcpRelated MCP server: BotWallet MCP Server
Claude Code, one line:
claude mcp add x402 --env SOLANA_SECRET_KEY=<base58> -- npx -y @three-ws/x402-mcpClaude 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.
Tool | Type | What it does |
| read-only | A wallet's address + live SOL/USDC balance. Defaults to your signer wallet — confirm funds before paying. |
| read-only | Search the live x402 bazaar (PayAI + Coinbase CDP) for paid HTTP/MCP services with prices. |
| read-only | Read any endpoint's 402 payment requirements (scheme, network, asset, price, pay-to) without paying. |
| execution | Pay an x402 endpoint in USDC from your Solana key and return its result. Bounded by |
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.
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).
// 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": { … } }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).
Variable | Required | Default |
| to pay only | — |
| no |
|
| no |
|
| no |
|
| no |
|
Homepage: https://three.ws
MCP catalog: https://three.ws/docs/mcp
Changelog: https://three.ws/changelog
License: Apache-2.0 — see LICENSE
All rights reserved. See LICENSE.
Search the live x402 facilitator network (PayAI + Coinbase CDP bazaar) for paid services — HTTP APIs and MCP tools. Returns each match with its price, networks, and resource URL. Pass a resource into pay_and_call to use it. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Service kind to search. | http |
| limit | No | Max results (default 25). | |
| query | Yes | What you need, e.g. "weather", "image upscale", "token intel". | |
| network | No | CAIP-2 network filter, e.g. "solana:*" or "eip155:8453". | |
| max_price_usdc | No | Only return services at or under this USDC price. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=true, covering safety and dynamic results. The description reinforces read-only behavior and adds context about the live network search, but doesn't disclose additional behavioral traits beyond what annotations offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no wasted words. The first sentence immediately states the core action, and subsequent sentences add essential context on workflow and safety.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, 1 required, and no output schema, the description provides a high-level overview of returns but lacks detail on result structure (e.g., field names, array format). It's adequate but not fully complete for invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description doesn't add new semantic details about parameters beyond what the schema provides. It mentions output fields but not parameter specifics, so it barely meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches a live network for paid services (HTTP APIs and MCP tools). It specifies the return fields (price, networks, resource URL) and distinguishes from siblings like pay_and_call (for using services) and inspect_endpoint (likely for inspection).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells agents to pass a resource into pay_and_call to use it, providing clear context on when to use this tool versus its sibling. It also marks the tool as read-only, though it doesn't explicitly exclude alternative scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch an x402 endpoint and return its 402 payment requirements — every accepted scheme, network, asset, price and pay-to address — WITHOUT paying. If the endpoint is free, returns its result instead. No signer required. Use this to learn the cost before pay_and_call.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The x402 endpoint URL to inspect. | |
| body | No | JSON body for a POST probe. | |
| method | No | HTTP method to probe with. | GET |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavioral context beyond annotations: no signer required, returns result if free. Annotations include readOnlyHint=true and openWorldHint=true; description adds operational details without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with primary action. No redundant information. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters (all well-described), annotations, and no output schema, the description fully explains behavior, use case, and return types. Sufficient for correct agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. Description adds minimal extra meaning beyond schema (e.g., 'probe with' for method). Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly identifies the tool's action (fetch/inspect) and resource (x402 endpoint). Explicitly states it returns payment requirements without paying, distinguishing from sibling pay_and_call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use this to learn the cost before pay_and_call' and notes 'No signer required'. Provides clear context for when to use, though could further differentiate from find_services and x402_wallet.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call a paid x402 endpoint and settle the payment automatically, then return the result.
Two modes:
• Self-custodial (default): signs with SOLANA_SECRET_KEY or secret arg — you hold the key.
• Session-governed: pass session_token (a three.ws Payment Session token) — the platform wallet signs on your behalf; the session's budget, allowlist, and per-tx cap are enforced by the platform. No private key required. Supports Solana USDC and Base USDC sessions.
Pay in USDC (default) or, when the endpoint advertises it, in $THREE (set token:"three"). Bounded by max_usd and the MAX_PAY_USD cap; refuses before any money moves if the price is over the cap. With REQUIRE_CONFIRM on, the call refuses until re-issued with confirm:true.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The x402 endpoint to pay and call. | |
| body | No | JSON body for POST requests. | |
| token | No | Settlement token. "usdc" (default) or "three" — the $THREE platform token; the endpoint must advertise it. Ignored when session_token is set. | usdc |
| method | No | HTTP method. | GET |
| secret | No | Per-call base58 signer override (defaults to SOLANA_SECRET_KEY). Ignored when session_token is set. | |
| confirm | No | Must be true to execute when REQUIRE_CONFIRM is on. | |
| max_usd | No | Hard ceiling for THIS call in USD. Can only lower the MAX_PAY_USD cap, never raise it. | |
| session_token | No | three.ws Payment Session token (pss_…). When provided, the platform wallet pays — no local key needed. Overrides `secret`. | |
| idempotency_key | No | Deduplication key for this call. Recommended when using session_token to avoid double-charges on retries. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: automatic payment settlement, two signing modes, bounded by max_usd and MAX_PAY_USD cap, refusal before money moves if over cap, confirmation requirement, and token override behavior. Annotations (destructiveHint=true) are consistent, and the description adds context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (~150 words) and well-structured with clear separation of modes, tokens, and constraints. Every sentence adds value, and there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main aspects of a payment tool but lacks details on return value format (no output schema) and error handling (e.g., what happens if payment succeeds but endpoint fails). Idempotency key is described in schema but not emphasized in description. Some gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds some context (e.g., session_token overrides secret, token ignored when session_token, max_usd bounded by cap), but most parameter meaning is already clear from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calls a paid x402 endpoint, settles payment, and returns the result. It distinguishes itself from sibling tools (find_services, inspect_endpoint, x402_wallet) which are about finding, inspecting, or managing wallets, not executing paid calls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use self-custodial vs session-governed modes, which token to pay with (USDC or $THREE), and mentions caps and confirmation. However, it does not explicitly compare to sibling tools or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show a Solana wallet's address and live SOL + USDC balance. With no address, derives the wallet from the configured signer (SOLANA_SECRET_KEY) — call this before pay_and_call to confirm there's USDC to spend. Read-only; never moves funds.
| Name | Required | Description | Default |
|---|---|---|---|
| address | No | Base58 Solana address to inspect. Omit to use the configured signer wallet. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations: explains real-time balance, signer derivation, and explicitly states 'never moves funds'. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. Front-loaded with purpose, then usage guidance. Highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description covers return values (address and balance), usage options, and when to invoke. Complete for a simple read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with a description for the 'address' parameter. The description reinforces the behavior of omitting address to use the configured signer, which is helpful for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Show a Solana wallet's address and live SOL + USDC balance' with a specific verb and resource. It distinguishes itself from siblings like pay_and_call, find_services, and inspect_endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises calling this before pay_and_call to confirm USDC balance, and explains derivation from signer when no address is provided. Also clarifies it is read-only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.2.0find_servicesinspect_endpointpay_and_callx402_walletEach tool has a distinct, non-overlapping purpose: searching services, inspecting costs, paying and calling, and checking wallet balance. No ambiguity.
All tool names follow a consistent verb_noun snake_case pattern (find_services, inspect_endpoint, pay_and_call, x402_wallet), making them predictable and easy to understand.
Four tools is an ideal count for this focused domain—covering discovery, inspection, execution, and wallet status without bloat or deficiency.
The tool set covers the core payment workflow comprehensively, but lacks session management or history features, which are minor gaps for advanced use cases.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Wallet-signed Solana RPC for AI agents. No API keys, LLM-safe amounts, pay-per-call in SOL.
AI service marketplace — agents discover, call, and pay for API services automatically.
Native Solana staking for AI agents. 26 MCP tools, one-shot signing, webhooks.
Discover and pay for APIs with USDC credits. No wallet, no gas, MCP-native marketplace.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/nirholas/x402-payments-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server