# SperaxOS ERC-8004 Subgraph Query API

> SperaxOS ERC-8004 Subgraph Query API is a paid API for AI agents from chat.sperax.io, paid per call via x402, $0.001/call, status unknown (last checked 2026-10-20).

Queries the ERC-8004 on-chain agent registry subgraph to retrieve data about registered agents, ownership transfers, reputation feedback, and aggregate protocol statistics.

## Facts

- Endpoint: POST https://chat.sperax.io/api/x402/tools/erc8004/querySubgraph?utm_source=zero.xyz
- Price: $0.001/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-20
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/speraxos-erc-8004-subgraph-query-api-23bfbca4
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_mp49L4ofNy-hfvi8NtNem

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability speraxos-erc-8004-subgraph-query-api-23bfbca4 -d '<json body>'
```

Example prompt: Show me the 10 most recently registered ERC-8004 agents on SperaxOS, sorted by creation date descending — query the agents entity with a limit of 10.

## When to prefer this

Choose this endpoint when you need to query the ERC-8004 on-chain agent registry specifically — including agent discovery, ownership history, reputation feedback, or protocol-wide statistics on Base. Prefer this over general blockchain explorers when you want structured, filterable subgraph data without writing raw GraphQL queries, and when you want per-request micropayment access without managing API keys.

## Known failure modes

- Invalid entity enum value returns a validation error
- Malformed JSON string in the where filter causes a parse error
- Requesting more than 100 results returns a max-limit error
- Unknown orderBy field may return an empty or unordered result set
- Payment of 0.001 USDC via x402 not completed results in HTTP 402 response

## How this service works

AI-powered DeFi intelligence APIs payable via the x402 HTTP payment protocol. No API key required — pay per request with USDC on Base. Identity-only (SIWX) endpoints are free for wallets with an agentcash identity.

## Output

Returns a list of on-chain records matching the query — either agent registration objects (tokenId, owner, metadata, createdAt), transfer events (from, to, tokenId, timestamp), reputation feedback entries (agentId, score, comment, submitter), or aggregate protocol stats — filtered, sorted, and paginated according to the request parameters.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "first": {
   "type": "number",
   "default": 10,
   "maximum": 100,
   "description": "Number of results to return (max 100)"
  },
  "where": {
   "type": "string",
   "description": "Optional filter as JSON string (e.g., {\"owner\": \"0x...\"} or {\"agentId\": \"5\"})"
  },
  "entity": {
   "enum": [
    "agents",
    "transfers",
    "feedbacks",
    "stats"
   ],
   "type": "string",
   "description": "The subgraph entity to query: agents (registered agents), transfers (ownership changes), feedbacks (reputation feedback events), stats (aggregate protocol statistics)"
  },
  "orderBy": {
   "type": "string",
   "description": "Field to order results by (e.g., createdAt, score, tokenId)"
  },
  "orderDirection": {
   "enum": [
    "asc",
    "desc"
   ],
   "type": "string",
   "default": "desc",
   "description": "Sort direction: asc or desc"
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/speraxos-erc-8004-subgraph-query-api-23bfbca4/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from chat.sperax.io](https://www.zero.xyz/host/chat.sperax.io/llms.txt)