xgate-server

用途

xgate-server 用于查询 xgate-server API，主要面向三类数据：X402 服务、ERC-8004 智能体（agents）以及链上代币转账记录。它既提供命令行工具（CLI），也提供 MCP 连接方式，让 Claude 等客户端可以直接调用 x402 API。

主要能力

健康检查：确认服务可用性。
服务查询：按关键词、网络、资产、scheme、X402 版本、最大金额等条件搜索服务，支持分页与调试诊断。
智能体查询：按关键词、链 ID、协议（MCP、A2A）、身份注册表、钱包地址、元数据、信任类型、MCP 版本与能力、A2A 技能与接口、验证状态、最低声誉分等条件搜索智能体。
转账查询：按 facilitator、链 ID、代币合约、来源/目标地址、区块范围、时间戳等条件查询代币转账，支持游标分页与总额统计。
MCP 集成：将 xgate 接入 Claude，使智能体能够搜索资源、添加 x402 API 工具并直接调用，支付通过服务器钱包自动结算。

使用方式

MCP 设置

MCP 连接需要人工完成认证，智能体无法自行生成连接 URL（需要钱包签名）。步骤：

前往 xgate.run 连接钱包，生成 MCP 连接 URL。
将 URL 添加到 Claude 配置。

Claude Code：

claude mcp add xgate --transport http https://xgate.run/user/<walletSlug>/mcp?token=<token>

Claude Desktop（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "xgate": {
      "url": "https://xgate.run/user/<walletSlug>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

连接后，智能体可以：

搜索资源：调用 xgate_search({ query: "weather" })
添加工具：调用 xgate_add_resource({ url: "..." }) 将 x402 API 加入工具集
使用工具：直接调用发现的 API，支付通过服务器钱包自动结算

如果 MCP 工具不可用，需提示人工先完成认证。

CLI 用法

使用打包的 CLI：plugins/xgate-server/scripts/xgate

# 健康检查
./plugins/xgate-server/scripts/xgate health

# 搜索服务
./plugins/xgate-server/scripts/xgate services -q "token" -n ethereum

# 获取特定服务
./plugins/xgate-server/scripts/xgate service SERVICE_ID

# 搜索智能体
./plugins/xgate-server/scripts/xgate agents -p MCP --min-score 0.8

# 查询代币转账
./plugins/xgate-server/scripts/xgate transfers -c 8453 --totals

# 资源转账
./plugins/xgate-server/scripts/xgate resource-transfers 0xADDRESS -c 1

运行 ./plugins/xgate-server/scripts/xgate --help 查看完整选项。

API 基础地址

https://api.xgate.run，可通过 XGATE_URL 环境变量覆盖。

查询参数

服务查询参数

参数	类型	说明
q	string	自由文本搜索
network	string	逗号分隔的网络（ethereum、base、polygon）
asset	string	逗号分隔的资产（USDC、ETH）
scheme	string	服务 scheme 过滤
version	number	X402 版本过滤
maxAmount	bigint	最大所需金额
limit	number	每页结果数（1-50，默认 10）
offset	number	分页偏移
debug	boolean	返回评分诊断

智能体查询参数

参数	类型	说明
q	string	自由文本搜索
chain_id	number	区块链链 ID
protocols	string	逗号分隔（MCP、A2A）
identity_registry	string	身份注册表地址
agent_id	string	特定智能体 ID
wallet	string	钱包地址
has_metadata	boolean	按元数据存在过滤
supported_trust	string	逗号分隔的信任类型
mcp_version	string	MCP 协议版本
mcp_capabilities	string	逗号分隔的能力
a2a_skills	string	逗号分隔的 A2A 技能
a2a_interfaces	string	逗号分隔的接口
validation_status	enum	pending、completed、expired、revoked
min_score	number	最低声誉分（0-1）
min_confidence	number	最低置信度阈值
min_pass_rate	number	最低验证通过率
limit	number	每页结果数（1-50）
offset	number	分页偏移
debug	boolean	返回排名明细

转账查询参数

参数	类型	说明
facilitator_id	string	Facilitator 标识
chain_id	number	区块链链 ID
token_contract	string	代币合约地址（0x）
from_address	string	来源地址（0x）
to_address	string	目标地址（0x）
wallet_address	string	钱包地址过滤
block_number_from	number	起始区块
block_number_to	number	结束区块
block_timestamp_from	string	ISO 时间戳
block_timestamp_to	string	ISO 时间戳
limit	number	结果数量限制
cursor	string	分页游标
order	enum	asc 或 desc
include_totals	boolean	包含金额总额

响应格式

服务响应示例：

{
  "query": {},
  "total": 42,
  "results": [
    {
      "id": "service_id",
      "resource": "0x...",
      "type": "http",
      "networks": ["ethereum"],
      "assets": ["USDC"],
      "score": 0.95
    }
  ],
  "diagnostics": { "latencyMs": 125 }
}

智能体响应示例：

{
  "query": {},
  "total": 25,
  "results": [
    {
      "agentKey": "key",
      "agentId": "0x...",
      "name": "Agent Name",
      "protocols": ["MCP", "A2A"],
      "reputationScore": 0.95,
      "rankScore": 87.5
    }
  ]
}

错误处理

状态码	含义
400	无效查询参数
401	未授权（缺少/无效 x-internal-key）
404	资源未找到
503	搜索引擎不可用
500	内部服务器错误

链 ID

链	ID
Ethereum Mainnet	1
Base	8453
Sepolia	11155111
Polygon	137

适用场景

查找支持 MCP 的智能体。
搜索 xgate 上的服务或资源。
查询某地址的代币转账记录。
将 x402 工具接入 Claude 并通过 MCP 调用。

限制与提示

MCP 认证必须由人工完成，智能体无法生成连接 URL。
若查询失败，可先运行 xgate health 检查服务状态。
使用 --debug 标志（或 debug=true）了解评分/排名逻辑。
大结果集使用分页：转账为游标分页，服务/智能体为偏移分页。
可将输出通过 jq 过滤器提取特定字段。