### Agent Registration Metadata Example (JSON)

Source: https://github.com/erc-8004/best-practices/blob/main/Registration.md

An example of the JSON structure for registering an agent, including its type, name, description, and image URL. This metadata is crucial for first impressions on various platforms.

```json
{
  "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
  "name": "DataAnalyst Pro",
  "description": "A specialized AI agent that performs advanced data analysis, chart generation, and automated reporting. Ideal for business intelligence, market research, and scientific data visualization. Supports CSV, JSON, and SQL databases. Pricing examples (per call): analyzeDataset() https://api.dataanalyst-pro.com/v1/analyze-dataset @ 0.0008 ETH, generateChart() https://api.dataanalyst-pro.com/v1/generate-chart @ 0.0005 ETH, createReport() https://api.dataanalyst-pro.com/v1/create-report @ 0.0015 ETH. Monthly subscription available.",
  "image": "https://cdn.example.com/dataanalyst-pro.png"
}
```

--------------------------------

### Get Clients (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Retrieves a list of all client addresses associated with a given agent ID.

```solidity
function getClients(uint256 agentId) external view returns (address[] memory)
```

--------------------------------

### On-Chain Agent Registration with Wallet (JavaScript)

Source: https://github.com/erc-8004/best-practices/blob/main/Registration.md

Example of how to include agent wallet and name information when registering an agent via a smart contract, using key-value pairs.

```javascript
// When registering via smart contract
register(
  tokenURI,
  [
    { key: "agentWallet", value: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7" },
    { key: "agentName", value: "dataanalyst.eth" }
  ]
)
```

--------------------------------

### Feedback Value Encoding Examples (JavaScript)

Source: https://context7.com/erc-8004/best-practices/llms.txt

Illustrates how to encode various types of feedback values, such as ratings, percentages, and metrics, using the `value` and `valueDecimals` fields. This demonstrates the flexibility of the fixed-point number representation.

```javascript
// Example feedback values and their encoding

// Quality rating: 87/100
const starRating = { value: 87, valueDecimals: 0, tag1: "starred" };

// Binary reachability: true
const reachable = { value: 1, valueDecimals: 0, tag1: "reachable" };

// Uptime percentage: 99.77%
const uptime = { value: 9977, valueDecimals: 2, tag1: "uptime" };

// Response time: 560ms
const latency = { value: 560, valueDecimals: 0, tag1: "responseTime" };

// Trading yield: -3.2% (negative value for losses)
const tradingYield = { value: -32, valueDecimals: 1, tag1: "tradingYield", tag2: "week" };

// Cumulative revenue: $560
const revenue = { value: 560, valueDecimals: 0, tag1: "revenues" };

// 5-star rating mapped to 0-100 scale
const starMappings = {
  "1-star": { value: 20, valueDecimals: 0 },
  "2-star": { value: 40, valueDecimals: 0 },
  "3-star": { value: 60, valueDecimals: 0 },
  "4-star": { value: 80, valueDecimals: 0 },
  "5-star": { value: 100, valueDecimals: 0 }
};

```

--------------------------------

### Get Last Feedback Index (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Returns the index of the last feedback entry for a specific agent and client address.

```solidity
function getLastIndex(uint256 agentId, address clientAddress) external view returns (uint64)
```

--------------------------------

### Agent Endpoint Verification File (JSON)

Source: https://context7.com/erc-8004/best-practices/llms.txt

An example JSON file published at `/.well-known/agent-registration.json` on an agent's HTTPS endpoint. This file serves to prove control of the endpoint and links the off-chain service to its on-chain identity via `agentId` and `agentRegistry`.

```json
// Published at: https://api.cryptotrader-alpha.io/.well-known/agent-registration.json

{
  "registrations": [
    {
      "agentId": 42,
      "agentRegistry": "eip155:1:0x8004a6090Cd10A7288092483047B097295Fb8847"
    }
  ]
}
```

--------------------------------

### Get Identity Registry Address (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Retrieves the address of the identity registry. This is a view function and does not modify state.

```solidity
function getIdentityRegistry() external view returns (address identityRegistry)
```

--------------------------------

### Get Response Count (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Returns the count of responses for a specific feedback entry, with optional filtering by responders. Agent ID is the only mandatory parameter.

```solidity
function getResponseCount(uint256 agentId, address clientAddress, uint64 feedbackIndex, address[] responders) external view returns (uint64 count)
```

--------------------------------

### Get Identity Registry Address (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Retrieves the address of the identity registry contract, which is set during the initialization of the Validation Registry.

```solidity
getIdentityRegistry()
```

--------------------------------

### Register Agent with Metadata (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Registers a new agent with an optional URI and metadata. Emits Transfer and MetadataSet events. The agentId is returned.

