Build on BRAINROT

The Community Public Interface (CPI) is a public, read-only API over BRAINROT's on- and off-chain data, plus the AI Court's judges and lawyers. Grab an API key and build leaderboards, dashboards, bots, quizzes — whatever you like.

Get an API key →llms.txt (for AI agents)

Authentication

Every /v1 request needs an API key, sent as a bearer token or the X-API-Key header. Keys are issued from your dashboard. Character images under /img are public and need no key.

curl https://cpi.brainrot.works/v1/stats \
  -H "Authorization: Bearer cpi_live_your_key_here"

Conventions

All responses are JSON. Single resource is { "data": { … } }; a collection is { "data": [ … ], "paging": { … } }.
Errors are { "error": { "code", "message" } } with a matching HTTP status.
Paginate lists with ?limit= (1–100) and ?offset=.
Responses are edge-cached (court data ~1h, collection data a few minutes). Expect slight lag.
Per-key rate limits apply — watch the RateLimit-Remaining header.
CORS is open and GET-only, so browser calls work.

Endpoints

GET/v1/statsCollection-level totals

GET/v1/leaderboardBrainpoints leaderboard (?limit)

GET/v1/tokensPer-token off-chain activity (paginated)

GET/v1/tokens/:idA single token's activity summary

GET/v1/tokens/:id/metadataToken traits + image by token number

GET/v1/judgesAI Court judges — biases & scoring weights

GET/v1/judges/:idA single judge (e.g. J01)

GET/v1/lawyersAI Court lawyers — combat stats (?role, ?pair)

GET/v1/lawyers/:idA single lawyer (e.g. L01A)

GET/v1/marketFloor price + volume snapshot

GET/v1/salesRecent secondary sales (paginated)

GET/v1/sales/topBiggest sales (?window=1d|7d|30d|all)

GET/v1/sales/token/:idA token's sale history

GET/v1/listingsActive listings, cheapest first

GET/v1/tokens/:id/listingWhether a token is listed + price

GET/v1/holdersHolder leaderboard (amount, or ?trait_type/&trait_value)

GET/v1/holders/:walletA wallet's holdings

GET/v1/tokens/:id/ownerCurrent owner of a token

GET/v1/traitsTrait rarity catalog (?type to narrow)

GET/v1/traits/tokensToken ids with a trait (?type & ?value)

GET/img/:fileCharacter portrait PNG (public, no key)

Data schema

Stats

GET /v1/stats

One object summarising the whole collection.

Field	Type	Description
wallets	integer	Distinct wallets holding brainpoints
total_brainpoints	integer	Sum of all brainpoints
total_actions	integer	Total recorded off-chain actions

Leaderboard

GET /v1/leaderboard

Brainpoints ranking, high to low. Query: ?limit (1–100).

Field	Type	Description
rank	integer	1-based rank
wallet_address	string	Public on-chain address
balance	integer	Brainpoints held

Token

GET /v1/tokens · /v1/tokens/:id

Per-token off-chain activity. Query: ?limit, ?offset.

Field	Type	Description
id	integer	Token id
action_count	integer	Recorded actions involving this token
last_action_at	timestamp	ISO 8601, nullable

Token metadata

GET /v1/tokens/:id/metadata

A token’s collection metadata — traits and image — by token number, from the BRAINROT metadata API (edge-cached).

Field	Type	Description
id	integer	Token number
name	string	e.g. BRAINROT #31
description	string	Collection description
image_url	string	Public webp URL, usable in an <img> tag
attributes	array	{ trait_type, value } — Archetype, Base, Rarity Tier, Type, Expression, Hat, …

Holder

GET /v1/holders · /v1/holders/:wallet · /v1/tokens/:id/owner

On-chain ownership, refreshed ~6h from Alchemy. /holders ranks wallets by amount held — add ?trait_type=&trait_value= to rank by a trait (e.g. who holds the most Sharks). /holders/:wallet lists a wallet’s token ids; /tokens/:id/owner gives a token’s current owner.

Field	Type	Description
rank	integer	Leaderboard position
wallet	string	Holder address
tokens	integer	Count held (or count of the trait, when filtered)
token_ids	integer[]	Held token numbers (on /holders/:wallet)
owner	string	Current owner (on /tokens/:id/owner)
as_of	timestamp	When ownership was last refreshed

Trait

GET /v1/traits · /v1/traits/tokens

/traits is the rarity catalog (each trait type → its values + counts + rarity %); add ?type to narrow. /traits/tokens lists the token ids that have a given ?type & ?value.

Field	Type	Description
trait_type	string	e.g. Base, Archetype, Rarity Tier, Hat
value	string	e.g. Shark
count	integer	How many tokens have this value
pct	number	Rarity: count / total_tokens (0–1)
token_ids	integer[]	Tokens with the trait (on /traits/tokens)

Market

GET /v1/market

Latest collection snapshot, refreshed every ~5 min from OpenSea. Floor price, rolling volumes, sale counts, listed/unlisted, owners.

Field	Type	Description
floor.price_eth	number	Current floor price
floor.symbol	string	Currency (ETH)
volume_eth	object	total, day, week, month (ETH)
sales	object	total, day, week (counts)
listings	object	listed, unlisted, total_supply, listed_pct, cheapest_eth
num_owners	integer	Distinct owners
captured_at	timestamp	ISO 8601 snapshot time

Listing

GET /v1/listings · /v1/tokens/:id/listing

