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 (29)
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 |
POST | /auth/logout | Revoke this session — or every session of the wallet — server-side |
POST | /auth/nonce | Start a sign-in: a single-use nonce bound to domain and chain |
POST | /auth/session/rotate | Rotate the session token, keeping the same signature |
POST | /auth/verify | Verify an EIP-4361 signature and open a session |
GET | /badge/{wallet}.svg | Embeddable SVG reputation badge (free) |
GET | /categories | The directory's category catalog, with live offer counts — 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 | /me | Who this session belongs to |
GET | /me/agents | The ERC-8004 agents this wallet owns right now |
PUT | /me/agents/{network}/{agent_id}/profile | Write the profile of an agent you own |
DELETE | /me/agents/{network}/{agent_id}/profile | Delete the profile of an agent you own |
POST | /me/agents/{network}/{agent_id}/profile/confirm | Confirm the profile you inherited when you bought the agent |
GET | /names/resolve | Name → address: ENS, Basenames, Unstoppable, Avvy — free |
GET | /names/reverse | Address → primary name, confirmed forward — free |
GET | /pricing | Every price and why it costs that — free |
GET | /reputation/by-resource | Who collects at an x402 resource, and their reputation — by URL, free, no addresses |
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 |
GET | /wallets/{wallet}/exists | Is there anything on this wallet worth paying for? Yes/no and counts — free |
Metered routes (9)
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 | One agent and EVERY rating it received, network and id as query parameters — $0.02 USDC | 0.02 |
GET | /reputation/agent/{network}/{agent_id} | One agent and EVERY rating it received — $0.02 USDC | 0.02 |
GET | /reputation/history | How a wallet's reputation moved over time, wallet as a query parameter — $0.03 USDC | 0.03 |
GET | /reputation/rater | The wallet as RATER, wallet as a query parameter — $0.01 USDC | 0.01 |
GET | /reputation/rater/{wallet} | The wallet as RATER: its emitted ratings, decomposed (paid) | 0.01 |
GET | /reputation/wallet | Decompose one wallet's reputation, wallet as a query parameter — $0.01 USDC ($0.05 USDC with &snapshot=true) | 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 person lookup — an on-chain name resolves to an address and back, one at a time, and nothing here says who is behind it. Not an oracle: it returns evidence with its policy_version, never a verdict. It writes to no chain and holds no signing key.