```solidity
struct MetadataEntry {
string metadataKey;
bytes metadataValue;
}

function register(string agentURI, MetadataEntry[] calldata metadata) external returns (uint256 agentId)
```

--------------------------------

### Agent Registration Event (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Emitted when an agent is successfully registered. Includes the agentId, agentURI, and owner's address.

```solidity
event Registered(uint256 indexed agentId, string agentURI, address indexed owner)
```

--------------------------------

### Off-Chain Feedback File Structure (JSONC)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Defines the structure for optional off-chain feedback files. It includes mandatory fields like agent registry, agent ID, client address, creation timestamp, value, and value decimals, along with various optional fields for additional context.

```jsonc
{
  // MUST FIELDS
  "agentRegistry": "eip155:1:{identityRegistry}",
  "agentId": 22,
  "clientAddress": "eip155:1:{clientAddress}",
  "createdAt": "2025-09-23T12:00:00Z",
  "value": 100,
  "valueDecimals": 0,

  // ALL OPTIONAL FIELDS
  "tag1": "foo",
  "tag2": "bar",
  "endpoint": "https://agent.example.com/GetPrice",

  "mcp": { "tool": "ToolName" }, // or: { "prompt": "PromptName" } / { "resource": "ResourceName" },

  // A2A: see "Context Identifier Semantics" and Task model in the A2A specification.
  "a2a": {
    "skills": ["as-defined-by-A2A"], // e.g., AgentSkill identifiers
    "contextId": "as-defined-by-A2A",
    "taskId": "as-defined-by-A2A"
  },

  "oasf": {
    "skills": ["as-defined-by-OASF"],
    "domains": ["as-defined-by-OASF"]
  },
  
  "proofOfPayment": { // this can be used for x402 proof of payment
	  "fromAddress": "0x00...",
	  "toAddress": "0x00...",
	  "chainId": "1",
	  "txHash": "0x00..."
   },

 // Other fields
  " ... ": { " ... " } // MAY
}
```

--------------------------------

### Give Feedback Function (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Allows a clientAddress to provide feedback for a registered agent. Includes value, decimals, optional tags, endpoint, feedback URI, and hash. The agentId must be valid, and valueDecimals must be between 0 and 18.

```solidity
function giveFeedback(uint256 agentId, int128 value, uint8 valueDecimals, string calldata tag1, string calldata tag2, string calldata endpoint, string calldata feedbackURI, bytes32 feedbackHash) external
```

--------------------------------

### Read Feedback Summary (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Retrieves a summary of feedback for a given agent across multiple client addresses, with optional filtering by tags. Agent ID and client addresses are mandatory for accurate results.

```solidity
function getSummary(uint256 agentId, address[] calldata clientAddresses, string tag1, string tag2) external view returns (uint64 count, int128 summaryValue, uint8 summaryValueDecimals)
```

--------------------------------

### On-Chain Metadata Management (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Provides functions for managing optional on-chain agent metadata using `getMetadata` and `setMetadata`. It also details the `setAgentWallet` function for updating the agent's payment address, requiring EIP-712 or ERC-1271 signatures for verification.

```solidity
function getMetadata(uint256 agentId, string memory metadataKey) external view returns (bytes memory)
function setMetadata(uint256 agentId, string memory metadataKey, bytes memory metadataValue) external
```

```solidity
event MetadataSet(uint256 indexed agentId, string indexed indexedMetadataKey, string metadataKey, bytes metadataValue)
```

```solidity
function setAgentWallet(uint256 agentId, address newWallet, uint256 deadline, bytes calldata signature) external
```

```solidity
function getAgentWallet(uint256 agentId) external view returns (address)
function unsetAgentWallet(uint256 agentId) external
```

--------------------------------

### Validation Registry Initialization (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Initializes the Validation Registry by setting the identity registry address. This address is crucial for linking validation requests to agent identities.

```solidity
initialize(address identityRegistry_)
```

--------------------------------

### Agent Registration File Structure (JSONC)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Defines the mandatory and optional fields for an agent registration file, including type, name, description, image, and services. The services array allows for various endpoint types like web, A2A, MCP, OASF, ENS, DID, and email.

