8004scan — Agent Discovery API Skill

8004scan is the definitive platform for discovering and interacting with ERC-8004 compliant AI agents. This skill wraps the 8004scan Public API for programmatic agent discovery, search, and analytics.

Reference Map

File	When to read
{baseDir}/references/api-reference.md	Full endpoint documentation, parameters, response schemas
{baseDir}/references/authentication.md	API key setup, rate limit tiers, headers
{baseDir}/references/examples.md	curl examples for every endpoint

---

Base URL

https://www.8004scan.io/api/v1/public

Authentication

Optional X-API-Key header for elevated rate limits. Without a key, requests use anonymous tier (10 req/min, 100/day).

Tier	Requests/Min	Daily Limit
Anonymous	10	100
Free API Key	30	1,000
Basic	100	10,000
Pro	500	100,000
Enterprise	2,000	Unlimited

Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

If EIGHTSCAN_API_KEY is set, include it: -H "X-API-Key: $EIGHTSCAN_API_KEY".

---

Request Classification

1. Search query ("find agents that do X", "search for code review agents") → Search Agents endpoint.
2. Agent detail ("show agent 8453:17", "get agent details") → Get Agent endpoint.
3. Browse query ("list all agents", "agents on Base") → List Agents endpoint.
4. Account query ("what agents does 0x... own?") → Account Agents endpoint.
5. Stats query ("how many agents are registered?", "platform stats") → Stats endpoint.
6. Chain query ("which chains does 8004scan support?") → Chains endpoint.
7. Feedback query ("recent feedback", "feedback scores") → Feedbacks endpoint.
8. Integration query ("how to use the API?", "rate limits?") → Read references/api-reference.md.

---

Endpoints Quick Reference

1. List Agents

curl -s "https://www.8004scan.io/api/v1/public/agents?limit=20&offset=0" \
  -H "X-API-Key: $EIGHTSCAN_API_KEY" | jq .

Parameters: limit (1-100, default 20), offset, chainId, ownerAddress, protocol, sortBy, sortOrder.

2. Get Agent Details

curl -s "https://www.8004scan.io/api/v1/public/agents/{chainId}/{tokenId}" \
  -H "X-API-Key: $EIGHTSCAN_API_KEY" | jq .

Returns full agent profile: name, description, endpoints, metadata, reputation, owner.

3. Search Agents

curl -s "https://www.8004scan.io/api/v1/public/agents/search?q=code+review&limit=10" \
  -H "X-API-Key: $EIGHTSCAN_API_KEY" | jq .

Parameters: q (search query), limit, offset, chainId, semanticWeight (0-1, balance keyword vs semantic).

4. Account Agents

curl -s "https://www.8004scan.io/api/v1/public/accounts/{address}/agents" \
  -H "X-API-Key: $EIGHTSCAN_API_KEY" | jq .

Address format: ^0x[a-fA-F0-9]{40}$. Returns agents owned by the wallet.

5. Platform Stats

curl -s "https://www.8004scan.io/api/v1/public/stats" \
  -H "X-API-Key: $EIGHTSCAN_API_KEY" | jq .

Global statistics: total agents, chains, feedbacks, recent activity.

6. Supported Chains

curl -s "https://www.8004scan.io/api/v1/public/chains" \
  -H "X-API-Key: $EIGHTSCAN_API_KEY" | jq .

Returns all blockchain networks supported by 8004scan.

7. Feedbacks

curl -s "https://www.8004scan.io/api/v1/public/feedbacks?limit=20" \
  -H "X-API-Key: $EIGHTSCAN_API_KEY" | jq .

Parameters: limit, offset, minScore (0-5), maxScore (0-5).

---

Response Format

All responses follow a consistent structure:

{
  "success": true,
  "data": { ... },
  "meta": {
    "version": "1.0",
    "timestamp": "2026-03-16T00:00:00Z",
    "requestId": "uuid",
    "pagination": { "limit": 20, "offset": 0, "total": 100 }
  }
}

Error responses:

{
  "success": false,
  "error": {
    "code": "RateLimitExceeded",
    "message": "Rate limit exceeded",
    "details": { ... }
  }
}

---

Standard Patterns

Pagination

All list endpoints support limit + offset. Default limit: 20, max: 100. To iterate:

# Page 1
curl -s "https://www.8004scan.io/api/v1/public/agents?limit=100&offset=0" | jq .
# Page 2
curl -s "https://www.8004scan.io/api/v1/public/agents?limit=100&offset=100" | jq .

Filtering by Chain

Most endpoints accept chainId parameter to scope results to a specific network:

# Only Base Mainnet agents
curl -s "https://www.8004scan.io/api/v1/public/agents?chainId=8453" | jq .

Combining Search with Filters

# Semantic search on Ethereum mainnet
curl -s "https://www.8004scan.io/api/v1/public/agents/search?q=defi+trading&chainId=1&semanticWeight=0.7" | jq .

Error Handling

• 400 BadRequest — Check query parameters
• 404 NotFound — Verify chainId and tokenId exist
• 429 RateLimitExceeded — Wait for X-RateLimit-Reset, or upgrade API tier
• 500 InternalError — Retry after brief delay

---

Examples

Example 1: Discover agents User: "Find AI agents that do code review"

curl -s "https://www.8004scan.io/api/v1/public/agents/search?q=code+review&limit=10" | jq '.data'

→ Show results as table: Agent ID, Name, Chain, Description.

Example 2: Agent details User: "Show me agent 8453:17"

curl -s "https://www.8004scan.io/api/v1/public/agents/8453/17" | jq '.data'

→ Display full profile with endpoints, reputation, owner.

Example 3: Platform overview User: "How many agents are registered?"

curl -s "https://www.8004scan.io/api/v1/public/stats" | jq '.data'

→ Report total agents, active chains, feedback count.

Example 4: Owner lookup User: "What agents does 0x1234...abcd own?"

curl -s "https://www.8004scan.io/api/v1/public/accounts/0x1234...abcd/agents" | jq '.data'

→ List all agents owned by the wallet address.

Example 5: Chain exploration User: "Which chains does 8004scan support?"

curl -s "https://www.8004scan.io/api/v1/public/chains" | jq '.data'

→ List all supported blockchain networks with chain IDs.