{"openapi":"3.0.3","info":{"title":"8004scan Public API","description":"## Overview\n\nThe 8004scan Public API provides programmatic access to ERC-8004 agent data.\nThis API enables developers to discover, query, and integrate AI agents registered on the blockchain.\n\n## Authentication\n\nAll endpoints support optional API key authentication via the `X-API-Key` header.\nWithout an API key, requests are subject to anonymous rate limits.\n\n## Rate Limits\n\n| Tier | Requests/Min | Daily Limit |\n|------|--------------|-------------|\n| anonymous | 10 | 100 |\n| free_api | 30 | 1,000 |\n| basic | 100 | 10,000 |\n| pro | 500 | 100,000 |\n| enterprise | 2000 | unlimited |\n\nRate limit headers are included in all responses:\n- `X-RateLimit-Limit`: Maximum requests per minute\n- `X-RateLimit-Remaining`: Remaining requests in current window\n- `X-RateLimit-Reset`: When the rate limit window resets (ISO 8601)\n\n## Response Format\n\nAll responses follow a consistent JSON format:\n\n```json\n{\n  \"success\": true,\n  \"data\": { ... },\n  \"meta\": {\n    \"version\": \"1.0.0\",\n    \"timestamp\": \"2026-02-18T12:00:00Z\",\n    \"requestId\": \"abc123\"\n  }\n}\n```","version":"1.0.0","contact":{"name":"8004scan Team","url":"https://8004scan.io"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://testnet.8004scan.io/api/v1/public","description":"Current server"}],"tags":[{"name":"Agents","description":"Operations for discovering and querying ERC-8004 agents"},{"name":"Accounts","description":"Operations for querying wallet accounts"},{"name":"Stats","description":"Platform statistics and analytics"},{"name":"Feedbacks","description":"Agent feedback and reviews"},{"name":"Chains","description":"Supported blockchain networks"}],"paths":{"/agents":{"get":{"tags":["Agents"],"summary":"List agents","description":"Retrieve a paginated list of ERC-8004 agents with optional filtering and sorting.","operationId":"listAgents","parameters":[{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/limit"},{"name":"chainId","in":"query","description":"Filter by blockchain chain ID","schema":{"type":"integer","example":1}},{"name":"ownerAddress","in":"query","description":"Filter by owner wallet address","schema":{"type":"string","example":"0x..."}},{"name":"search","in":"query","description":"Search by name, description, or agent ID","schema":{"type":"string"}},{"name":"protocol","in":"query","description":"Filter by supported protocol","schema":{"type":"string","enum":["MCP","A2A","OASF","Web","Email"]}},{"name":"sortBy","in":"query","description":"Sort field","schema":{"type":"string","enum":["created_at","stars","name","token_id","total_score"],"default":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort order","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"isTestnet","in":"query","description":"Filter by testnet/mainnet","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentListResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/agents/{chainId}/{tokenId}":{"get":{"tags":["Agents"],"summary":"Get agent by ID","description":"Retrieve detailed information about a specific agent by chain ID and token ID.","operationId":"getAgent","parameters":[{"name":"chainId","in":"path","required":true,"description":"Blockchain chain ID","schema":{"type":"integer","example":1}},{"name":"tokenId","in":"path","required":true,"description":"Agent token ID","schema":{"type":"integer","example":123}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/agents/search":{"get":{"tags":["Agents"],"summary":"Semantic search","description":"Search for agents using semantic (vector) and keyword search.","operationId":"searchAgents","parameters":[{"name":"q","in":"query","required":true,"description":"Search query","schema":{"type":"string","example":"code review assistant"}},{"name":"limit","in":"query","description":"Maximum results (varies by tier: anonymous=10, free=20, basic=50, pro/enterprise=100)","schema":{"type":"integer","default":20,"maximum":100}},{"name":"chainId","in":"query","description":"Filter by chain ID","schema":{"type":"integer"}},{"name":"semanticWeight","in":"query","description":"Balance between semantic and keyword search (0=keyword only, 1=semantic only)","schema":{"type":"number","minimum":0,"maximum":1,"default":0.5}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/accounts/{address}/agents":{"get":{"tags":["Accounts"],"summary":"Get agents by owner","description":"Retrieve all agents owned by a specific wallet address.","operationId":"getAgentsByOwner","parameters":[{"name":"address","in":"path","required":true,"description":"Ethereum wallet address","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","example":"0x1234567890123456789012345678901234567890"}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/limit"},{"name":"sortBy","in":"query","description":"Sort field","schema":{"type":"string","enum":["created_at","stars","name","total_score"]}},{"name":"sortOrder","in":"query","description":"Sort order","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/stats":{"get":{"tags":["Stats"],"summary":"Get platform statistics","description":"Retrieve global platform statistics including total agents, users, feedbacks, and chain distribution.","operationId":"getStats","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/feedbacks":{"get":{"tags":["Feedbacks"],"summary":"List feedbacks","description":"Retrieve a paginated list of agent feedbacks with optional filtering.","operationId":"listFeedbacks","parameters":[{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/limit"},{"name":"chainId","in":"query","description":"Filter by chain ID","schema":{"type":"integer"}},{"name":"tokenId","in":"query","description":"Filter by agent token ID (requires chainId)","schema":{"type":"integer"}},{"name":"minScore","in":"query","description":"Minimum feedback score","schema":{"type":"number","minimum":0,"maximum":5}},{"name":"maxScore","in":"query","description":"Maximum feedback score","schema":{"type":"number","minimum":0,"maximum":5}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackListResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/chains":{"get":{"tags":["Chains"],"summary":"List supported chains","description":"Retrieve the list of supported blockchain networks.","operationId":"listChains","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChainsResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Optional API key for higher rate limits. Get one at https://8004scan.io/developers/api-keys"}},"parameters":{"page":{"name":"page","in":"query","description":"Page number (1-indexed)","schema":{"type":"integer","minimum":1,"default":1}},"limit":{"name":"limit","in":"query","description":"Items per page","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}},"schemas":{"ResponseMeta":{"type":"object","properties":{"version":{"type":"string","example":"1.0.0"},"timestamp":{"type":"string","format":"date-time","example":"2026-02-18T12:00:00Z"},"requestId":{"type":"string","example":"abc123xyz"},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer","example":1},"limit":{"type":"integer","example":20},"total":{"type":"integer","example":150},"hasMore":{"type":"boolean","example":true}}},"Agent":{"type":"object","properties":{"id":{"type":"string"},"agent_id":{"type":"string"},"token_id":{"type":"integer"},"chain_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"image_url":{"type":"string","format":"uri"},"owner_address":{"type":"string"},"supported_protocols":{"type":"array","items":{"type":"string"}},"total_score":{"type":"number"},"star_count":{"type":"integer"},"total_feedbacks":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"Feedback":{"type":"object","properties":{"id":{"type":"string"},"chain_id":{"type":"integer"},"token_id":{"type":"integer"},"user_id":{"type":"string"},"score":{"type":"number"},"comment":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"Chain":{"type":"object","properties":{"chain_id":{"type":"integer"},"name":{"type":"string"},"is_testnet":{"type":"boolean"},"explorer_url":{"type":"string","format":"uri"}}},"AgentListResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"AgentResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Agent"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"AgentSearchResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"StatsResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"total_agents":{"type":"integer"},"total_users":{"type":"integer"},"total_feedbacks":{"type":"integer"},"total_validations":{"type":"integer"}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"FeedbackListResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Feedback"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"ChainsResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Chain"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string"},"details":{"type":"object"}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}},"responses":{"BadRequest":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"INVALID_PARAMS","message":"Invalid parameter value"},"meta":{"version":"1.0.0","timestamp":"2026-02-18T12:00:00Z","requestId":"abc123"}}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NOT_FOUND","message":"Agent not found"},"meta":{"version":"1.0.0","timestamp":"2026-02-18T12:00:00Z","requestId":"abc123"}}}}},"RateLimitExceeded":{"description":"Rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Maximum requests per minute"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests in current window"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"When the rate limit resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Rate limit exceeded. Try again later or upgrade your API tier.","details":{"limit":10,"remaining":0,"resetAt":"2026-02-18T12:01:00Z"}},"meta":{"version":"1.0.0","timestamp":"2026-02-18T12:00:00Z","requestId":"abc123"}}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"},"meta":{"version":"1.0.0","timestamp":"2026-02-18T12:00:00Z","requestId":"abc123"}}}}}}},"security":[{"ApiKeyAuth":[]},{}]}