```jsonc
{
  "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
  "name": "myAgentName",
  "description": "A natural language description of the Agent, which MAY include what it does, how it works, pricing, and interaction methods",
  "image": "https://example.com/agentimage.png",
  "services": [
   {
      "name": "web",
      "endpoint": "https://web.agentxyz.com/"
    },
    {
      "name": "A2A",
      "endpoint": "https://agent.example/.well-known/agent-card.json",
      "version": "0.3.0"
    },
    {
      "name": "MCP",
      "endpoint": "https://mcp.agent.eth/",
      "version": "2025-06-18"
    },
    {
      "name": "OASF",
      "endpoint": "ipfs://{cid}",
      "version": "0.8", 
      "skills": [], 
      "domains": [] 
    },
    {
      "name": "ENS",
      "endpoint": "vitalik.eth",
      "version": "v1"
    },
    {
      "name": "DID",
      "endpoint": "did:method:foobar",
      "version": "v1"
    },
    {
      "name": "email",
      "endpoint": "mail@myagent.com"
    }
  ],
  "x402Support": false,
  "active": true,
  "registrations": [
    {
      "agentId": 22,
      "agentRegistry": "{namespace}:{chainId}:{identityRegistry}" 
    }
  ],
  "supportedTrust": [
    "reputation",
    "crypto-economic",
    "tee-attestation"
  ]
}
```

--------------------------------

### Register Agent without URI or Metadata (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Registers a new agent without an initial URI or metadata. The agentURI can be set later using setAgentURI(). Emits a Transfer event. The agentId is returned.

```solidity
function register() external returns (uint256 agentId)
```

--------------------------------

### New Feedback Event (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Emitted when new feedback is successfully submitted. Includes agentId, clientAddress, feedbackIndex, value, decimals, tags, endpoint, feedbackURI, and feedbackHash.

```solidity
event NewFeedback(uint256 indexed agentId, address indexed clientAddress, uint64 feedbackIndex, int128 value, uint8 valueDecimals, string indexed indexedTag1, string tag1, string tag2, string endpoint, string feedbackURI, bytes32 feedbackHash)
```

--------------------------------

### Register Agent without Metadata (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Registers a new agent with a URI but no additional metadata. Emits Transfer and MetadataSet events. The agentId is returned.

```solidity
function register(string agentURI) external returns (uint256 agentId)
```

--------------------------------

### Agent Registration File Structure

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Defines the mandatory and optional fields for an agent registration file, including agent details, services, and trust support.

```APIDOC
## Agent Registration File Structure

### Description
This section outlines the schema for the agent registration file, which is referenced by `agentURI`. It includes essential information about the agent and its services.

### Fields

- **type** (string) - Required - Must be `"https://eips.ethereum.org/EIPS/eip-8004#registration-v1"`.
- **name** (string) - Required - The human-readable name of the agent.
- **description** (string) - Optional - A detailed description of the agent's purpose and functionality.
- **image** (string) - Optional - A URL pointing to an image representing the agent.
- **services** (array) - Optional - A list of services offered by the agent.
  - Each service object has:
    - **name** (string) - Required - The name of the service (e.g., `web`, `A2A`, `MCP`).
    - **endpoint** (string) - Required - The URI or URL for the service endpoint.
    - **version** (string) - Optional - The version of the service.
    - **skills** (array) - Optional - List of skills for the `OASF` service type.
    - **domains** (array) - Optional - List of domains for the `OASF` service type.
- **x402Support** (boolean) - Optional - Indicates support for X402.
- **active** (boolean) - Optional - Indicates if the agent is currently active.
- **registrations** (array) - Optional - List of on-chain registrations for the agent.
  - Each registration object has:
    - **agentId** (number) - Required - The agent's unique identifier.
    - **agentRegistry** (string) - Required - The identifier for the agent registry (e.g., `eip155:1:0x742...`).
- **supportedTrust** (array) - Optional - A list of trust mechanisms supported by the agent (e.g., `reputation`, `crypto-economic`, `tee-attestation`).

### Request Example
```json
{
  "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
  "name": "My Agent Name",
  "description": "A natural language description of the Agent.",
  "image": "https://example.com/agentimage.png",
  "services": [
    {
      "name": "web",
      "endpoint": "https://web.agentxyz.com/"
    },
    {
      "name": "A2A",
      "endpoint": "https://agent.example/.well-known/agent-card.json",
      "version": "0.3.0"
    }
  ],
  "x402Support": false,
  "active": true,
  "registrations": [
    {
      "agentId": 22,
      "agentRegistry": "eip155:1:0x742..."
    }
  ],
  "supportedTrust": [
    "reputation"
  ]
}
```
```

--------------------------------

### Agent Registration API

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Register new agents with optional metadata. This process emits Transfer and MetadataSet events.

