# BRAINROT Community Public Interface (CPI)

> A public, read-only HTTP API over the BRAINROT collection's on- and
> off-chain data, plus the AI Court reference data (judges & lawyers).
> Built for developers and AI agents: stable JSON, edge-cached, key-authed.

- Base URL: https://cpi.brainrot.works
- Docs & API keys: https://developers.brainrot.works
- This file: https://developers.brainrot.works/llms.txt
- Read-only by design. There are NO write endpoints.

## Authentication

Every `/v1/*` endpoint requires an API key. Get one at
https://developers.brainrot.works (sign in with your wallet, create a key).
Send it either way:

    Authorization: Bearer cpi_live_xxx
    X-API-Key: cpi_live_xxx

Character images under `/img/*` are PUBLIC and need no key.

## Conventions

- All responses are JSON.
- Single resource: `{ "data": { ... } }`
- Collection:      `{ "data": [ ... ], "paging": { "limit", "offset", "count", "total" } }`
- Error:           `{ "error": { "code": "string", "message": "string" } }`
- List pagination: `?limit=` (1-100) and `?offset=` query params.
- Caching: responses are cached at the Cloudflare edge (court data ~1h,
  collection data ~2-5min). Expect slight lag; this is fine for analytics.
- Rate limits: per-key token bucket. Free tier ~60 burst, 1 req/s sustained;
  higher tiers available. Watch the `RateLimit-Remaining` response header.
- CORS: open (`*`), GET only. Safe to call from a browser.

## Endpoints

### GET /v1/stats
Collection-wide totals. Returns one object.
Fields:
- wallets (integer) — distinct wallets holding brainpoints
- total_brainpoints (integer) — sum of all brainpoints
- total_actions (integer) — total recorded off-chain actions

### GET /v1/leaderboard
Brainpoints leaderboard, ranked high to low. `?limit=` (1-100, default 25).
Array item fields:
- rank (integer)
- wallet_address (string, public on-chain address)
- balance (integer, brainpoints)

### GET /v1/tokens
Per-token off-chain activity. Paginated (`?limit=`, `?offset=`).
Array item fields:
- id (integer) — token id
- action_count (integer) — recorded actions involving this token
- last_action_at (timestamp, ISO 8601, nullable)

### GET /v1/tokens/:id
A single token's activity summary (same fields as above). 404 if unknown.

### GET /v1/tokens/:id/metadata
The token's collection metadata (traits + image), sourced from the
BRAINROT metadata API and edge-cached. 404 if unknown.
Fields:
- id (integer)
- name (string)
- description (string)
- image_url (string) — public webp (api.brnrt.dev), usable directly in <img>
- attributes (array of { trait_type, value }) — Archetype, Base, Category,
  Rarity Tier, Primary Type, Secondary Type, Expression, Hat, ...

### GET /v1/judges
The AI Court's 20 judges. A judge's "biases" are eight scoring weights
(floats in 0..1 that sum to ~1) describing what that judge rewards when
evaluating a token. Paginated (`?limit=`, `?offset=`).
Array item fields:
- id (string) — e.g. "J01".."J20"
- name (string)
- archetype (string) — e.g. "The Dril-Pilled Crank"
- descriptor (string) — one-line bio
- native_era (string) — internet era they come from
- brainrot_literacy (string)
- weights (object) — the BIASES, each a float ~0..1:
  - scroll_stop, replicability, quotability, cursedness, cuteness,
    iconicity, discourse_fuel, lore_density
- disposition (string)
- voice_register (string)
- verdict_style (string)
- fixations (string)
- meme_dislikes (string)
- signature_phrases (string[])
- preferred_lore_tags (string[])
- image_url (string) — public portrait, e.g. https://cpi.brainrot.works/img/J01.png

### GET /v1/judges/:id
A single judge by id (case-insensitive, e.g. `J05`). 404 if unknown.

