x402.direct — 服务目录

x402.direct API 是一个面向支持 x402 协议的服务的目录系统。它索引所有接受 x402 支付（HTTP 402 + 加密货币）的服务，并提供全文搜索、分类浏览及可信度评分功能。

基础 URL：https://x402.direct

端点列表

1. 搜索（需付费 —— $0.001，通过 x402 支付）

GET /api/search?q=

对所有已索引服务执行全文搜索。结果按文本相关性与可信度分数的加权综合得分排序。该接口受 x402 中间件保护：首次请求将返回 HTTP 402 状态码，需附带支付凭证后重发请求。

参数说明：

示例：

curl "https://x402.direct/api/search?q=weather+api&minScore=60&limit=5"

响应结构：

{
  "query": "weather api",
  "count": 3,
  "results": [
    {
      "id": 42,
      "resourceUrl": "https://example.com/api/weather",
      "description": "Real-time weather data for any location",
      "category": "weather",
      "provider": "example.com",
      "network": "base-mainnet",
      "price": "1000",
      "priceUsd": "0.001",
      "scoutScore": 85,
      "scoutVerdict": "safe",
      "relevance": 0.3214,
      "score": 58.11
    }
  ]
}

x402 支付流程：

1. 向 /api/search?q=... 发起 GET 请求，不携带任何支付头信息。
2. 服务器返回 HTTP 402 状态码，并在响应体中包含支付详情（金额、网络、收款地址 payTo、托管方 URL）。
3. 在 Base 主网上支付 $0.001 USDC（可通过 agent wallet 或 Coinbase Agentic Wallet 完成）。
4. 使用相同的请求参数重新发送请求，并在请求头中添加 X-402-Payment: 。
5. 服务器通过托管方验证支付有效性，随后返回搜索结果。

若使用支持 x402 的 HTTP 客户端（例如 x402 npm 包），支付过程将自动完成：

import { createX402Client } from "x402";
const client = createX402Client({ wallet: agentWallet });
const resp = await client.fetch("https://x402.direct/api/search?q=weather+api");

2. 浏览服务（免费）

GET /api/services

分页返回所有已索引服务的列表。无需支付费用。

参数说明：

示例：

# 评分最高的 AI 类服务
curl "https://x402.direct/api/services?category=ai&sort=score&limit=10"

# Base 主网上的最新服务
curl "https://x402.direct/api/services?network=base-mainnet&sort=newest"

# 仅返回高可信度服务
curl "https://x402.direct/api/services?minScore=70&sort=score"

响应结构：

{
  "services": [
    {
      "id": 1,
      "resourceUrl": "https://example.com/api/generate",
      "type": "x402",
      "description": "AI text generation endpoint",
      "category": "ai",
      "provider": "example.com",
      "network": "base-mainnet",
      "scheme": "exact",
      "price": "5000",
      "priceUsd": "0.005",
      "scoutScore": 92,
      "scoutVerdict": "safe",
      "lastSeen": "2025-05-01T12:00:00.000Z",
      "createdAt": "2025-04-15T08:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 127,
    "totalPages": 3
  }
}

3. 服务详情（免费）

GET /api/services/:id

返回单个服务的完整信息，包括支付选项、原始元数据以及托管方信息。

示例：

curl "https://x402.direct/api/services/42"

响应结构：

{
  "id": 42,
  "resourceUrl": "https://example.com/api/weather",
  "type": "x402",
  "x402Version": "1",
  "description": "Real-time weather data for any location",
  "mimeType": "application/json",
  "category": "weather",
  "provider": "example.com",
  "network": "base-mainnet",
  "scheme": "exact",
  "price": "1000",
  "priceUsd": "0.001",
  "payTo": "0xAbC123...",
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "scoutScore": 85,
  "scoutVerdict": "safe",
  "accepts": [{"scheme": "exact", "network": "base-mainnet", "maxAmountRequired": "1000", "asset": "..."}],
  "metadata": {"description": "...", "mimeType": "application/json"},
  "lastSeen": "2025-05-01T12:00:00.000Z",
  "lastUpdated": "2025-05-01T12:00:00.000Z",
  "createdAt": "2025-04-15T08:00:00.000Z",
  "facilitator": {
    "name": "x402.org",
    "url": "https://x402.org/facilitator",
    "facilitatorId": "x402-org-mainnet"
  }
}

4. 生态统计（免费）

GET /api/stats

返回目录系统的高层级统计数据，适用于仪表盘展示或快速了解当前生态规模。

示例：

curl "https://x402.direct/api/stats"

响应结构：

{
  "services": 247,
  "providers": 38,
  "categories": 12,
  "facilitators": 3,
  "avgScoutScore": 62,
  "networks": [
    { "network": "base-mainnet", "count": 180 },
    { "network": "base-sepolia", "count": 45 },
    { "network": "polygon", "count": 15 },
    { "network": "solana", "count": 7 }
  ]
}

筛选值参考

类别（Categories）： ai、image、weather、search、data、audio、video、developer、finance、language、storage、other

网络（Networks）： base-mainnet、base-sepolia、polygon、solana（随着生态发展可能新增更多网络）

排序选项（Sort options）： score（可信度分数，默认）、newest（创建时间）、price（价格由低到高）

可信度分数（ScoutScore）

每个服务均基于自动化可信信号进行 0–100 分评分：

• HTTPS 传输安全性
• 主网 vs 测试网部署状态
• 域名唯一性与服务提供方声誉
• 描述质量与文档完整性
• 定价合理性
• 收款地址有效性
• 是否使用自定义域名（而非通用托管平台）

判定结果（Verdicts）：

建议： 在搜索可用于生产环境的服务时，请设置 minScore=60 或更高；仅在探索或调试场景下才使用 minScore=0。

典型使用模式

为特定任务查找服务：

# Agent 需要图像生成能力
curl "https://x402.direct/api/services?category=image&sort=score&minScore=60&limit=5"

基于具体能力语义搜索（需付费）：

curl "https://x402.direct/api/search?q=text+to+speech&minScore=70" 
  -H "X-402-Payment: "

调用服务前获取完整详情：

# 从浏览或搜索中获得服务 ID 42，现获取其支付细节
curl "https://x402.direct/api/services/42"
# 使用其中的 payTo、asset、network 和 price 字段构造 x402 支付请求

检查生态健康状况：

curl "https://x402.direct/api/stats"

决策指南

当已知服务类别时，优先使用带筛选参数的 /api/services；当 Agent 需要在服务描述与提供方名称中进行语义或关键词匹配时，则使用 /api/search。