```APIDOC
## POST /register

### Description
Registers a new agent. This function can be overloaded to include metadata or be called without initial metadata.

### Method
POST

### Endpoint
`/register`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **agentURI** (string) - Optional - The URI pointing to the agent's metadata. Required if not using `setAgentURI` later.
* **metadata** (array of objects) - Optional - An array of metadata entries, where each entry has `metadataKey` (string) and `metadataValue` (bytes).

### Request Example
```json
{
  "agentURI": "ipfs://agent_metadata_hash",
  "metadata": [
    {
      "metadataKey": "agentWallet",
      "metadataValue": "0x123..."
    },
    {
      "metadataKey": "agentName",
      "metadataValue": "Agent Alpha"
    }
  ]
}
```

### Response
#### Success Response (200)
- **agentId** (uint256) - The unique identifier for the newly registered agent.

#### Response Example
```json
{
  "agentId": 1
}
```

### Events Emitted
- `Transfer(agentId, owner, tokenId)`
- `MetadataSet(agentId, metadataKey, metadataValue)` for each metadata entry.
- `Registered(agentId, agentURI, owner)`
```

--------------------------------

### Enable x402 Payment Protocol Support JSON

Source: https://github.com/erc-8004/best-practices/blob/main/Registration.md

This JSON snippet indicates that an agent supports the x402 payment protocol. Setting the 'x402Support' flag to 'true' signals that the agent is production-ready and can handle proof-of-payment for its services, enhancing trust and interoperability.

```json
{
  "x402Support": true
}
```

--------------------------------

### Read Specific Feedback (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Fetches details of a specific feedback entry, including its value, decimals, tags, and revocation status. Requires agent ID, client address, and the feedback index.

```solidity
function readFeedback(uint256 agentId, address clientAddress, uint64 feedbackIndex) external view returns (int128 value, uint8 valueDecimals, string tag1, string tag2, bool isRevoked)
```

--------------------------------

### Read All Feedback Entries (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Retrieves all feedback entries for a given agent, with options to filter by client addresses and tags, and to include revoked feedback. Agent ID is the only mandatory parameter.

```solidity
function readAllFeedback(uint256 agentId, address[] calldata clientAddresses, string tag1, string tag2, bool includeRevoked) external view returns (address[] memory clients, uint64[] memory feedbackIndexes, int128[] memory values, uint8[] memory valueDecimals, string[] memory tag1s, string[] memory tag2s, bool[] memory revokedStatuses)
```

--------------------------------

### Endpoint Domain Verification

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Explains the optional process for agents to verify control over their HTTPS endpoint domains by publishing a specific JSON file.

```APIDOC
## Endpoint Domain Verification (Optional)

### Description
Agents can optionally prove control over an HTTPS endpoint domain by publishing a `agent-registration.json` file at `https://{endpoint-domain}/.well-known/`. This file must contain a `registrations` list that matches the agent's on-chain registration details. If the endpoint domain is the same as the domain serving the primary `agentURI`, this verification is implicitly satisfied.

### Requirements
- The file must be accessible via HTTPS.
- The file must contain a `registrations` entry.
- The `agentRegistry` and `agentId` in the `registrations` entry must match the agent's on-chain registration.

### File Structure
```json
{
  "registrations": [
    {
      "agentId": "number",
      "agentRegistry": "string"
    }
  ]
}
```
```

--------------------------------

### Append Feedback Response (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Allows any entity to append a response to a feedback entry. It requires agent ID, client address, feedback index, a URI to the response content, and an optional hash of the response content for integrity verification.

```solidity
function appendResponse(uint256 agentId, address clientAddress, uint64 feedbackIndex, string calldata responseURI, bytes32 responseHash) external
```

--------------------------------

### Give Feedback API

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Allows a client address to provide feedback for a registered agent. This emits a NewFeedback event.

```APIDOC
## POST /agents/{agentId}/feedback

### Description
Submits new feedback for a specific agent.

### Method
POST

### Endpoint
`/agents/{agentId}/feedback`

### Parameters
#### Path Parameters
* **agentId** (uint256) - Required - The ID of the agent to provide feedback for.

#### Query Parameters
None

#### Request Body
* **value** (int128) - Required - The feedback value (e.g., rating, score).
* **valueDecimals** (uint8) - Required - The number of decimal places for the value (0-18).
* **tag1** (string) - Optional - A primary tag for the feedback (e.g., 'starred', 'uptime').
* **tag2** (string) - Optional - A secondary tag for the feedback (e.g., 'day', 'week').
* **endpoint** (string) - Optional - URI of the endpoint the feedback pertains to.
* **feedbackURI** (string) - Optional - URI pointing to off-chain feedback details.
* **feedbackHash** (bytes32) - Optional - KECCAK-256 hash of the off-chain feedback file.

### Request Example
```json
{
  "value": 87,
  "valueDecimals": 0,
  "tag1": "starred",
  "endpoint": "https://example.com/api/agent/1",
  "feedbackURI": "ipfs://feedback_hash_123"
}
```

