live/stable

API

The KYA check and the public, read-only JSON and SSE endpoints behind the census, with generated field tables.

Base URL: https://api.recensus.xyz — public, read-only, CORS open, 120 requests a minute per IP. OpenAPI at /openapi.json.

The check is GET /v1/kya/:subject: free up to 100 a day without a key and 1,000 with one. Keys, quotas, pay per check and webhooks are on KYA API; the answer's fields are on The check.

Conventions: money as strings (USD8, or the token's base units) plus display; addresses lowercase hex; every response carries asOfBlock and asOfTime; fields are added between versions, never removed within one.

Route	Returns
`GET /v1/headline`	Agents, transactions and USD moved over 24h, 7d and all time, with the claimed/unclaimed split.
`GET /v1/frameworks?window=`	Frameworks by active agents. Windows: 24h, 7d, 30d, all.
`GET /v1/dapps?window=`	Contracts agents used. Unmapped targets are grouped as "other".
`GET /v1/feed?limit=&cursor=`	Recent agent transactions, newest first, with a stable cursor.
`GET /v1/agents/:id`	One agent: totals (USD, and native ETH beside it as ethWei, never in the USD), dapp breakdown, and unclaimed use of its ID.
`GET /v1/agents/:id/txs`	That agent's transactions.
`GET /v1/agents/:id/series`	That agent over time.
`GET /v1/series?metric=&step=`	The chain over time. metric: agents, txs, usd. step: hour, day.
`GET /v1/kya/:subject`	A KYA check of an address, agent ID or ERC-8004 token ID: the agent, who stands behind it, its track record, its stake, its history and its flags. Free up to a daily quota; see KYA API.
`POST /v1/kya/webhooks`	With a key: watch agents for tier and flag changes, delivered signed. GET lists, DELETE /v1/kya/webhooks/:id stops one.
`POST /v1/share/event`	Body { kind, ref }: adds one to the count of permalink views or share clicks for the day (permalink, share_x, copy_link, embed). A number per day and kind is kept, and nothing about the caller.
`GET /v1/verify?agentId=`	claimed, senders, tier, staked. What the agent-lane middleware asks.
`GET /v1/badge/:dapp`	agents7d and txs7d for one dapp.
`GET /v1/stream/feed`	Server-sent events: `tx` per labelled transaction, `ping` every 20 s.
`GET /v1/stream/headline`	Server-sent events: the headline on connect and on every change.
`GET /v1/top-earners?window=`	Top earners: claimed agents ranked by unflagged USDG earnings, with gross, payers, and flags with the payments behind them; no score. Windows: 7d, 30d, all.
`GET /v1/signals?limit=&cursor=`	Signals from the 7-day Top earners ranking, newest first: NEW_NUMBER_ONE, REVENUE_SPIKE, FLATLINE, NEW_ENTRY.
`GET /v1/owners/:address`	An ERC-8004 owner's agents with their Top earners rows, a shared wallet if any, and its note.
`GET /v1/health`	Freshness. "stale" when the newest indexed block is over a minute old.

reference

Route	Returns
`GET /v1/headline`	Agents, transactions and USD moved over 24h, 7d and all time, with the claimed/unclaimed split.
`GET /v1/frameworks?window=`	Frameworks by active agents. Windows: 24h, 7d, 30d, all.
`GET /v1/dapps?window=`	Contracts agents used. Unmapped targets are grouped as "other".
`GET /v1/feed?limit=&cursor=`	Recent agent transactions, newest first, with a stable cursor.
`GET /v1/agents/:id`	One agent: totals (USD, and native ETH beside it as ethWei, never in the USD), dapp breakdown, and unclaimed use of its ID.
`GET /v1/agents/:id/txs`	That agent's transactions.
`GET /v1/agents/:id/series`	That agent over time.
`GET /v1/series?metric=&step=`	The chain over time. metric: agents, txs, usd. step: hour, day.
`GET /v1/kya/:subject`	A KYA check of an address, agent ID or ERC-8004 token ID: the agent, who stands behind it, its track record, its stake, its history and its flags. Free up to a daily quota; see KYA API.
`POST /v1/kya/webhooks`	With a key: watch agents for tier and flag changes, delivered signed. GET lists, DELETE /v1/kya/webhooks/:id stops one.
`POST /v1/share/event`	Body { kind, ref }: adds one to the count of permalink views or share clicks for the day (permalink, share_x, copy_link, embed). A number per day and kind is kept, and nothing about the caller.
`GET /v1/verify?agentId=`	claimed, senders, tier, staked. What the agent-lane middleware asks.
`GET /v1/badge/:dapp`	agents7d and txs7d for one dapp.
`GET /v1/stream/feed`	Server-sent events: `tx` per labelled transaction, `ping` every 20 s.
`GET /v1/stream/headline`	Server-sent events: the headline on connect and on every change.
`GET /v1/top-earners?window=`	Top earners: claimed agents ranked by unflagged USDG earnings, with gross, payers, and flags with the payments behind them; no score. Windows: 7d, 30d, all.
`GET /v1/signals?limit=&cursor=`	Signals from the 7-day Top earners ranking, newest first: NEW_NUMBER_ONE, REVENUE_SPIKE, FLATLINE, NEW_ENTRY.
`GET /v1/owners/:address`	An ERC-8004 owner's agents with their Top earners rows, a shared wallet if any, and its note.
`GET /v1/health`	Freshness. "stale" when the newest indexed block is over a minute old.