x402 Bazaar Skill
The x402 Bazaar is the discovery layer for the x402 ecosystem — a
machine-readable catalog helping AI agents find and integrate with x402-compatible
API endpoints and MCP tools. Query, find, pay, and use with no pre-baked
integrations.
Two modes:
- - Browse only — no wallet needed, zero cost, discover all available services
- Browse + Pay — requires Base wallet with USDC to call discovered endpoints
Prerequisites
Browse only (no keys needed)
CODEBLOCK0
To call paid endpoints
- 1. Get a Base wallet private key (MetaMask → export, or Coinbase Wallet)
- Fund with USDC on Base — get from coinbase.com or bridge.base.org
- Add to
.env:
CODEBLOCK1
Install dependencies (run once)
pip install -r ~/clawd/skills/x402-bazaar/requirements.txt
When to Activate This Skill
Activate when user says any of:
Discovery
- - "What x402 services are available?"
- "Find me an API for [task] on x402"
- "Browse the x402 Bazaar"
- "What services cost less than $0.01?"
- "Find a weather API I can pay per call"
- "What MCP tools are on x402?"
- "Show me x402 services under [price]"
- "Search x402 for [keyword]"
Paying for services
- - "Call this x402 endpoint: [url]"
- "Pay for and call [service name]"
- "Use x402 to get [data] — find and pay the cheapest service"
- "Make a paid x402 request to [url]"
Do NOT activate for:
- - Checking agent's own wallet balance → use /agent-wallet skill
- Listing on the Bazaar as a seller → manual setup, see seller section below
- Alpaca or stock trading → use /alpaca-trading skill
Exact Commands
List all available services
CODEBLOCK3
Search by keyword
CODEBLOCK4
Filter by max price
CODEBLOCK5
Filter by type
CODEBLOCK6
Inspect a specific service
CODEBLOCK7
Call a discovered service (requires EVMPRIVATEKEY + USDC)
CODEBLOCK8
Full autonomous flow: find + pay + use
python3 agent.py "find the cheapest weather API and get weather for London"
python3 agent.py "find a web scraping API and scrape https://example.com"
How x402 Payment Works
- 1. Agent discovers a service from the Bazaar catalog
- Calls the endpoint — gets HTTP 402 Payment Required response
- Reads payment requirements from the 402 response headers
- Pays via facilitator using USDC on Base
- Retries the exact same request with payment proof header
- Service verifies proof and returns paid result
No accounts, no subscriptions, no API keys — just USDC per request.
MCP Integration
This skill can be integrated with Model Context Protocol (MCP) servers to enable
Claude Desktop and other MCP clients to autonomously pay for and use x402 APIs.
See the full MCP integration guide: x402-MCP.md
Key capabilities:
- - Expose x402 services as MCP tools in Claude Desktop
- Automatic payment handling when Claude calls an API
- Support for both EVM (Base) and Solana networks
- No manual payment steps — fully autonomous
Example: Claude can discover weather APIs via this skill, then call them via MCP
with automatic USDC micropayments on Base.
Facilitators Queried
| Facilitator | Discovery URL | Notes |
|---|
| Coinbase CDP | INLINECODE1 | Largest catalog, default |
| PayAI |
facilitator.payai.network/discovery/resources | Alternative catalog |
Both are queried and merged when you run "list services".
Output Format
Service list:
CODEBLOCK10
Paid call result:
💸 x402 Payment Executed
Endpoint: https://api.weather-x402.com/current
Paid: $0.001 USDC
Network: Base (eip155:8453)
TxHash: 0xabc123...
Status: 200 OK
📦 Response:
{"temperature": 72, "conditions": "sunny", "humidity": 45}
Spending Limits
Default max spend per call is $0.10 USDC. Set in .env:
CODEBLOCK12
The skill refuses any call where maxAmountRequired exceeds this limit
and asks the user to confirm before proceeding.
Error Handling
| Error | Cause | Fix |
|---|
| INLINECODE4 | Missing .env key | Add key to .env (only needed for paid calls) |
| INLINECODE5 |
Wallet underfunded | Bridge USDC to Base at bridge.base.org |
|
Spend limit exceeded | Service costs more than MAX
SPENDPER_CALL | Raise limit in .env or confirm manually |
|
402 verification failed | Facilitator rejected payment | Retry or switch facilitator |
|
No services found | Empty Bazaar result | Broaden search or try again later |
|
Network mismatch | Service on unsupported chain | Filter by network eip155:8453 |
Supported Networks (v1.0)
- - Base mainnet: eip155:8453 (real USDC)
- Base Sepolia: eip155:84532 (test USDC — use for testing)
Solana support planned for v1.1.
Listing Your Own API (Sellers)
To list your x402 API on the Bazaar (v2 spec-compliant):
- 1. Add
bazaarResourceServerExtension to your x402 resource server - Use
declareDiscoveryExtension() in your route configuration - Set
maxAmountRequired in your accepts[] entries (replaces v1 amount field) - Listing is free — services set their own per-call price
The v2 discovery API returns:
CODEBLOCK13
Note: This skill handles both v1 (flat list) and v2 (wrapped response) for resilience.
MCP tool uniqueness: For MCP servers, uniqueness is determined by (resource_url, tool_name),
not just the URL, since one MCP server can host multiple tools.
Full seller guide: docs.cdp.coinbase.com/x402/bazaar
x402 Bazaar 技能
x402 Bazaar 是 x402 生态系统的发现层——一个机器可读的目录，帮助 AI 代理发现并集成兼容 x402 的 API 端点和 MCP 工具。无需预先集成即可查询、发现、支付和使用。
两种模式：
- - 仅浏览 — 无需钱包，零成本，发现所有可用服务
- 浏览 + 支付 — 需要持有 USDC 的 Base 钱包来调用已发现的端点
前置条件
仅浏览（无需密钥）
bash
python3 agent.py list services
python3 agent.py find weather APIs
调用付费端点
- 1. 获取 Base 钱包私钥（MetaMask → 导出，或 Coinbase 钱包）
- 在 Base 上存入 USDC — 从 coinbase.com 或 bridge.base.org 获取
- 添加到 .env：
EVMPRIVATEKEY=0xYourPrivateKeyHere
MAXSPENDPER_CALL=0.10
安装依赖（运行一次）
bash
pip install -r ~/clawd/skills/x402-bazaar/requirements.txt
何时激活此技能
当用户说出以下任何内容时激活：
发现
- - 有哪些 x402 服务可用？
- 帮我找一个用于 [任务] 的 x402 API
- 浏览 x402 Bazaar
- 哪些服务价格低于 $0.01？
- 找一个按次付费的天气 API
- x402 上有哪些 MCP 工具？
- 显示价格低于 [价格] 的 x402 服务
- 在 x402 上搜索 [关键词]
支付服务
- - 调用这个 x402 端点：[url]
- 支付并调用 [服务名称]
- 使用 x402 获取 [数据] — 找到并支付最便宜的服务
- 向 [url] 发起付费的 x402 请求
不要激活的情况：
- - 检查代理自身钱包余额 → 使用 /agent-wallet 技能
- 在 Bazaar 上作为卖家发布 → 手动设置，见下方卖家部分
- Alpaca 或股票交易 → 使用 /alpaca-trading 技能
精确命令
列出所有可用服务
bash
cd ~/clawd/skills/x402-bazaar && python3 agent.py list services
按关键词搜索
bash
python3 agent.py find weather
python3 agent.py search for AI inference
python3 agent.py find web scraping services
按最高价格筛选
bash
python3 agent.py services under 0.01
python3 agent.py services under 0.001 USDC
按类型筛选
bash
python3 agent.py list http services
python3 agent.py list mcp tools
检查特定服务
bash
python3 agent.py inspect https://api.example.com/x402/weather
调用已发现的服务（需要 EVMPRIVATEKEY + USDC）
bash
python3 agent.py call https://api.example.com/x402/weather?location=NYC
python3 agent.py pay and call https://api.example.com/x402/sentiment
全自动流程：发现 + 支付 + 使用
bash
python3 agent.py find the cheapest weather API and get weather for London
python3 agent.py find a web scraping API and scrape https://example.com
x402 支付工作原理
- 1. 代理从 Bazaar 目录中发现服务
- 调用端点 — 收到 HTTP 402 Payment Required 响应
- 从 402 响应头中读取支付要求
- 通过促进器使用 Base 上的 USDC 进行支付
- 使用支付证明头重试完全相同的请求
- 服务验证证明并返回付费结果
无需账户、无需订阅、无需 API 密钥——只需按请求支付 USDC。
MCP 集成
此技能可与 模型上下文协议（MCP） 服务器集成，使 Claude Desktop 和其他 MCP 客户端能够自主支付并使用 x402 API。
查看完整的 MCP 集成指南： x402-MCP.md
关键能力：
- - 在 Claude Desktop 中将 x402 服务暴露为 MCP 工具
- Claude 调用 API 时自动处理支付
- 支持 EVM（Base）和 Solana 网络
- 无需手动支付步骤 — 完全自主
示例：Claude 可以通过此技能发现天气 API，然后通过 MCP 调用它们，在 Base 上自动进行 USDC 微支付。
查询的促进器
| 促进器 | 发现 URL | 备注 |
|---|
| Coinbase CDP | api.cdp.coinbase.com/platform/v2/x402/discovery/resources | 最大目录，默认 |
| PayAI |
facilitator.payai.network/discovery/resources | 备选目录 |
运行 list services 时会查询并合并两者。
输出格式
服务列表：
🛒 x402 Bazaar — 找到 42 个服务
1. 🌐 天气 API
URL: https://api.weather-x402.com/current
类型: http GET
价格: $0.001 USDC
网络: Base (eip155:8453)
更新: 2小时前
2. 🤖 Llama 3.3 70B 推理
URL: https://api.x402network.com/llm/llama
类型: http POST
价格: $0.005 USDC
网络: Base (eip155:8453)
更新: 4小时前
付费调用结果：
💸 x402 支付已执行
端点: https://api.weather-x402.com/current
支付: $0.001 USDC
网络: Base (eip155:8453)
交易哈希: 0xabc123...
状态: 200 OK
📦 响应：
{temperature: 72, conditions: sunny, humidity: 45}
消费限额
每次调用的默认最高消费为 $0.10 USDC。在 .env 中设置：
MAXSPENDPER_CALL=0.10
当 maxAmountRequired 超过此限额时，技能会拒绝任何调用，并在继续前要求用户确认。
错误处理
| 错误 | 原因 | 修复 |
|---|
| EVMPRIVATEKEY not set | 缺少 .env 密钥 | 将密钥添加到 .env（仅付费调用需要） |
| Insufficient USDC balance |
钱包资金不足 | 在 bridge.base.org 将 USDC 桥接到 Base |
| Spend limit exceeded | 服务费用超过 MAX
SPENDPER_CALL | 在 .env 中提高限额或手动确认 |
| 402 verification failed | 促进器拒绝支付 | 重试或切换促进器 |
| No services found | Bazaar 结果为空 | 扩大搜索范围或稍后重试 |
| Network mismatch | 服务在不支持的链上 | 按网络 eip155:8453 筛选 |
支持的网络（v1.0）
- - Base 主网：eip155:8453（真实 USDC）
- Base Sepolia：eip155:84532（测试 USDC — 用于测试）
Solana 支持计划在 v1.1 中推出。
发布你自己的 API（卖家）
要在 Bazaar 上发布你的 x402 API（符合 v2 规范）：
- 1. 将 bazaarResourceServerExtension 添加到你的 x402 资源服务器
- 在路由配置中使用 declareDiscoveryExtension()
- 在 accepts[] 条目中设置 maxAmountRequired（替代 v1 的 amount 字段）
- 发布免费 — 服务自行设置每次调用的价格
v2 发现 API 返回：
json
{
x402Version: 2,
items: [...],
pagination: {...}
}
注意： 此技能同时处理 v1（扁平列表）和 v2（包装响应）以保证健壮性。
MCP 工具唯一性： 对于 MCP 服务器，唯一性由 (resourceurl, toolname) 决定，而不仅仅是 URL，因为一个 MCP 服务器可以托管多个工具。
完整卖家指南：docs.cdp.coinbase.com/x402/bazaar