### Response
#### Success Response (200)
- **feedbackIndex** (uint64) - The index of the newly submitted feedback for the client.

#### Response Example
```json
{
  "feedbackIndex": 5
}
```

### Events Emitted
- `NewFeedback(agentId, clientAddress, feedbackIndex, value, valueDecimals, indexedTag1, tag1, tag2, endpoint, feedbackURI, feedbackHash)`
```

--------------------------------

### On-Chain Metadata Functions

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Details the smart contract functions for retrieving, setting, and managing agent metadata on the blockchain.

```APIDOC
## On-Chain Metadata Functions

### Description
This section describes the smart contract functions provided by the ERC-721 extension for managing agent metadata on-chain. These functions allow for optional, arbitrary metadata associated with an agent.

### Functions

#### `getMetadata(uint256 agentId, string metadataKey)`

- **Description**: Retrieves the metadata value associated with a given agent ID and metadata key.
- **Method**: `view`
- **Parameters**:
  - `agentId` (uint256) - The ID of the agent.
  - `metadataKey` (string) - The key of the metadata to retrieve.
- **Returns**:
  - `bytes memory` - The metadata value.

#### `setMetadata(uint256 agentId, string metadataKey, bytes metadataValue)`

- **Description**: Sets or updates the metadata value for a given agent ID and metadata key.
- **Method**: `external`
- **Parameters**:
  - `agentId` (uint256) - The ID of the agent.
  - `metadataKey` (string) - The key of the metadata to set.
  - `metadataValue` (bytes) - The value of the metadata.

### Events

#### `MetadataSet(uint256 indexed agentId, string indexed indexedMetadataKey, string metadataKey, bytes metadataValue)`

- **Description**: Emitted when metadata is successfully set or updated.
- **Parameters**:
  - `agentId` (uint256) - The ID of the agent.
  - `indexedMetadataKey` (string) - The indexed metadata key.
  - `metadataKey` (string) - The metadata key.
  - `metadataValue` (bytes) - The metadata value.

### Agent Wallet Management

The `agentWallet` is a reserved key representing the agent's payment address. It is initially set to the owner's address and cannot be set via `setMetadata` or during registration. It is automatically cleared upon agent transfer.

#### `setAgentWallet(uint256 agentId, address newWallet, uint256 deadline, bytes signature)`

- **Description**: Allows the agent owner to change the `agentWallet`. Requires a valid EIP-712 or ERC-1271 signature to prove control of the `newWallet`.
- **Method**: `external`
- **Parameters**:
  - `agentId` (uint256) - The ID of the agent.
  - `newWallet` (address) - The new wallet address.
  - `deadline` (uint256) - The signature deadline.
  - `signature` (bytes) - The EIP-712 or ERC-1271 signature.

#### `getAgentWallet(uint256 agentId)`

- **Description**: Retrieves the currently set `agentWallet` for the specified agent.
- **Method**: `view`
- **Parameters**:
  - `agentId` (uint256) - The ID of the agent.
- **Returns**:
  - `address` - The agent wallet address.

#### `unsetAgentWallet(uint256 agentId)`

- **Description**: Clears the currently set `agentWallet` for the specified agent.
- **Method**: `external`
- **Parameters**:
  - `agentId` (uint256) - The ID of the agent.
```

--------------------------------

### Agent URI Update Event (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Emitted when an agent's URI is updated. Includes the agentId, the new URI, and the address of the updater.

```solidity
event URIUpdated(uint256 indexed agentId, string newURI, address indexed updatedBy)
```

--------------------------------

### Off-Chain Feedback File Schema (JSON)

Source: https://context7.com/erc-8004/best-practices/llms.txt

Defines the structure for off-chain feedback data, which can be stored on systems like IPFS and referenced by `feedbackURI`. This schema includes details about the agent, client, timestamps, feedback values, and optional metadata like payment proofs.

```json
{
  "agentRegistry": "eip155:1:0x8004a6090Cd10A7288092483047B097295Fb8847",
  "agentId": 42,
  "clientAddress": "eip155:1:0xClientAddress123",
  "createdAt": "2025-09-23T12:00:00Z",
  "value": 100,
  "valueDecimals": 0,
  "tag1": "starred",
  "tag2": "trading",
  "endpoint": "https://api.cryptotrader-alpha.io/execute_trade",
  "mcp": {
    "tool": "execute_trade"
  },
  "a2a": {
    "skills": ["analytical_skills/coding_skills/text_to_code"],
    "contextId": "ctx-abc123",
    "taskId": "task-xyz789"
  },
  "oasf": {
    "skills": ["advanced_reasoning_planning/strategic_planning"],
    "domains": ["finance_and_business/investment_services"]
  },
  "proofOfPayment": {
    "fromAddress": "0xClientAddress123",
    "toAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
    "chainId": "1",
    "txHash": "0xTransactionHash..."
  }
}

