# BRAINROT Community Public Interface (CPI)

> A public, read-only HTTP API over the BRAINROT collection's on- and
> off-chain data, the AI Court reference data (judges & lawyers), and every
> specimen's verdict (standing, score, ruling, transcript).
> 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.
Adds a `stats` object aggregating every trial this judge presided:
- trial_count (integer)
- avg_score, min_score, max_score (integer, 0..1000)
- immortal_count (integer) — tokens this judge scored into IMMORTAL
- standing_counts (object) — tier name → count
(`stats` is null if the court verdict data is unavailable.)

### 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.
Adds a `stats` object aggregating every trial this lawyer argued (same shape
as the judge stats: trial_count, avg_score, min_score, max_score,
immortal_count, standing_counts). Null if verdict data is unavailable.

### GET /v1/verdicts
The AI Court's verdict on each specimen — one row per token. Filterable and
paginated over the whole 10,000-token corpus.
Filters (all optional, composable):
- ?standing=       one tier (case-insensitive): IMMORTAL, EXEMPLARY, MEMORABLE,
                   NOTED, COOKED, SLOP, DEATH SENTENCE
- ?min_score= / ?max_score=   integer bounds, 0..1000
- ?judge=          judge id (e.g. J07; case-insensitive)
- ?lawyer=         lawyer id (matches the advocate OR the adversary)
- ?pair=           mirror-pair id (e.g. P16)
- ?zeitgeist=true|false        ZEITGEIST flagship tokens (9901-10000) only / excluded
- ?sort=           score_desc (default) | score_asc | token_asc | token_desc
- ?limit= (1-100), ?offset=
Array item fields:
- token_id (integer)
- score (integer, 0..1000) — the memetic score
- standing (string) — IMMORTAL | EXEMPLARY | MEMORABLE | NOTED | COOKED | SLOP | DEATH SENTENCE
- is_zeitgeist (boolean)
- judge_id (string, uppercase e.g. J07) — resolve via /v1/judges/:id
- advocate_id (string, e.g. L01A) — argued FOR the token; resolve via /v1/lawyers/:id
- adversary_id (string, e.g. L01D) — argued AGAINST
- pair_id (string, e.g. P16)
- ruling_headline (string) — quotable one-line verdict
Cast ids are returned uppercase, matching /v1/judges & /v1/lawyers.

### GET /v1/verdicts/:tokenId
One token's full verdict. 404 if the token has no trial on record.
Fields: everything from the list item above, plus:
- narrative_ruling (string) — the full prose ruling
- attributes (array of { trait_type, value }) — the token's on-chain traits
- transcript (array) — the beat-by-beat trial; ONLY included with
  ?include=transcript (each beat: { phase, speaker_id, speaker_name,
  speaker_role, text }).

### GET /v1/verdicts/standings
Corpus-wide tier distribution + score summary. Returns one object:
- standings (object) — tier name → count, across all judged tokens
- score (object) — total_trials, zeitgeist_count, min_score, max_score,
  avg_score, median_score
- total (integer) — total judged tokens

### GET /v1/verdicts/leaderboard
Wallets ranked by the verdict quality of the collection they hold (combines
on-chain ownership with verdicts). Query:
- ?sort=court_points (default) | immortals | avg_score
- ?min_tokens=     only wallets holding at least N judged tokens
- ?limit= (1-100), ?offset=
Array item fields:
- rank (integer)
- wallet (string address)
- tokens_judged (integer)
- court_points (integer) — weighted tier sum (IMMORTAL 6, EXEMPLARY 5,
  MEMORABLE 4, NOTED 3, COOKED 2, SLOP 1, DEATH SENTENCE 0)
- immortals (integer)
- avg_score (integer)
- standings (object) — tier name → count within the wallet

### 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[] }.

### GET /v1/holders/:wallet/verdicts
A wallet's collection summarised by court verdict.
Returns one object:
- wallet (string)
- tokens_owned (integer), tokens_judged (integer)
- standings (object) — tier name → count within the wallet
- immortals (integer)
- avg_score (integer, nullable)
- best (object, nullable) — the wallet's highest-scored piece:
  { token_id, standing, score, ruling_headline }

  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"

    # One token's verdict (standing, score, ruling)
    curl https://cpi.brainrot.works/v1/verdicts/9973 -H "Authorization: Bearer cpi_live_xxx"

    # A token's verdict WITH the full trial transcript
    curl "https://cpi.brainrot.works/v1/verdicts/9973?include=transcript" -H "Authorization: Bearer cpi_live_xxx"

    # Every IMMORTAL, highest score first
    curl "https://cpi.brainrot.works/v1/verdicts?standing=IMMORTAL&sort=score_desc" -H "Authorization: Bearer cpi_live_xxx"

    # Corpus-wide tier distribution
    curl https://cpi.brainrot.works/v1/verdicts/standings -H "Authorization: Bearer cpi_live_xxx"

    # Wallets with the best-judged collections
    curl "https://cpi.brainrot.works/v1/verdicts/leaderboard?sort=immortals" -H "Authorization: Bearer cpi_live_xxx"

    # Judge J01's real record (profile + trial stats)
    curl https://cpi.brainrot.works/v1/judges/J01 -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 next to
  their REAL record (/v1/judges/:id stats); "which judges reward cursedness vs
  cuteness," and which actually hand out the most IMMORTALs.
- Verdict lookup: any token's standing + score + ruling by number
  (/v1/verdicts/:tokenId), with the full trial transcript on demand.
- Standings board: the whole corpus by tier + a score histogram
  (/v1/verdicts/standings); filterable galleries of every IMMORTAL or
  DEATH SENTENCE (/v1/verdicts?standing=).
- Best-collection leaderboard: rank wallets by the court quality of what they
  hold (/v1/verdicts/leaderboard) — most IMMORTALs, highest average score.
- Holder verdict card: a wallet's standing breakdown + best-judged piece
  (/v1/holders/:wallet/verdicts) — a shareable "court resume".
- Judge/lawyer scorecards: harshest judge, whose advocacy lands the highest
  scores, per-tier win rates — from /v1/judges/:id & /v1/lawyers/:id stats.
- 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.

### GET /v1/lab/rules
The BRAINROT Lab's COMPLETE MECHANICS RULESET — burn-value formulas, stamp
derivation, trait-bank pricing, nuke tiers, edition caps, legendary rules and
a step-by-step valuation guide (e.g. to rank tokens by burn value). Generated
live from the Lab worker's own code constants, so it is always current.
Returns `{ "data": { ...ruleset } }`. Add `?format=md` for markdown prose.
KEYLESS DIRECT SOURCE (same content, no API key needed):
- https://lab-api.brainrot.works/rules.json  (structured)
- https://lab-api.brainrot.works/rules       (markdown)
Related public Lab endpoints (keyless):
- https://api.brnrt.dev/metadata/{id}                — token attributes (Standing, Evolutions, Bank Grafts, Rarity Tier)
- https://lab-api.brainrot.works/burn/stamps/{id}    — history-derived stamp yield at burn
- https://lab-api.brainrot.works/catalog/library     — trait catalog: caps + live supply
- https://lab-api.brainrot.works/embed/{id}          — the token's interactive marketplace card