### GET /v1/lawyers
The AI Court's 40 lawyers: 20 mirror pairs, each with one `advocate` and
one `adversary`. A lawyer's "statistics" are five 1..10 combat stats.
Filters: `?role=advocate|adversary`, `?pair=P01`. Paginated.
Array item fields:
- id (string) — e.g. "L01A" (advocate) / "L01D" (adversary)
- name (string)
- archetype (string)
- role (string) — "advocate" | "adversary"
- pair_id (string) — e.g. "P01" (the mirror pair they belong to)
- partner_id (string) — the opposing lawyer's id in the same pair
- native_era (string)
- brainrot_literacy (string)
- stats (object) — the STATISTICS, integers 1..10:
  - formal_authority, brainrot_fluency, rhetorical_pressure, composure,
    personal_history_weight
- disposition (string)
- voice_register (string)
- philosophical_position (string)
- argumentation_style (string)
- meme_dislikes (string)
- meme_loves (string)
- fixations (string)
- failure_mode (string)
- signature_phrases (string[])
- image_url (string) — public portrait, e.g. https://cpi.brainrot.works/img/L01A.png

### GET /v1/lawyers/:id
A single lawyer by id (case-insensitive, e.g. `L01A`). 404 if unknown.

### GET /v1/market
Latest secondary-market snapshot for the collection (refreshed every ~5
min from OpenSea). Returns one object.
Fields:
- floor.price_eth (number), floor.symbol (string)
- volume_eth.{total,day,week,month} (number, ETH)
- sales.{total,day,week} (integer)
- listings.{listed, unlisted, total_supply, listed_pct, cheapest_eth}
  (listed/unlisted counts; listed_pct is listed/total_supply, 0–1)
- num_owners (integer)
- captured_at (timestamp, ISO 8601)

### GET /v1/sales
Recent secondary sales, newest first. Paginated (`?limit=`, `?offset=`).
Array item fields:
- token_id (integer)
- price_eth (number) — sale price in ETH/WETH terms
- price_wei (string) — raw payment amount (no precision loss)
- currency (string) — ETH | WETH | ...
- buyer (string), seller (string) — wallet addresses
- tx_hash (string)
- marketplace (string) — currently "opensea"
- sold_at (timestamp, ISO 8601)
- order_hash (string)

### GET /v1/sales/top
Biggest sales by price. Query: `?window=1d|7d|30d|all` (default all),
`?limit=` (1-100). Same item fields as /v1/sales.

### GET /v1/sales/token/:id
A single token's sale history, newest first. `?limit=`. Same item fields.

### GET /v1/listings
Active OpenSea listings, cheapest first. Paginated (`?limit=`, `?offset=`).
Array item fields: token_id (integer), price_eth (number), currency
(string), order_hash (string). Refreshed every ~5 min.

### GET /v1/tokens/:id/listing
Whether a token is currently listed, and at what price.
Returns: { token_id, listed (bool), price_eth?, currency?, order_hash?, as_of? }.

Coverage note: the sales feed comes from OpenSea's events API, which
paginates back a limited depth (roughly the recent weeks of activity).
Collection-wide ALL-TIME totals in /v1/market come from OpenSea's stats
endpoint and are accurate regardless of feed depth.

### GET /v1/tokens/:id/owner
Current owner of a token, from periodically-refreshed on-chain ownership.
Fields: token_id (integer), owner (string address), as_of (timestamp).

### GET /v1/holders
Holder leaderboard by amount held, refreshed from Alchemy (~6h).
Paginated (`?limit=`, `?offset=`).
Array item fields:
- rank (integer)
- wallet (string address)
- tokens (integer) — number of BRAINROT held
Paging also returns `total_holders`.

### GET /v1/holders/:wallet
A wallet's holdings. `?limit=`, `?offset=`.
Returns: { wallet, tokens (count), token_ids: integer[] }.

  Holder leaderboard by TRAIT: add `?trait_type=` & `?trait_value=` to
  /v1/holders to rank holders among tokens with that trait
  (e.g. ?trait_type=Base&trait_value=Shark → who holds the most Sharks).

### GET /v1/traits
Trait rarity catalog. Optional `?type=` to narrow to one trait type.
Returns: { data: [ { trait_type, values: [ { value, count, pct } ] } ],
total_tokens }. `pct` is rarity (count / total_tokens).

