ERC-8004 Agent Registration and Reputation Service

Overview

The x402 Facilitator provides AI Agent registration and reputation services based on the ERC-8004 standard, helping you:

• Discover AI Agents: Query AI Agents registered on a specified network
• Verify Agent Identity: Retrieve an Agent's on-chain identity information and metadata
• Query Agent Reputation: View an Agent's service quality scores and user feedback
• Submit Service Feedback: Record your experience using an AI Agent on-chain

---

Core Features

1. Agent Discovery & Query

Query registered AI Agents with multiple filtering options:

• Filter by chain ID
• Filter by owner address
• Filter by x402 support
• Paginated queries

Returned information:

• Agent basic info (name, description, icon)
• Agent metadata (service type, endpoints, capabilities)
• Agent reputation score (total feedback count, average score, tag breakdown)
• x402 support status

2. Agent Reputation Query

View an Agent's service quality data:

• Total feedback count
• Average score
• Scores broken down by tag
• Composite score (includes engagement, service quality, publisher reputation, compliance, and momentum)

3. Service Feedback Submission

Submit your experience using an AI Agent on-chain:

• Link to a transaction hash
• Rating (supports custom precision)
• Tag classification (e.g., "x402", "success")
• Service endpoint information

4. Agent Cache Management

• Manually refresh Agent data cache
• Query feedback submission status
• Reputation cache synchronization

---

API Reference

Basic Information

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

Unified Response Format:

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

---

1. Query Agent List

Endpoint: POST /v1/erc8004/agents/query

Request Parameters:

Parameter	Type	Required	Description
chainId	string	Yes	Chain ID (EIP-155 format), e.g. "eip155:1"
agentId	uint64	No	Specific Agent ID
owner	string	No	Owner address
x402Support	boolean	No	Whether x402 is supported
limit	int	No	Page size, default 20, max 100
offset	int	No	Pagination offset, default 0

Request Example:

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

Response Example:

{
  "code": 200,
  "msg": "",
  "data": {
    "agents": [
      {
        "agentId": 123,
        "chainId": "eip155:1",
        "owner": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "tokenURI": "ipfs://Qm...",
        "metadata": {
          "type": "Agent",
          "name": "Data Analysis AI",
          "description": "A professional AI assistant for data analysis",
          "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
}

Use Cases:

• Discover AI Agents that support x402 payments
• Find Agents belonging to a specific owner
• Filter for high-rated Agents

---

2. Submit Service Feedback

Endpoint: POST /v1/erc8004/feedback/submit

Request Parameters:

Parameter	Type	Required	Description
chainId	string	Yes	Chain ID (EIP-155 format)
agentId	uint64	Yes	Agent ID
txHash	string	Yes	Associated transaction hash
fromAddress	string	Yes	Payer address
toAddress	string	Yes	Recipient address (Agent address)
value	int64	Yes	Feedback value (rating score)
valueDecimals	uint8	Yes	Precision of the feedback value (0–18)
tag1	string	Yes	Primary tag (e.g., "x402")
tag2	string	No	Secondary tag (e.g., "success", "fast")
endpoint	string	No	Service endpoint URL used

Request Example:

{
  "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"
}

Response Example:

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

Use Cases:

• Rate an Agent's service after completing a payment
• Record service quality data
• Help other users select Agents

Notes:

• A positive value indicates positive feedback; a negative value indicates negative feedback
• valueDecimals controls rating precision; 0 means integer scoring
• Feedback is submitted to the chain asynchronously; status transitions: pending → submitted → confirmed

---

3. Query Feedback Status

Endpoint: GET /v1/erc8004/feedback/status/{txHash}

Path Parameters:

• txHash: The transaction hash associated with the submitted feedback

Response Example:

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

Status Descriptions:

Status	Meaning
pending	Awaiting submission
submitted	Submitted on-chain, awaiting confirmation
confirmed	Confirmed on-chain
failed	Submission failed

---

4. Refresh Agent Cache

Endpoint: POST /v1/erc8004/agents/refresh

Query Parameters:

• chainId (required): Chain ID
• agentId (required): Agent ID

Request Example:

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

Response Example:

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

Use Cases:

• Sync immediately after Agent information is updated
• Ensure the latest Agent data is retrieved

---

Integration Guide

Quick Start

1. Query Agents that Support x402

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. Submit Service Feedback

After completing an x402 payment, submit feedback:

curl -X POST http://api-x402.gatenode.cc/v1/erc8004/feedback/submit \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": "eip155:1",
    "agentId": 123,
    "txHash": "0xYourTransactionHash",
    "fromAddress": "0xYourAddress",
    "toAddress": "0xAgentAddress",
    "value": 90,
    "valueDecimals": 0,
    "tag1": "x402",
    "tag2": "excellent"
  }'

---

Agent Metadata Reference

Metadata Structure

interface AgentMetadata {
  type: string; // Type identifier, typically "Agent"
  name: string; // Agent name
  description: string; // Agent description
  image: string; // Agent icon URL
  services: Service[]; // List of services
  registrations: Registration[]; // On-chain registration info
  x402Support: boolean; // Whether x402 payments are supported
}

interface Service {
  name: string; // Service name
  type: string; // Service type (web, MCP, OASF, A2A, etc.)
  endpoint: string; // Service endpoint URL
  version?: string; // Service version
  tools?: string[]; // Available tools (MCP)
  capabilities?: string[]; // Service capabilities
}

Common Service Types

Type	Description	Example Endpoint
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

---

Reputation Score Reference

Composite Score Breakdown

interface CompositeScore {
  total: number; // Overall composite score
  engagement: number; // Engagement (30%)
  service: number; // Service quality (25%)
  publisher: number; // Publisher reputation (20%)
  compliance: number; // Compliance (15%)
  momentum: number; // Activity / momentum (10%)
}

Score Tiers

Score Range	Rating	Description
90–100	Excellent	Outstanding service quality, strongly recommended
75–89	Good	Good service quality, recommended
60–74	Average	Acceptable quality, use with caution
< 60	Poor	Low quality, not recommended

---

Best Practices

1. Selecting the Right Agent

// Query high-rated Agents that support x402
const agents = await queryAgents({
  chainId: 'eip155:1',
  x402Support: true,
  limit: 10,
});

// Sort by composite score
const sortedAgents = agents.data.agents.sort(
  (a, b) => b.reputation.compositeScore.total - a.reputation.compositeScore.total,
);

// Select the top-rated Agent
const bestAgent = sortedAgents[0];

2. Submitting Feedback After Payment

// 1. Complete payment
const paymentTxHash = await completeX402Payment(agent, amount);

// 2. Submit feedback based on actual experience
await submitFeedback({
  chainId: 'eip155:1',
  agentId: agent.agentId,
  txHash: paymentTxHash,
  value: 90, // Score out of 100
  tag1: 'x402',
  tag2: 'excellent',
});

3. Handling Asynchronous Feedback Submission

// Feedback submission is asynchronous; poll for status periodically
async function waitForConfirmation(txHash: string) {
  while (true) {
    const status = await checkFeedbackStatus(txHash);

    if (status.feedbackStatus === 'confirmed') {
      console.log('Feedback confirmed on-chain');
      break;
    } else if (status.feedbackStatus === 'failed') {
      console.error('Feedback submission failed:', status.errorMessage);
      break;
    }

    // Wait 10 seconds before retrying
    await new Promise((resolve) => setTimeout(resolve, 10000));
  }
}

---

Error Handling

Common Error Codes

Error Code	Description	Resolution
400	Invalid request parameters	Check parameter format and required fields
404	Agent not found	Verify agentId is correct, or refresh the cache
500	Internal server error	Check service logs or contact technical support

Error Response Example

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

---

Supported Blockchain Networks

Note: Always use the EIP-155 chain ID format (e.g., eip155:1) rather than a plain integer (e.g., 1).

Last updated on 2026/04/10