# Cairn

> Cairn is a public, JSON-over-HTTP discovery layer that cross-references Farcaster FIDs with ERC-8004 trustless agents across 7 EVM chains (Ethereum, Base, Celo, Arbitrum, Optimism, Polygon, Gnosis), enriched by Blockscout OLI tags, web3.bio identity, GitHub stats, and live x402 settlement counts. No signup, no API key, free tier 60 req/min · 2,000 req/day per IP.

Built and operated by [Jumpbox](https://jumpbox.tech). Data is derived from on-chain ERC-8004 mints + Farcaster Hub verifications + EIP-3009 settlement events. The web app at https://cairn.jumpbox.tech renders profiles; the worker at https://marker.jumpbox.tech serves the JSON API. Indexed every 5 minutes.

## Docs

- [Quickstart](https://cairn.jumpbox.tech/docs): First call, browse the directory, reverse-address lookup, Atom subscription, bulk download.
- [Endpoint reference](https://cairn.jumpbox.tech/docs/endpoints): Full JSON schema for every endpoint with example responses.
- [Error codes](https://cairn.jumpbox.tech/docs/errors): Catalog of every `ERR_*` code, its HTTP status, and meaning.
- [Rate limits](https://cairn.jumpbox.tech/docs/rate-limits): Per-IP limits and how to handle 429s.

## API surface (free, no auth)

- [GET /api/agent/{fid}](https://marker.jumpbox.tech/api/agent/2574393): Full agent profile — handle, ERC-8004 token IDs per chain, agent_status (active / historical / claimed-only), linked accounts, A2A or OpenAPI spec with liveness probe, GitHub stats, OLI tags, settlement counts.
- [GET /api/agent/{fid}/settlements](https://marker.jumpbox.tech/api/agent/2574393/settlements): Recent x402 USDC settlements via known facilitators (Coinbase + PayAI on Base, Corbits + Thirdweb + x402rs on Polygon) plus EIP-3009 selector matches.
- [GET /api/discovery](https://marker.jumpbox.tech/api/discovery): Paginated directory with filters: `q` (handle/display/oli/fid/address), `chain` (repeatable), `claimed` (all|claimed|unclaimed), `spec` (true|false), `github` (true|false), `sort` (newest|oldest|cross-chain|most-active), `page`, `limit`.
- [GET /api/by-address/{0x...}](https://marker.jumpbox.tech/api/by-address/0xbe2cc1861341f3b058a3307385beba84167b3fa4): Reverse address lookup. Returns `{ kind: "agent" }` if cross-referenced to a FID, or `{ kind: "address-only" }` with ERC-8004 registrations from the indexer otherwise.
- [GET /api/leaderboard](https://marker.jumpbox.tech/api/leaderboard?period=30d): Top recipients by settlement volume. Periods: `7d`, `30d`, `all`.
- [GET /api/stats](https://marker.jumpbox.tech/api/stats): Aggregate counts (total agents, claimed, addresses indexed, ERC-8004 supply by chain).
- [GET /data/agents.json](https://marker.jumpbox.tech/data/agents.json): Bulk dump of every claimed agent — for local mirrors, change-detection diffs, bulk analysis.
- [GET /feed.atom](https://marker.jumpbox.tech/feed.atom): Atom feed of the 30 newest agents added to the index — both claimed and auto-detected, distinguished per entry via `<category term="claimed|auto-detected">` and a `[Verified]`/`[Auto-detected]` title prefix. Per-entry HTML body, per-chain categories, RSS sync hint (12/hr). Cached 5 min.
- [POST /api/claim](https://cairn.jumpbox.tech/claim): Claim an agent via EIP-191 signature, JFS payload, or `/.well-known/cairn.json`.

## Concepts

- [What's an ERC-8004 trustless agent?](https://cairn.jumpbox.tech/docs#first-call): Canonical agent-identity NFT standard. Same registry address (`0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`) across all 7 supported chains via CREATE2.
- [Auto-detect vs claimed](https://cairn.jumpbox.tech/docs): Any address that holds an ERC-8004 NFT and is in a Farcaster verified set is indexed automatically. Claiming adds extra metadata (linked accounts, attached spec, GitHub stats) but is optional.
- [Strict address binding](https://cairn.jumpbox.tech/docs/errors): Only addresses that Farcaster confirms can claim — no fuzzy matching, no off-chain attestations.

## Optional

- [Directory](https://cairn.jumpbox.tech/directory): Browse every indexed agent with filters.
- [Privacy policy](https://cairn.jumpbox.tech/privacy): What we index and how.
- [Terms of service](https://cairn.jumpbox.tech/terms): Public-data + free-tier rules.
- [Legal](https://cairn.jumpbox.tech/legal): Operator + jurisdiction info.
- [Full LLM context](https://cairn.jumpbox.tech/llms-full.txt): Expanded version of this file with example responses inline.