{
  "openapi": "3.1.0",
  "info": {
    "title": "8004 Explorer API",
    "description": "REST API for indexed ERC-8004 agent data across Ethereum and Base. Provides searchable, paginated access to registered agents, their metadata, services, reputation feedback, and registry statistics.",
    "version": "2.0.0",
    "contact": {
      "name": "8004 Explorer",
      "url": "https://8004.fyi"
    },
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://8004.fyi",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/v2/agents": {
      "get": {
        "operationId": "listAgents",
        "summary": "List registered agents",
        "description": "Paginated, sortable, searchable listing of all indexed ERC-8004 agents. Supports filtering by service type, reputation status, and network.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "description": "Page number"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 24
            },
            "description": "Results per page"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "reputation",
                "name"
              ],
              "default": "reputation"
            },
            "description": "Sort order"
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Search across agent name, description, owner address, and agent ID"
          },
          {
            "name": "filter",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "has-reputation",
                "all"
              ],
              "default": "has-reputation"
            },
            "description": "Filter to agents with reputation or return the full indexed set"
          },
          {
            "name": "service",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by service type (e.g., \"mcp\", \"a2a\", \"web\", \"x402\")"
          },
          {
            "name": "chain",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                1,
                8453
              ]
            },
            "description": "Optional chain filter. `1` = Ethereum, `8453` = Base."
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of agents",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedAgentsResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/agents/{id}": {
      "get": {
        "operationId": "getAgent",
        "summary": "Get agent details",
        "description": "Full agent details including network, metadata, services, and all reputation feedback entries.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Agent ID (ERC-721 token ID)"
          },
          {
            "name": "chain",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                1,
                8453
              ]
            },
            "description": "Optional chain selector. Defaults to Ethereum if omitted."
          }
        ],
        "responses": {
          "200": {
            "description": "Agent details with feedback",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentDetailResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid agent ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Get registry statistics",
        "description": "Aggregate statistics for the indexed ERC-8004 registry across all supported networks, including total agents, reputation coverage, and sync status.",
        "responses": {
          "200": {
            "description": "Registry statistics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatsResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AgentService": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Service type (e.g., \"MCP\", \"A2A\", \"OASF\", \"web\", \"x402\")"
          },
          "endpoint": {
            "type": "string",
            "format": "uri",
            "description": "Service endpoint URL"
          },
          "version": {
            "type": "string",
            "description": "Service version"
          },
          "skills": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Capabilities offered by this service"
          },
          "domains": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Applicable domains"
          }
        },
        "required": [
          "name",
          "endpoint"
        ]
      },
      "Agent": {
        "type": "object",
        "properties": {
          "chainId": {
            "type": "integer",
            "description": "Chain ID (`1` = Ethereum, `8453` = Base)"
          },
          "agentId": {
            "type": "string",
            "description": "Agent ID (serialized bigint)"
          },
          "owner": {
            "type": "string",
            "description": "EVM address of the agent owner"
          },
          "agentURI": {
            "type": "string",
            "description": "Metadata URI (IPFS, Arweave, or HTTPS)"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "image": {
            "type": "string",
            "nullable": true,
            "description": "Resolved image URL"
          },
          "services": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentService"
            }
          },
          "x402Support": {
            "type": "boolean",
            "description": "Supports x402 payment protocol"
          },
          "active": {
            "type": "boolean"
          },
          "supportedTrust": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "feedbackCount": {
            "type": "integer",
            "description": "Number of active (non-revoked) feedback entries"
          }
        },
        "required": [
          "chainId",
          "agentId",
          "owner",
          "agentURI"
        ]
      },
      "FeedbackEntry": {
        "type": "object",
        "properties": {
          "clientAddress": {
            "type": "string",
            "description": "Address of the feedback giver"
          },
          "feedbackIndex": {
            "type": "string",
            "description": "Feedback sequence number"
          },
          "value": {
            "type": "string",
            "description": "Signed int128 value"
          },
          "valueDecimals": {
            "type": "integer",
            "description": "Decimal places for value encoding"
          },
          "tag1": {
            "type": "string",
            "description": "Primary tag (quality, reachable, uptime, responsetime, starred)"
          },
          "tag2": {
            "type": "string",
            "description": "Secondary context tag"
          },
          "isRevoked": {
            "type": "boolean"
          },
          "blockNumber": {
            "type": "integer",
            "nullable": true
          },
          "txHash": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "clientAddress",
          "feedbackIndex",
          "value",
          "valueDecimals",
          "tag1",
          "tag2",
          "isRevoked"
        ]
      },
      "AgentDetailResponse": {
        "type": "object",
        "properties": {
          "chainId": {
            "type": "integer",
            "description": "Chain ID (`1` = Ethereum, `8453` = Base)"
          },
          "agentId": {
            "type": "string"
          },
          "owner": {
            "type": "string"
          },
          "agentURI": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "image": {
            "type": "string",
            "nullable": true
          },
          "services": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentService"
            }
          },
          "x402Support": {
            "type": "boolean"
          },
          "active": {
            "type": "boolean"
          },
          "supportedTrust": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "metadataRaw": {
            "type": "object",
            "nullable": true,
            "description": "Full original metadata JSON"
          },
          "blockNumber": {
            "type": "integer",
            "nullable": true
          },
          "feedback": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FeedbackEntry"
            }
          },
          "lastSyncBlock": {
            "type": "integer",
            "nullable": true
          }
        },
        "required": [
          "chainId",
          "agentId",
          "owner",
          "agentURI"
        ]
      },
      "PaginatedAgentsResponse": {
        "type": "object",
        "properties": {
          "agents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Agent"
            }
          },
          "total": {
            "type": "integer"
          },
          "page": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "totalPages": {
            "type": "integer"
          },
          "lastSyncBlock": {
            "type": "integer",
            "nullable": true,
            "description": "When a chain filter is provided, this is that network's last synced block."
          }
        },
        "required": [
          "agents",
          "total",
          "page",
          "limit",
          "totalPages"
        ]
      },
      "StatsResponse": {
        "type": "object",
        "properties": {
          "totalAgents": {
            "type": "integer",
            "description": "Aggregated across all indexed networks"
          },
          "agentsWithReputation": {
            "type": "integer",
            "description": "Aggregated across all indexed networks"
          },
          "totalFeedback": {
            "type": "integer",
            "description": "Aggregated across all indexed networks"
          },
          "lastSyncBlock": {
            "type": "integer",
            "nullable": true,
            "description": "Most recent indexed checkpoint across the supported networks"
          },
          "lastSyncAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp of the most recent indexed pass across the supported networks"
          }
        },
        "required": [
          "totalAgents",
          "agentsWithReputation",
          "totalFeedback"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}