GitHub

Indexed REST Surface

API Surface For The Indexed Agent Layer

The API is indexed across Ethereum and Base, responses are stable and machine-friendly, and the browse surface exposes the same underlying model. List agents, inspect a single record, or pull registry-wide stats with explicit sync metadata.

Open OpenAPI

Live Examples

Try the API without leaving the page.

Start with opinionated examples. Run the request, inspect the live response, and copy the client code that matches it.

Search Agents

Run a high-intent search for agents by service and reputation across all networks or within one chain.

Request Path

/api/v2/agents?search=mcp&service=mcp&sort=reputation&limit=5&filter=has-reputation&chain=1

Network

Live Response

Run the example to fetch a real response.

No response yet.

Endpoint

GET

/api/v2/agents

Paginated, sortable, searchable listing of all indexed ERC-8004 agents. Supports filtering by service type, reputation status, and network.

Parameters

pagequeryinteger

Page number

Default 1

limitqueryinteger

Results per page

Default 24

sortquerystring

Sort order

Default reputation

searchquerystring

Search across agent name, description, owner address, and agent ID

filterquerystring

Filter to agents with reputation or return the full indexed set

Default has-reputation

servicequerystring

Filter by service type (e.g., "mcp", "a2a", "web", "x402")

chainqueryinteger

Optional chain filter. `1` = Ethereum, `8453` = Base.

Curl

List registered agents

curl "https://8004.fyi/api/v2/agents?chain=8453&search=mcp&service=mcp&sort=reputation&limit=5"
Examples are hand-authored to stay readable and close to real usage.

Example Response

Representative payload

{
  "agents": [
    {
      "chainId": 8453,
      "agentId": "21",
      "name": "Registry Copilot",
      "services": [{ "name": "MCP", "endpoint": "https://agent.example.com/mcp" }],
      "feedbackCount": 12
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 5,
  "totalPages": 1,
  "lastSyncBlock": 24637464
}

Endpoint

GET

/api/v2/agents/{id}

Full agent details including network, metadata, services, and all reputation feedback entries.

Parameters

idpathinteger

Agent ID (ERC-721 token ID)

chainqueryinteger

Optional chain selector. Defaults to Ethereum if omitted.

Curl

Get agent details

curl "https://8004.fyi/api/v2/agents/21?chain=8453"
Examples are hand-authored to stay readable and close to real usage.

Example Response

Representative payload

{
  "chainId": 8453,
  "agentId": "21",
  "owner": "0xabc...def",
  "agentURI": "ipfs://...",
  "blockNumber": 24630201,
  "services": [{ "name": "MCP", "endpoint": "https://agent.example.com/mcp" }],
  "feedback": [],
  "lastSyncBlock": 24637464
}

Endpoint

GET

/api/v2/stats

Aggregate statistics for the indexed ERC-8004 registry across all supported networks, including total agents, reputation coverage, and sync status.

Parameters

No parameters. Call this endpoint directly.

Curl

Get registry statistics

curl "https://8004.fyi/api/v2/stats"
Examples are hand-authored to stay readable and close to real usage.

Example Response

Representative payload

{
  "totalAgents": 28412,
  "agentsWithReputation": 1470,
  "totalFeedback": 47891,
  "lastSyncBlock": 26830000,
  "lastSyncAt": "2026-03-12T14:58:00.000Z"
}