Active OpenSea listings, refreshed ~5 min. /listings is cheapest-first; /tokens/:id/listing tells you if a specific token is listed and at what price.

Field	Type	Description
token_id	integer	Listed token
price_eth	number	Asking price
currency	string	ETH \| WETH \| …
order_hash	string	OpenSea order hash
listed	boolean	On /tokens/:id/listing

Sale

GET /v1/sales · /v1/sales/top · /v1/sales/token/:id

Secondary sales, newest first. /sales paginates (?limit, ?offset); /sales/top ranks by price (?window=1d|7d|30d|all); /sales/token/:id is one token’s history. Feed covers the recent history OpenSea exposes; all-time totals live in /v1/market.

Field	Type	Description
token_id	integer	Token sold
price_eth	number	Price in ETH/WETH terms
price_wei	string	Raw amount (no precision loss)
currency	string	ETH \| WETH \| …
buyer	string	Buyer address
seller	string	Seller address
tx_hash	string	Transaction hash
marketplace	string	Source marketplace
sold_at	timestamp	ISO 8601 sale time
order_hash	string	OpenSea order hash

Judge

GET /v1/judges · /v1/judges/:id

The 20 AI Court judges. Their biases are eight scoring weights (floats ~0–1 summing to ~1) describing what each judge rewards. Query: ?limit, ?offset.

Field	Type	Description
id	string	e.g. J01–J20
name	string	Personal name
archetype	string	e.g. The Dril-Pilled Crank
descriptor	string	One-line bio
native_era	string	Internet era they come from
brainrot_literacy	string	How fluent they are in brainrot
weights	object	THE BIASES — scroll_stop, replicability, quotability, cursedness, cuteness, iconicity, discourse_fuel, lore_density (each a float ~0–1)
disposition	string	Temperament
voice_register	string	How they speak
verdict_style	string	How they write rulings
fixations	string	What they latch onto
meme_dislikes	string	What they reject
signature_phrases	string[]	Catchphrases
preferred_lore_tags	string[]	Lore tags they favour
image_url	string	Public portrait URL

Lawyer

GET /v1/lawyers · /v1/lawyers/:id

The 40 AI Court lawyers — 20 mirror pairs, each an advocate and an adversary. Their statistics are five 1–10 combat stats. Query: ?role=advocate|adversary, ?pair=P01, ?limit, ?offset.

Field	Type	Description
id	string	e.g. L01A (advocate) / L01D (adversary)
name	string	Personal name
archetype	string	Character archetype
role	string	advocate \| adversary
pair_id	string	Mirror pair, e.g. P01
partner_id	string	The opposing lawyer in the pair
native_era	string	Internet era they come from
brainrot_literacy	string	How fluent they are in brainrot
stats	object	THE STATISTICS — formal_authority, brainrot_fluency, rhetorical_pressure, composure, personal_history_weight (integers 1–10)
disposition	string	Temperament
voice_register	string	How they speak
philosophical_position	string	Their worldview on memes
argumentation_style	string	How they argue
meme_dislikes	string	What they reject
meme_loves	string	What they champion
fixations	string	What they latch onto
failure_mode	string	How they crack under pressure
signature_phrases	string[]	Catchphrases
image_url	string	Public portrait URL

Lawyers come in 20 mirror pairs (P01–P20): each pair is one advocate (id ending A) versus one adversary (id ending D). Use ?pair=P03 to fetch both sides.

Examples

# 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"

# A portrait (public — no key)
https://cpi.brainrot.works/img/J01.png

Ideas — what to build

Buildable today

Brainpoints leaderboard

Top holders, holder counts, rank movement.

Collection pulse

Live totals and activity counters from /v1/stats.

Most-active tokens

Rank tokens by action_count.

Judge bias explorer

Radar charts of each judge’s 8 weights — who rewards cursedness vs cuteness vs lore.

Verdict predictor

Score a token’s vibe against each judge’s weights to guess their ruling.

Lawyer tier lists

Rank all 40 lawyers by composure, pressure, etc.; compare advocate vs adversary in a pair.

Character galleries

Profile cards and galleries built on image_url.

Token explorer

Look up any token’s image + traits by number (/v1/tokens/:id/metadata) — rarity tools, trait filters, collage makers.

Holder leaderboards

Rank wallets by amount held (/v1/holders), whale-watch, or show a wallet’s full portfolio with images + traits.

Rarity & trait tools

Rarity catalog (/v1/traits), trait filters/galleries (/v1/traits/tokens), and “who owns the most of trait X” (/v1/holders?trait_type=&trait_value=).

Bots & quizzes

“Which judge are you,” a Discord bot (!judge J05), or an LLM persona arguing in a lawyer’s voice.

Market dashboards

Live floor + volume + listed/unlisted ratio (/v1/market), a recent-sales ticker (/v1/sales), a biggest-sales hall of fame (/v1/sales/top), and a live listings board (/v1/listings).

Sales bots

Poll /v1/sales and post each new sale to Discord/Telegram/X; flip alerts when a token resells.

On the roadmap (as more data lands)

Holder P&L and cost-basis

Combine /v1/sales history with per-wallet holdings.

Composite rarity score

Weight each token’s traits by rarity into a single score/rank.

Cross-cuts

Rarity × judge-bias scoring, archetype-weighted boards, “rarest wallet”.

For AI agents

A machine-readable version of this reference lives at /llms.txt. It is the source of truth for the schema: stable JSON, paginate with limit/offset, respect RateLimit-Remaining, treat everything as read-only.