ERC-8004 Agent 注册与声誉服务

概述

x402 Facilitator 提供了基于 ERC-8004 标准的 AI Agent 注册与声誉服务，帮助您：

• 发现 AI Agent：查询已注册到指定网络的 AI Agent
• 验证 Agent 身份：获取 Agent 的链上身份信息和元数据
• 查询 Agent 声誉：查看 Agent 的服务质量评分和用户反馈
• 提交服务反馈：将使用 AI Agent 的体验反馈到链上

核心功能

1. Agent 查询与发现

查询已注册的 AI Agent，支持多种筛选条件：

• 按链 ID 筛选
• 按所有者地址筛选
• 按 x402 支持筛选
• 分页查询

返回信息：

• Agent 基础信息（名称、描述、图标）
• Agent 元数据（服务类型、端点、能力）
• Agent 声誉评分（总反馈数、平均分、标签分解）
• x402 支持状态

2. Agent 声誉查询

查看 Agent 的服务质量数据：

• 总反馈数量
• 平均评分
• 按标签分类的评分
• 综合评分（包含参与度、服务质量、发布者信誉、合规性、活跃度）

3. 服务反馈提交

将使用 AI Agent 的体验反馈提交到链上：

• 关联交易哈希
• 评分（支持自定义精度）
• 标签分类（如 "x402"、"success"）
• 服务端点信息

4. Agent 缓存管理

• 手动刷新 Agent 数据缓存
• 查询反馈提交状态
• 声誉缓存同步

---

API 接口

基础信息

Base URL: http://api-x402.gatenode.cc

统一响应格式:

{
  "code": 200,
  "msg": "",
  "data": {...},
  "timestamp": 1705651200
}

---

1. 查询 Agent 列表

接口: POST /v1/erc8004/agents/query

请求参数:

参数	类型	必填	说明
chainId	string	是	链 ID（EIP-155 格式），如 "eip155:1"
agentId	uint64	否	特定 Agent ID
owner	string	否	所有者地址
x402Support	boolean	否	是否支持 x402
limit	int	否	分页大小，默认 20，最大 100
offset	int	否	分页偏移量，默认 0

请求示例:

{
  "chainId": "eip155:1",
  "x402Support": true,
  "limit": 10,
  "offset": 0
}

响应示例:

{
  "code": 200,
  "msg": "",
  "data": {
    "agents": [
      {
        "agentId": 123,
        "chainId": "eip155:1",
        "owner": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "tokenURI": "ipfs://Qm...",
        "metadata": {
          "type": "Agent",
          "name": "Data Analysis AI",
          "description": "专业的数据分析 AI 助手",
          "image": "https://example.com/image.png",
          "services": [
            {
              "name": "Web Service",
              "type": "web",
              "endpoint": "https://api.example.com/analyze",
              "version": "2025-01-15"
            }
          ],
          "x402Support": true
        },
        "x402Support": true,
        "reputation": {
          "totalFeedbacks": 150,
          "averageScore": "85",
          "scoreDecimals": 0,
          "tagBreakdown": {
            "x402": {
              "count": 100,
              "value": "88",
              "decimals": 0
            }
          },
          "compositeScore": {
            "total": 85.5,
            "engagement": 90.0,
            "service": 88.0,
            "publisher": 85.0,
            "compliance": 82.0,
            "momentum": 80.0
          }
        },
        "lastSyncAt": "2026-04-09T12:00:00Z"
      }
    ],
    "total": 1,
    "limit": 10,
    "offset": 0
  },
  "timestamp": 1705651200
}

使用场景:

• 发现支持 x402 支付的 AI Agent
• 查找特定所有者的 Agent
• 筛选高评分的 Agent

---

2. 提交服务反馈

接口: POST /v1/erc8004/feedback/submit

请求参数:

参数	类型	必填	说明
chainId	string	是	链 ID（EIP-155 格式）
agentId	uint64	是	Agent ID
txHash	string	是	关联的交易哈希
fromAddress	string	是	付款方地址
toAddress	string	是	收款方地址（Agent 地址）
value	int64	是	反馈值（评分）
valueDecimals	uint8	是	反馈值精度（0-18）
tag1	string	是	主标签（如 "x402"）
tag2	string	否	副标签（如 "success"、"fast"）
endpoint	string	否	使用的服务端点 URL

请求示例:

{
  "chainId": "eip155:1",
  "agentId": 123,
  "txHash": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
  "fromAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "toAddress": "0x9be8Df37C788B244cFc28E46654aD5Ec28a880AF",
  "value": 85,
  "valueDecimals": 0,
  "tag1": "x402",
  "tag2": "success",
  "endpoint": "https://api.example.com/analyze"
}

响应示例:

{
  "code": 200,
  "msg": "",
  "data": {
    "success": true,
    "recordId": 456,
    "feedbackStatus": "pending",
    "message": "Feedback queued for submission"
  },
  "timestamp": 1705651200
}

使用场景:

• 完成支付后评价 Agent 服务
• 记录服务质量数据
• 帮助其他用户选择 Agent

注意:

• value 为正数表示正面反馈，负数表示负面反馈
• valueDecimals 控制评分精度，0 表示整数评分
• 反馈会异步提交到链上，状态会从 pending → submitted → confirmed

---

3. 查询反馈状态

接口: GET /v1/erc8004/feedback/status/{txHash}

路径参数:

• txHash: 提交反馈时关联的交易哈希