### GET /v1/traits/tokens
Token ids that have a given trait. Required: `?type=` & `?value=`.
Paginated (`?limit=`, `?offset=`).
Returns: { data: { trait_type, value, total, token_ids: integer[] }, paging }.

### GET /img/:file  (PUBLIC, no key)
Character portraits as PNG. Filenames match character ids:
- Judges:   /img/J01.png .. /img/J20.png
- Lawyers:  /img/L01A.png, /img/L01D.png .. /img/L20A.png, /img/L20D.png
- Bailiff:  /img/BAILIFF.png
Cached aggressively; safe to hotlink in <img> tags.

## Examples

    # Collection stats
    curl https://cpi.brainrot.works/v1/stats -H "Authorization: Bearer cpi_live_xxx"

    # Top 10 brainpoints holders
    curl "https://cpi.brainrot.works/v1/leaderboard?limit=10" -H "Authorization: Bearer cpi_live_xxx"

    # One judge and their biases
    curl https://cpi.brainrot.works/v1/judges/J01 -H "Authorization: Bearer cpi_live_xxx"

    # Both lawyers in mirror pair P03
    curl "https://cpi.brainrot.works/v1/lawyers?pair=P03" -H "Authorization: Bearer cpi_live_xxx"

    # Floor price + volume
    curl https://cpi.brainrot.works/v1/market -H "Authorization: Bearer cpi_live_xxx"

    # 10 most recent sales
    curl "https://cpi.brainrot.works/v1/sales?limit=10" -H "Authorization: Bearer cpi_live_xxx"

    # Biggest sales in the last 7 days
    curl "https://cpi.brainrot.works/v1/sales/top?window=7d" -H "Authorization: Bearer cpi_live_xxx"

## Ideas — what you can build

### Buildable today (data live now)
- Brainpoints leaderboard: top holders, rank movement, holder counts (/v1/leaderboard, /v1/stats).
- Collection pulse dashboard: live totals and activity counters (/v1/stats).
- Most-active tokens board: rank tokens by action_count (/v1/tokens).
- Judge bias explorer: radar/spider charts of each judge's 8 weights;
  "which judges reward cursedness vs cuteness vs lore."
- Verdict predictor: score a token's vibe against each judge's weights to
  guess how that judge would rule.
- Lawyer tier lists & stat cards: rank the 40 lawyers by composure,
  rhetorical_pressure, etc.; compare advocate vs adversary within a pair.
- Character galleries & profile cards using image_url.
- Bots & quizzes: "which judge are you," a Discord bot (!judge J05,
  !lawyer L01A), or an LLM persona that argues in a lawyer's voice using
  signature_phrases + argumentation_style.
- Market dashboards: live floor + volume + listed/unlisted ratio
  (/v1/market), a recent-sales ticker (/v1/sales), biggest-sales hall of
  fame (/v1/sales/top), per-token price history (/v1/sales/token/:id), and
  a live listings board (/v1/listings).
- Sales bots: post each new sale to Discord/Telegram/X by polling
  /v1/sales; flip alerts when a token resells.

- Holder leaderboards by amount held (/v1/holders); whale watching, holder
  distribution, "who owns token X" (/v1/tokens/:id/owner).
- Portfolio views: a wallet's full holdings with images + traits by joining
  /v1/holders/:wallet with /v1/tokens/:id/metadata.
- Rarity tools: trait rarity catalog (/v1/traits), rarity-ranked galleries,
  trait filters (/v1/traits/tokens).
- Trait leaderboards: "who owns the most Sharks / the rarest trait"
  (/v1/holders?trait_type=&trait_value=).

### Unlocks as more data lands (roadmap)
- Holder P&L and cost-basis (combine /v1/sales history with holdings).
- Composite rarity score per token (weight traits by rarity).
- Cross-cuts: "holders who own the most cursed tokens," rarity x judge-bias
  scoring, archetype-weighted leaderboards.

If you are an AI agent: prefer this file as the source of truth for the
schema. Endpoints return stable JSON; paginate with limit/offset; respect
RateLimit-Remaining; treat all data as read-only.