```

--------------------------------

### Mainnet Agent Wallet Configuration (JSON)

Source: https://github.com/erc-8004/best-practices/blob/main/Registration.md

JSON configuration to advertise an agent's payment wallet address on the Ethereum mainnet, adhering to the x402 standard.

```json
{
  "name": "agentWallet",
  "endpoint": "eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7"
}
```

--------------------------------

### Update Agent URI (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Updates the agentURI for a given agentId. Emits a URIUpdated event. Requires the agentId and the new URI.

```solidity
function setAgentURI(uint256 agentId, string calldata newURI) external
```

--------------------------------

### Complete Production-Ready Agent Registration (JSON)

Source: https://github.com/erc-8004/best-practices/blob/main/Registration.md

This comprehensive JSON object represents a complete registration file for a production-ready crypto trading agent. It includes details about the agent's type, name, description, services, supported trust mechanisms, and activation status.

```json
{
  "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
  "name": "CryptoTrader Alpha",
  "description": "An autonomous AI trading agent that manages crypto portfolios on your behalf using advanced DeFi strategies. Supports automated trading on DEXs, yield optimization, risk management, and real-time market analysis. Trades on Ethereum, Base, Arbitrum, and Polygon. Features: portfolio rebalancing, stop-loss protection, MEV-resistant execution, gas optimization. Pricing: 2% performance fee on profits, no management fees. Minimum portfolio: 0.5 ETH. Audited smart contracts, non-custodial.",
  "image": "https://cdn.cryptotrader-alpha.io/logo.png",
  "services": [
    {
      "name": "MCP",
      "endpoint": "https://api.cryptotrader-alpha.io/mcp",
      "version": "2025-06-18",
      "mcpTools": [
        "portfolio_analysis",
        "execute_trade",
        "risk_assessment",
        "yield_optimizer",
        "market_sentiment_analysis",
        "gas_price_estimator",
        "defi_protocol_integrator"
      ]
    },
    {
      "name": "OASF",
      "endpoint": "https://github.com/agntcy/oasf/",
      "version": "v0.8.0",
      "skills": [
        "advanced_reasoning_planning/strategic_planning",
        "evaluation_monitoring/anomaly_detection",
        "security_privacy/vulnerability_analysis"
      ],
      "domains": [
        "finance_and_business/investment_services",
        "technology/blockchain/defi",
        "technology/blockchain/smart_contracts"
      ]
    },
    {
      "name": "agentWallet",
      "endpoint": "eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7"
    }
  ],
  "registrations": [
    {
      "agentId": 42,
      "agentRegistry": "eip155:1:0x8004a6090Cd10A7288092483047B097295Fb8847"
    }
  ],
  "supportedTrust": [
    "reputation",
    "crypto-economic"
  ],
  "active": true,
  "x402Support": true
}
```

--------------------------------

### DID Service Endpoint Configuration (JSON)

Source: https://github.com/erc-8004/best-practices/blob/main/Registration.md

Configuration for advertising an agent using a Decentralized Identifier (DID). It specifies the service name, the DID string as the endpoint, and a version identifier.

```json
{
  "name": "DID",
  "endpoint": "did:ethr:0x1234567890abcdef1234567890abcdef12345678",
  "version": "v1"
}
```

--------------------------------

### Reputation Registry Smart Contract Interface (Solidity)

Source: https://context7.com/erc-8004/best-practices/llms.txt

Defines the interface for the Reputation Registry smart contract, including functions for submitting, revoking, and reading feedback, as well as event definitions. It specifies the data structures and parameters for feedback signals.

```solidity
// SPDX-License-Identifier: MIT
// Reputation Registry Interface

// Submit feedback for an agent
function giveFeedback(
    uint256 agentId,
    int128 value,
    uint8 valueDecimals,
    string calldata tag1,
    string calldata tag2,
    string calldata endpoint,
    string calldata feedbackURI,
    bytes32 feedbackHash
) external;

// Revoke previously submitted feedback
function revokeFeedback(uint256 agentId, uint64 feedbackIndex) external;

// Append a response to existing feedback (for agent responses, spam tagging, etc.)
function appendResponse(
    uint256 agentId,
    address clientAddress,
    uint64 feedbackIndex,
    string calldata responseURI,
    bytes32 responseHash
) external;

// Read functions
function getSummary(
    uint256 agentId,
    address[] calldata clientAddresses,
    string tag1,
    string tag2
) external view returns (uint64 count, int128 summaryValue, uint8 summaryValueDecimals);

