describe API — live schema

Global reputation for humans, AI agents and robots — on every chain we read

Base URL https://api.describe.net (also reachable as /v1, same contract). Version 2.0.0. Prices: GET /pricing (free) — the 402 of your own call is the final authority.

Authentication

Authentication is payment (x402): no accounts, no API keys, no sign-up.

1. Call a metered route. It answers HTTP 402 with a challenge (accepts[]: network, USDC amount, recipient).
2. Sign an EIP-3009 USDC authorization for that amount on one of the accepted networks.
3. Repeat the same call with the signed payment in the X-PAYMENT header; the response carries X-Payment-Receipt. A retry with the same header is not charged twice (X-Payment-Reused: true).

Full contract: auth.md. Free routes need nothing at all.

Endpoints

• GET /health — free
• GET /pricing — free
• POST /a2a (A2A message/send: el preview gratis, por JSON-RPC) — free
• POST /mcp (MCP Streamable HTTP: las catorce tools; las pagas relayan el 402 de su ruta) — free
• GET /api (402 informativo: el challenge vivo, como documentación) — free
• GET /.well-known/oauth-protected-resource — free
• GET /manifesto — free
• GET /wallets/{wallet}/chains — free
• GET /badge/{wallet}.svg — free
• GET /search/{query} — free
• GET /chains — free
• GET /feed — free
• GET /leaderboard (primera página) — free
• GET /leaderboard/page/? — $0.01 via x402
• GET /stats/facets — free
• GET /stats/types — free
• GET /stats/issuers — free
• GET /reputation/wallet/[^/]+/? — $0.05 via x402
• GET /reputation/wallet/[^/]+/? — $0.01 via x402
• GET /reputation/wallet/[^/]+/history/? — $0.03 via x402
• GET /reputation/rater/[^/]+/? — $0.01 via x402
• GET /reputation/agent/[^/]+/[^/]+/? — $0.02 via x402

Example

curl https://api.describe.net/wallets/0x715dc035ffb97dd7bb4095c6670138ba05bb4e6d/chains   # free preview
curl -i https://api.describe.net/reputation/wallet/0x715dc035ffb97dd7bb4095c6670138ba05bb4e6d  # 402 challenge
curl "https://api.describe.net/feed?network=base&limit=5"                                        # free, one chain

Errors

• 402 — payment required: the body is the challenge to pay; not an error of your request.
• 422 — invalid parameter (out-of-range limit, unknown network: the body lists known_networks).
• 429 — HTTP 429 from the gateway before the application runs; back off and retry
• 404 — unknown route or unknown chain; a wallet with no data is not a 404: it answers 200 with null scores.

Versioning and rate limits

semver — info.version (no path or header versioning; every route is the current contract). Breaking changes: major bump + new API_VERSION, never silent; a served field changing type is breaking, a new optional field is not. Every scored response carries policy_version. Every response carries API-Version and RateLimit-Policy headers.

Rate limit: 50 requests/s sustained, burst 40, enforced at API Gateway (edge), per stage. CloudFront-cached free routes do not consume the budget on a cache hit. A None above means this build was not told the gateway's numbers (they come from its own configuration, not from this code): read the RateLimit-Policy header of any response, which always carries the live ones.

Machine-readable

openapi.json (live) · openapi.json (sealed, citable) · llms.txt (documentation hub) · llms.txt (site) · skill.md · MCP server card (remote MCP: POST https://api.describe.net/mcp) · A2A agent card. Interactive explorer below (requires JavaScript).