响应示例:

{
  "code": 200,
  "msg": "",
  "data": {
    "txHash": "0xabc123def456...",
    "feedbackStatus": "confirmed",
    "onChainTxHash": "0xxyz789abc123...",
    "feedbackIndex": 789,
    "confirmedAt": "2026-04-09T12:05:00Z",
    "errorMessage": null
  },
  "timestamp": 1705651200
}

状态说明:

• pending: 等待提交
• submitted: 已提交上链，等待确认
• confirmed: 已确认
• failed: 提交失败

---

4. 刷新 Agent 缓存

接口: POST /v1/erc8004/agents/refresh

查询参数:

• chainId（必填）: 链 ID
• agentId（必填）: Agent ID

请求示例:

curl -X POST "http://localhost:8080/v1/erc8004/agents/refresh?chainId=eip155:1&agentId=123"

响应示例:

{
  "code": 200,
  "msg": "",
  "data": {
    "success": true,
    "message": "Agent cache refreshed successfully"
  },
  "timestamp": 1705651200
}

使用场景:

• Agent 信息更新后立即同步
• 确保获取最新的 Agent 数据

---

接入指南

快速开始

1. 查询支持 x402 的 Agent

curl -X POST http://api-x402.gatenode.cc/v1/erc8004/agents/query \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": "eip155:1",
    "x402Support": true,
    "limit": 10
  }'

2. 提交服务反馈

完成 x402 支付后，提交反馈：

curl -X POST http://api-x402.gatenode.cc/v1/erc8004/feedback/submit \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": "eip155:1",
    "agentId": 123,
    "txHash": "0x交易哈希",
    "fromAddress": "0x您的地址",
    "toAddress": "0xAgent地址",
    "value": 90,
    "valueDecimals": 0,
    "tag1": "x402",
    "tag2": "excellent"
  }'

---

Agent 元数据说明

Metadata 结构

interface AgentMetadata {
  type: string; // 类型标识，通常为 "Agent"
  name: string; // Agent 名称
  description: string; // Agent 描述
  image: string; // Agent 图标 URL
  services: Service[]; // 服务列表
  registrations: Registration[]; // 链上注册信息
  x402Support: boolean; // 是否支持 x402 支付
}

interface Service {
  name: string; // 服务名称
  type: string; // 服务类型（web, MCP, OASF, A2A 等）
  endpoint: string; // 服务端点 URL
  version?: string; // 服务版本
  tools?: string[]; // 可用工具（MCP）
  capabilities?: string[]; // 服务能力
}

常见服务类型

类型	说明	示例端点
web	HTTP REST API	https://api.example.com/chat
MCP	Model Context Protocol	mcp://example.com/agent
OASF	Open Agent Service Framework	oas://example.com/analyze
A2A	Agent-to-Agent Protocol	a2a://0x123...@example.com

---

声誉评分说明

复合评分组成

interface CompositeScore {
  total: number; // 综合评分（总分）
  engagement: number; // 参与度（30%）
  service: number; // 服务质量（25%）
  publisher: number; // 发布者信誉（20%）
  compliance: number; // 合规性（15%）
  momentum: number; // 活跃度（10%）
}

评分参考

分数范围	评级	说明
90-100	优秀	服务质量极佳，强烈推荐
75-89	良好	服务质量较好，推荐使用
60-74	一般	服务质量一般，谨慎使用
< 60	较差	服务质量差，不推荐

---

最佳实践

1. 选择合适的 Agent

// 查询高评分、支持 x402 的 Agent
const agents = await queryAgents({
  chainId: 'eip155:1',
  x402Support: true,
  limit: 10,
});

// 按评分排序
const sortedAgents = agents.data.agents.sort(
  (a, b) => b.reputation.compositeScore.total - a.reputation.compositeScore.total,
);

// 选择评分最高的 Agent
const bestAgent = sortedAgents[0];

2. 完成支付后提交反馈

// 1. 完成支付
const paymentTxHash = await completeX402Payment(agent, amount);

// 2. 提交反馈（根据实际体验评分）
await submitFeedback({
  chainId: 'eip155:1',
  agentId: agent.agentId,
  txHash: paymentTxHash,
  value: 90, // 90分（满分100）
  tag1: 'x402',
  tag2: 'excellent',
});

3. 处理异步反馈提交

// 提交反馈是异步的，需要定期查询状态
async function waitForConfirmation(txHash: string) {
  while (true) {
    const status = await checkFeedbackStatus(txHash);

    if (status.feedbackStatus === 'confirmed') {
      console.log('反馈已确认上链');
      break;
    } else if (status.feedbackStatus === 'failed') {
      console.error('反馈提交失败:', status.errorMessage);
      break;
    }

    // 等待 10 秒后重试
    await new Promise((resolve) => setTimeout(resolve, 10000));
  }
}

---

错误处理

常见错误码

错误码	说明	解决方案
400	请求参数错误	检查请求参数格式和必填项
404	Agent 不存在	确认 agentId 正确，或刷新缓存
500	服务器内部错误	查看服务日志或联系技术支持

错误响应示例

{
  "code": 400,
  "msg": "Invalid request",
  "data": {
    "error": "chainId is required"
  },
  "timestamp": 1705651200
}

---

支持的区块链网络

注意: 请使用 EIP-155 格式的 chain ID（如 eip155:1），而不是纯数字（如 1）。

---

最后更新于2026/04/10