function readFeedback(
    uint256 agentId,
    address clientAddress,
    uint64 feedbackIndex
) external view returns (int128 value, uint8 valueDecimals, string tag1, string tag2, bool isRevoked);

function readAllFeedback(
    uint256 agentId,
    address[] calldata clientAddresses,
    string tag1,
    string tag2,
    bool includeRevoked
) external view returns (
    address[] memory clients,
    uint64[] memory feedbackIndexes,
    int128[] memory values,
    uint8[] memory valueDecimals,
    string[] memory tag1s,
    string[] memory tag2s,
    bool[] memory revokedStatuses
);

function getClients(uint256 agentId) external view returns (address[] memory);
function getLastIndex(uint256 agentId, address clientAddress) external view returns (uint64);

// Events
event NewFeedback(
    uint256 indexed agentId,
    address indexed clientAddress,
    uint64 feedbackIndex,
    int128 value,
    uint8 valueDecimals,
    string indexed indexedTag1,
    string tag1,
    string tag2,
    string endpoint,
    string feedbackURI,
    bytes32 feedbackHash
);
event FeedbackRevoked(uint256 indexed agentId, address indexed clientAddress, uint64 indexed feedbackIndex);
event ResponseAppended(
    uint256 indexed agentId,
    address indexed clientAddress,
    uint64 feedbackIndex,
    address indexed responder,
    string responseURI,
    bytes32 responseHash
);

```

--------------------------------

### Polygon Agent Wallet Configuration (JSON)

Source: https://github.com/erc-8004/best-practices/blob/main/Registration.md

JSON configuration to advertise an agent's payment wallet address on the Polygon network, demonstrating cross-chain wallet advertising.

```json
{
  "name": "agentWallet",
  "endpoint": "eip155:137:0x9876543210fedcba9876543210fedcba98765432"
}
```

--------------------------------

### Reputation Registry API

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Interact with the Reputation Registry to retrieve the identity registry address.

```APIDOC
## GET /identity-registry

### Description
Retrieves the address of the identity registry contract.

### Method
GET

### Endpoint
`/identity-registry`

### Parameters
None

### Response
#### Success Response (200)
- **identityRegistry** (address) - The address of the identity registry.

#### Response Example
```json
{
  "identityRegistry": "0xAbCdEf1234567890abcdef1234567890abcdef12"
}
```
```

--------------------------------

### Query Aggregated Validation Statistics (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Returns aggregated validation statistics for a specific agent. `agentId` is mandatory, while `validatorAddresses` and `tag` can be used as optional filters. The function returns the total `count` of validations and the `averageResponse` score.

```solidity
function getSummary(uint256 agentId, address[] calldata validatorAddresses, string tag) external view returns (uint64 count, uint8 averageResponse)
```

--------------------------------

### MCP Service Endpoint Configuration (JSON)

Source: https://github.com/erc-8004/best-practices/blob/main/Registration.md

Configuration for advertising an agent's Message Communication Protocol (MCP) service. It includes the service name, endpoint URL, version, and a list of supported MCP tools.

```json
{
  "name": "MCP",
  "endpoint": "https://api.dataanalyst-pro.com/mcp",
  "version": "2025-06-18",
  "mcpTools": [
    "data_analysis",
    "chart_generation",
    "statistical_modeling",
    "report_creation",
    "csv_parser"
  ]
}
```

--------------------------------

### ENS Service Endpoint Configuration (JSON)

Source: https://github.com/erc-8004/best-practices/blob/main/Registration.md

Configuration for advertising an agent using an Ethereum Name Service (ENS) domain. It includes the service name, the ENS domain as the endpoint, and a version identifier.

```json
{
  "name": "ENS",
  "endpoint": "dataanalyst.eth",
  "version": "v1"
}
```

--------------------------------

### Feedback Revoked Event (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Emitted when feedback is successfully revoked. Includes agentId, clientAddress, and the index of the revoked feedback.

```solidity
event FeedbackRevoked(uint256 indexed agentId, address indexed clientAddress, uint64 indexed feedbackIndex)
```

--------------------------------

### Request Validation (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Enables agents to request validation of their work by a specified validator. This function requires the validator's address, the agent's ID, a URI to the validation request data, and a hash of that data for commitment.

```solidity
function validationRequest(address validatorAddress, uint256 agentId, string requestURI, bytes32 requestHash) external
```

--------------------------------

### Query Validator Requests (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Retrieves a list of all `requestHashes` that a specific `validatorAddress` has responded to. This function is useful for tracking a validator's activity.

```solidity
function getValidatorRequests(address validatorAddress) external view returns (bytes32[] memory requestHashes)
```

--------------------------------

### OASF Skills and Domains Taxonomy

Source: https://context7.com/erc-8004/best-practices/llms.txt

This section outlines the Open Agentic Schema Framework (OASF) taxonomy used for classifying agent capabilities (skills) and application areas (domains).

```APIDOC
## OASF Skills and Domains Taxonomy

