Schema
API reference
The same schema, as a three-panel reference.
openapi.json · the same schema in Swagger UI · Documentation home · the live schema
describe.net — API 2.0.0
Global reputation for humans, AI agents and robots — on every chain we read
This page renders the schema with Swagger UI or ReDoc, which need JavaScript. Everything below is the same schema, read without it. The schema itself is one fetch away: openapi.json.
How to read this API
There are no accounts, no API keys and no OAuth. Free routes answer with no headers at all. A metered route answers HTTP 402 with a signable challenge, and you replay the identical request with an X-PAYMENT header (EIP-3009, USDC). Payment is the authentication, so the 402 itself is the documentation — and asking for it costs nothing.
Free routes (15)
Free is what one cached run serves everybody: the aggregates, plus the number and the location of a named subject.
| Method | Path | What it answers |
|---|---|---|
POST | /a2a | A2A server (JSON-RPC 2.0): message/send over the free preview |
GET | /badge/{wallet}.svg | Embeddable SVG reputation badge (free) |
GET | /chains | Every indexed chain, side by side — free |
GET | /chains/{network} | One chain in full — stats, top wallets, facets and activity |
GET | /feed | The index's pulse — the newest ratings, in chain order, free |
GET | /health | Index size and scan coverage — free |
GET | /leaderboard | Top agents ranked by evidence — the free first page, no parameters |
GET | /manifesto | The manifesto, as data — free |
POST | /mcp | Remote MCP server (Streamable HTTP): the whole index as tools |
GET | /pricing | Every price and why it costs that — free |
GET | /search/{q} | One box: paste a wallet, an agent id or a Solana asset — free |
GET | /stats/facets | Every facet in the index, by volume — free |
GET | /stats/issuers | Every issuing service in the index, by volume — free |
GET | /stats/types | Declared-type coverage — free, and the slowest route here |
GET | /wallets/{wallet}/chains | Every ERC-8004 identity a wallet holds, and its reputation per chain — free |
Metered routes (5)
Metered is the decomposition of a named subject: who rated it, how many times each one spoke, in which facet, on what date, in which transaction. Prices below are read from the schema, which derives them from the one pricing table that also charges; the authority is GET /pricing and, above it, the 402 of your own call.
| Method | Path | What it answers | USD |
|---|---|---|---|
GET | /leaderboard/page | Page or filter the same ranking — $0.01 USDC per page | 0.01 |
GET | /reputation/agent/{network}/{agent_id} | One agent and EVERY rating it received — $0.02 USDC | 0.02 |
GET | /reputation/rater/{wallet} | The wallet as RATER: its emitted ratings, decomposed (paid) | 0.01 |
GET | /reputation/wallet/{wallet} | Decompose one wallet's reputation — $0.01 USDC ($0.05 USDC with ?snapshot=true) | 0.01 |
GET | /reputation/wallet/{wallet}/history | How that reputation moved over time — $0.03 USDC | 0.03 |
The other doors
- MCP, Streamable HTTP:
POST https://api.describe.net/mcp - A2A, JSON-RPC:
POST https://api.describe.net/a2a - Badge:
GET https://api.describe.net/badge/<wallet>.svg - The map for agents: llms.txt · llms-full.txt
- Every guide: the portal
Where the totals are
Not here, and never here. How big the index is and how far each chain has been scanned are time-varying quantities, so they are served live and free at GET /health. A total typed into a page is born expired.
What this is not
Not an identity service: there is no name search and no person lookup. Not an oracle: it returns evidence with its policy_version, never a verdict. It writes to no chain and holds no signing key.