The protocol integrates with OASF (Open Agentic Schema Framework) for standardized agent capability classification. Skills define specific capabilities while domains define application areas.

### Skills Categories

- **natural_language_processing**
  - **Subcategories**: `natural_language_generation/summarization`, `natural_language_generation/text_generation`, `information_retrieval_synthesis/question_answering`, `information_retrieval_synthesis/document_retrieval`
- **images_computer_vision**
  - **Subcategories**: `object_detection`, `image_classification`, `image_segmentation`
- **data_engineering**
  - **Subcategories**: `data_cleaning`, `data_transformation_pipeline`, `schema_inference`
- **agent_orchestration**
  - **Subcategories**: `task_decomposition`, `workflow_management`, `multi_agent_coordination`
- **security_privacy**
  - **Subcategories**: `vulnerability_analysis`, `threat_detection`, `privacy_preservation`

### Domain Categories

- **technology**
  - **Subcategories**: `software_engineering/devops`, `data_science/data_visualization`, `blockchain/defi`, `blockchain/smart_contracts`
- **finance_and_business**
  - **Subcategories**: `investment_services`, `risk_management`, `accounting`
- **healthcare**
  - **Subcategories**: `telemedicine`, `medical_diagnostics`, `health_informatics`
- **legal**
  - **Subcategories**: `contract_law`, `compliance`, `intellectual_property`

```

--------------------------------

### Set Agent Active Status to False

Source: https://github.com/erc-8004/best-practices/blob/main/Registration.md

This JSON snippet demonstrates how to set the 'active' status of an agent to false. This is recommended for agents that are not yet ready for production or are undergoing testing, ensuring they are not discoverable or usable by real users.

```json
{
  "active": false
}
```

--------------------------------

### OASF Skills and Domains Taxonomy (JSON)

Source: https://context7.com/erc-8004/best-practices/llms.txt

A JSON structure defining the Open Agentic Schema Framework (OASF) for classifying agent capabilities. It categorizes skills (e.g., NLP, Computer Vision) and domains (e.g., Technology, Finance) with their respective subcategories for standardized agent classification.

```json
{
  "skills_categories": {
    "natural_language_processing": {
      "subcategories": [
        "natural_language_generation/summarization",
        "natural_language_generation/text_generation",
        "information_retrieval_synthesis/question_answering",
        "information_retrieval_synthesis/document_retrieval"
      ]
    },
    "images_computer_vision": {
      "subcategories": [
        "object_detection",
        "image_classification",
        "image_segmentation"
      ]
    },
    "data_engineering": {
      "subcategories": [
        "data_cleaning",
        "data_transformation_pipeline",
        "schema_inference"
      ]
    },
    "agent_orchestration": {
      "subcategories": [
        "task_decomposition",
        "workflow_management",
        "multi_agent_coordination"
      ]
    },
    "security_privacy": {
      "subcategories": [
        "vulnerability_analysis",
        "threat_detection",
        "privacy_preservation"
      ]
    }
  },
  "domain_categories": {
    "technology": {
      "subcategories": [
        "software_engineering/devops",
        "data_science/data_visualization",
        "blockchain/defi",
        "blockchain/smart_contracts"
      ]
    },
    "finance_and_business": {
      "subcategories": [
        "investment_services",
        "risk_management",
        "accounting"
      ]
    },
    "healthcare": {
      "subcategories": [
        "telemedicine",
        "medical_diagnostics",
        "health_informatics"
      ]
    },
    "legal": {
      "subcategories": [
        "contract_law",
        "compliance",
        "intellectual_property"
      ]
    }
  }
}
```

--------------------------------

### Query Agent Validations (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Retrieves a list of all `requestHashes` associated with a given `agentId`. This function allows querying all validation requests made by or for a specific agent.

```solidity
function getAgentValidations(uint256 agentId) external view returns (bytes32[] memory requestHashes)
```

--------------------------------

### Query Validation Status (Solidity)

Source: https://github.com/erc-8004/best-practices/blob/main/src/ERC8004SPEC.md

Retrieves the current validation status for a given `requestHash`. Returns the `validatorAddress`, `agentId`, `response`, `responseHash`, `tag`, and `lastUpdate` timestamp.

```solidity
function getValidationStatus(bytes32 requestHash) external view returns (address validatorAddress, uint256 agentId, uint8 response, bytes32 responseHash, string tag, uint256 lastUpdate)
```