# Normies API Base URL: `https://api.normies.art` Normies is a 10,000-token on-chain NFT collection on Ethereum. Token IDs are `0` through `9999`. The API serves token rendering, original mint data, Canvas state, burn/customization history, zombie state, Legendary Canvas state, ERC-8004 agent metadata, rarity data, and the Pixel Market (pixel ledger balances, sell-side listings, fills, and canvas services). Pixels: burning Normies earns pixels. Pixels sit either attached to a Normie (its painting ceiling, reported as `actionPoints`) or in a wallet balance. Attached pixels backing the current overlay are `lockedPixels`; the rest are `freePixels` and can be withdrawn to the wallet without a reset. Canvases are 40x40 by default and can be enlarged to 50, 60, 70 or 80 pixels per side; a blank canvas drops the base art. Bitmaps are `ceil(n*n/8)` bytes (200, 313, 450, 613, 800). Most mutable data is read from the Ponder indexer rather than from per-request RPC calls. ## Cache Policy Every endpoint below lists the public `Cache-Control` header set by the API server. `none` means the API server does not set an explicit `Cache-Control` header. Route-family defaults: - `/rarity/*`: `public, max-age=15, s-maxage=30, stale-while-revalidate=120` - `/rarity/admin/*`: `no-store` - `/rarity/listings/stream`: `no-store` - `/canvas/status`: `public, max-age=300, s-maxage=300` - `/zombies/status`: `public, max-age=10, s-maxage=10` - `/pixels/*`, `/market/*`, `/canvas/sinks`, `/canvas/token/*`: `public, max-age=10, s-maxage=10` - Any path containing `/canvas/info`: `public, max-age=60, s-maxage=60` - Owner and holder paths: `public, max-age=10, s-maxage=10` - Paths containing `/original/` or `/traits`: `public, max-age=300, s-maxage=3600` - `/history/*`: `public, max-age=60, s-maxage=300` - Default `/normie/*`, `/zombies/*`, `/legendary-canvas/*`: `public, max-age=60, s-maxage=300` - `/favicon.png` and `/favicon.ico`: `public, max-age=86400` - `/agents/*`: set per endpoint. Server-side cache defaults: - `CACHE_TTL_MS`: 3600000 ms / 3600 s. Bulk token dump cache and positive agent binding cache. - `CANVAS_CACHE_TTL_MS`: 60000 ms / 60 s. Canvas transform and transformed-state caches. - `CANVAS_INFO_CACHE_TTL_MS`: 60000 ms / 60 s. Canvas info cache, agent response cache, negative agent binding TTL. - `CANVAS_STATUS_CACHE_TTL_MS`: 300000 ms / 300 s. Canvas status cache. - `ZOMBIE_CACHE_TTL_MS`: 60000 ms / 60 s. Zombie token info and bitmap caches. - `ZOMBIE_STATUS_CACHE_TTL_MS`: 10000 ms / 10 s. Zombie status response cache. - `MARKET_CACHE_TTL_MS`: 10000 ms / 10 s. Public cache header for Pixel Market listings, balances and sinks. - `LEGENDARY_CANVAS_CACHE_TTL_MS`: 60000 ms / 60 s. Legendary Canvas token info cache. - `RARITY_CACHE_TTL_MS`: 60000 ms / 60 s. Live and historical rarity collection snapshots; historical cache keeps up to 32 block snapshots. - `RARITY_LISTINGS_REFRESH_MS`: 60000 ms / 60 s. OpenSea listing poll interval for rarity listings. - `transformHistoryCache`: 30000 ms / 30 s. Per-token transform history. - Immutable token image data, raw traits, and decoded traits are cached in-process with no TTL. ## Core Endpoints - `GET /` - Human-readable API documentation. - Cache: `none` - `GET /llms.txt` - LLM/tool-readable API documentation. - Cache: `none` - `GET /favicon.png` - PNG favicon. - Cache: `public, max-age=86400` - `GET /favicon.ico` - PNG favicon served at the ICO path. - Cache: `public, max-age=86400` - `GET /health` - Health check. Response: `{ "status": "ok" }`. - Cache: `none` ## Normie Token Data Active endpoints apply zombie and Canvas state. Original endpoints ignore zombie conversion and Canvas edits. - `GET /normie/all/original` - Bulk original mint dump with token ID, raw image data, decoded traits, pixel count, block number, timestamp, and tx hash. - Cache: `public, max-age=60, s-maxage=300` - `GET /normie/all/original/data` - Alias-style bulk original mint dump with the same token rows. - Cache: `public, max-age=300, s-maxage=3600` - `GET /normie/all/original/traits` - Decoded original traits for all indexed tokens. - Cache: `public, max-age=300, s-maxage=3600` - `GET /normie/all/original/traits/binary` - Raw original `bytes8` trait hex for all indexed tokens. - Cache: `public, max-age=300, s-maxage=3600` - `GET /normie/all/original/pixels` - Original raw image data and pixel counts for all indexed tokens. - Cache: `public, max-age=300, s-maxage=3600` - `GET /normie/all/original/canvas` - Canvas-oriented alias for the original bitmap rows. - Cache: `public, max-age=300, s-maxage=3600` - `GET /normie/{id}/owner` - Current indexed owner. `id` must be 0-9999. - Cache: `public, max-age=10, s-maxage=10` - `GET /normie/{id}/pixels` - Active 40x40 bitmap as a 1600-character `0`/`1` string. - Cache: `public, max-age=60, s-maxage=300` - `GET /normie/{id}/traits/binary` - Raw original mint trait hex. - Cache: `public, max-age=300, s-maxage=3600` - `GET /normie/{id}/traits` - Decoded original mint traits. - Cache: `public, max-age=300, s-maxage=3600` - `GET /normie/{id}/image.svg` - Active SVG image. Zombie art and Canvas transforms are applied when present. - Cache: `public, max-age=60, s-maxage=300` - `GET /normie/{id}/image.png` - Active 1000x1000 PNG image rendered from the active SVG. - Cache: `public, max-age=60, s-maxage=300` - `GET /normie/{id}/metadata` - Active NFT metadata JSON with Level, Pixel Count, Action Points, Customized, zombie attributes when converted, and Legendary Canvas artist when set. - Cache: `public, max-age=60, s-maxage=300` - `GET /normie/{id}/legendary-canvas` - Legendary Canvas state for a token. - Cache: `public, max-age=60, s-maxage=300` - `GET /normie/{id}/original/pixels` - Original mint bitmap as a 1600-character `0`/`1` string. - Cache: `public, max-age=300, s-maxage=3600` - `GET /normie/{id}/original/image.svg` - Original mint SVG. - Cache: `public, max-age=300, s-maxage=3600` - `GET /normie/{id}/original/image.png` - Original mint PNG. - Cache: `public, max-age=300, s-maxage=3600` - `GET /normie/{id}/zombie` - Token-scoped zombie info plus conversion history. - Cache: `public, max-age=60, s-maxage=300` - `GET /normie/{id}/zombie/attributes` - Zombie attributes for a converted token, or an empty list if not converted. - Cache: `public, max-age=60, s-maxage=300` - `GET /normie/{id}/zombie/pixels` - Zombie bitmap as a 1600-character string. - Cache: `public, max-age=60, s-maxage=300` - `GET /normie/{id}/zombie/image.svg` - Zombie SVG image. - Cache: `public, max-age=60, s-maxage=300` - `GET /normie/{id}/zombie/image.png` - Zombie PNG image. - Cache: `public, max-age=60, s-maxage=300` - `GET /normie/{id}/canvas/pixels` - Canvas transform bitmap as a 1600-character string. - Cache: `public, max-age=60, s-maxage=300` - `GET /normie/{id}/canvas/diff` - Pixel diff between active base art and Canvas transform. - Cache: `public, max-age=60, s-maxage=300` - `GET /normie/{id}/canvas/info` - Canvas level, action points (pixels attached), customized flag, delegate, delegate setter, `gridSize`, `baseCleared`, `migrated`, `lockedPixels`, and `freePixels`. - Cache: `public, max-age=60, s-maxage=60` ## Canvas - `GET /canvas/status` - Global Canvas contract status: paused state, max burn percent, tier thresholds, and tier minimum percents. Once the Pixel Market stack is configured a `pixelMarket` object is added with the V2 canvas and market addresses, cumulative `enlargePrices` for 50/60/70/80, `blankCanvasPrice`, the pixel `treasury`, and the market's `paused`, `feeBps` and `revenueShareBps`. - Cache: `public, max-age=300, s-maxage=300` - `GET /canvas/token/{id}/pixels` - Pixels on one Normie: `attached`, `locked` (backing the overlay), `free` (withdrawable without a reset), `level`, `gridSize`, `baseCleared`, `migrated`, `customized`. - Cache: `public, max-age=10, s-maxage=10` - `GET /canvas/token/{id}/activity` - Ledger events that changed the pixels attached to a token (migration, burn rewards, deposits, withdrawals, spends), newest first. - Query: `limit`, `offset`. - Cache: `public, max-age=10, s-maxage=10` - `GET /canvas/sinks` - Pixels spent on canvas services: enlargements (`kind=enlarge`, with `fromSize`/`toSize`) and blank canvases (`kind=clearBase`), with `cost`, `source` (`wallet` or `attached`) and the paying wallet. - Query: `tokenId`, `kind`, `limit`, `offset`. - Cache: `public, max-age=10, s-maxage=10` ## Pixels Wallet-level pixel balances from NormiesCanvasStorageV2. 404 until the Pixel Market stack is configured. - `GET /pixels/balance/{address}` - Wallet `balance` plus the pixels sitting on the wallet's Normies (`attached`, `locked`, `free`, and a per-token breakdown with `gridSize`, `baseCleared`, `customized`). - Cache: `public, max-age=10, s-maxage=10` - `GET /pixels/holders` - Holders of #PIXEL, largest first. `balance` counts every pixel a wallet controls: `wallet` + `listed` (its open market listings) + `attached` (on the Normies it owns). - Query: `limit`, `offset`. - Cache: `public, max-age=10, s-maxage=10` - `GET /pixels/holders/{address}` - One wallet counted the same way: `{ address, balance, wallet, listed, attached, normiesWithPixels }`. - Cache: `public, max-age=10, s-maxage=10` - `GET /pixels/activity/{address}` - Wallet balance moves involving the address (mints in, moves to and from the market, deposits onto Normies, withdrawals), newest first. - Query: `limit`, `offset`. - Cache: `public, max-age=10, s-maxage=10` - `GET /pixels/supply` - `totalWallet`, `totalAttached` (migrated tokens only), `totalMigrated`, and the number of wallets holding pixels. - Cache: `public, max-age=10, s-maxage=10` ## Market Sell-side order book of the NormiesPixelMarket, ETH priced per pixel. Prices and volumes are wei strings. 404 until the stack is configured. - `GET /market/status` - Market config from the chain: `paused`, `feeBps`, `revenueShareBps`, plus the canvas service prices. - Cache: `public, max-age=10, s-maxage=10` - `GET /market/listings` - Listings with `seller`, `pricePerPixel`, `amount`, `remaining`, `partialFill`, `expiry` (0 = none) and `status`. - Query: `status=active|filled|cancelled|all` (default `active`, expired active listings hidden unless `expired=true`), `seller`, `partial=true|false`, `sort=price-asc|price-desc|amount-desc|newest`, `limit`, `offset`. - Cache: `public, max-age=10, s-maxage=10` - `GET /market/listings/{id}` - One listing plus its fills. - Cache: `public, max-age=10, s-maxage=10` - `GET /market/depth` - Active listings grouped by price: `remaining`, `listings`, and `partialRemaining` per level, cheapest first. - Cache: `public, max-age=10, s-maxage=10` - `GET /market/fills` - Fill feed with `buyer`, `seller`, `amount`, `pricePerPixel`, `grossWei`, `feeWei`. - Query: `limit`, `offset`, `after_timestamp`, `sort=asc|desc`. - Cache: `public, max-age=10, s-maxage=10` - `GET /market/fills/address/{address}` - Fills where the address bought or sold. - Query: `limit`, `offset`. - Cache: `public, max-age=10, s-maxage=10` - `GET /market/stats` - Totals (`volumeWei`, `feesWei`, `pixelsTraded`, `fills`, `listings`), `activeListings`, `pixelsListed`, `bestAskWei`, `lastPriceWei`, `volume24hWei`, `pixels24h`, fee config and paused flag. - Cache: `public, max-age=10, s-maxage=10` - `GET /market/candles` - OHLC in wei per pixel from fills, plus `volumeWei`, `pixels` and `fills` per bucket. Empty buckets are omitted. - Query: `interval=1h|4h|1d` (default `1h`), `limit` 1-1000 (default 168). - Cache: `public, max-age=10, s-maxage=10` ## Revenue share Half of Pixel Market fees and half of collection royalties go to `NormiesRevenuePool` and are paid to holders in epochs. Payouts are computed off chain from RPC state (wallet score = (Normies held x bracket + weighted #PIXEL) x boost, sampled four times a day and averaged over the epoch) and claimed on chain with Merkle proofs: each epoch opens for claims 24 hours after it is posted. 404 while the pool is not configured. - `GET /revshare/config` - The scoring rules (`brackets`, `ladder`, `boost`, `looseWeight100`, factors, sampling) and their `configHash`, which every posted epoch records on chain. - `GET /revshare/status` - Pool `balanceWei`, `outstandingWei` (promised to posted epochs), `unallocatedWei` (in the pool, waiting for the next epoch), `availableWei` (that plus the holders' half of royalties still in the royalty splitter: what the next epoch would split now), windows, `nextEpochId`, totals. - `sources`: `marketFeesWei` (all-time Pixel Market fees paid into the pool on every fill), `royaltiesReleasedWei` (royalties released into the pool) and `royaltiesPendingWei` (the holders' half still in the splitter until `release()`); `splitter`: its `ethWei`, `wethWei` and `poolBps`. - `current`: what `availableWei` is made of, counted from the block after the last posted epoch's range (`fromBlock`): `marketFeesWei` (Pixel Market fees paid in since then, over `marketFills` fills), `royaltiesWei` (`royaltiesReleasedWei` released since then plus `royaltiesPendingWei` still in the splitter) and `otherWei` (unclaimed payouts swept back, a cancelled epoch's money, rounding dust). Null when the indexer is unreachable. - `GET /revshare/files/{id}.json` - The raw epoch file (every payout with its proof), which is the epoch's on-chain `dataURI`. Check it with `pnpm revshare verify `. 404 until published. - Cache: `public, max-age=10, s-maxage=10` - `GET /revshare/epochs`, `GET /revshare/epochs/{id}` - Posted epochs: `root`, `amount`, `claimed`, `claims`, block range, `claimableAt`, fixed `sweepableAt` (earliest sweep time; claims remain open until swept), `status` (`posted`, `cancelled`, `swept`), and whether the payout file is published. - `GET /revshare/epochs/{id}/proof/{address}` - `index`, `amount` and `proof` for `NormiesRevenuePool.claim(epochId, index, account, amount, proof)`. 404 if the address has no payout. - `GET /revshare/wallet/{address}` - Live `score`, `sharePpm` and score `breakdown` (a projection of the next epoch, not a payout), `claimable` epochs with proofs, `claimableWei`, and past `claims`. - `GET /revshare/tiers` - How many scoring wallets sit in each cell of the tier grid (Normie bracket x #PIXEL boost). ## History - `GET /history/burns` - Paginated Canvas burn commitments. - Query: `limit` 1-100, `offset`. - Cache: `public, max-age=60, s-maxage=300` - `GET /history/burns/{commitId}` - One burn commitment plus burned token details. Commit ids restart at 0 on the V2 canvas; every commitment carries `contractVersion` (1 or 2). - Query: `version=1|2` (defaults to the newest configured canvas). - Cache: `public, max-age=60, s-maxage=300` - `GET /history/burns/pending/legacy` - Original-canvas commitments not yet revealed there. Anyone can reveal them on that canvas; all of them are revealed before it is paused for the Pixel Market cutover. - Query: `owner`, `limit`, `offset`. - Cache: `public, max-age=60, s-maxage=300` - `GET /history/burns/address/{address}` - Burn commitments created by a wallet. - Query: `limit`, `offset`. - Cache: `public, max-age=60, s-maxage=300` - `GET /history/burns/receiver/{tokenId}` - Burn commitments that transferred action points to a receiver token. - Query: `limit`, `offset`. - Cache: `public, max-age=60, s-maxage=300` - `GET /history/burned-tokens` - Paginated list of burned token records. - Query: `limit`, `offset`. - Cache: `public, max-age=60, s-maxage=300` - `GET /history/burned-ids` - Every burned token id in one response: `{ count, ids }`, ids ascending. - Cache: `public, max-age=60, s-maxage=300` - `GET /history/burned/{tokenId}` - Burn record for a token. - Cache: `public, max-age=60, s-maxage=300` - `GET /history/burned/{tokenId}/image.svg` - Original SVG for a burned token. - Cache: `public, max-age=60, s-maxage=300` - `GET /history/burned/{tokenId}/image.png` - Original PNG for a burned token. - Cache: `public, max-age=60, s-maxage=300` - `GET /history/customized` - Canvas transform event sync feed. Returns events, unique token IDs, count, `hasMore`, and requested timestamp cursor. - Query: `limit`, `offset`, `after_timestamp` or `since_timestamp`, `sort=asc|desc`. - Cache: `public, max-age=60, s-maxage=300` - `GET /history/normie/{id}/versions` - Transform versions for a token, oldest first, with change count, new pixel count, `gridSize`, `cleared` (an overlay reset), transformer, block, timestamp, and tx hash. `version` numbers match `/history/normie/{id}/version/{version}/*`. - Query: `limit`, `offset`. - Cache: `public, max-age=60, s-maxage=300` - `GET /history/normie/{id}/version/{version}/pixels` - Historical composited pixel string for a transform version. - Cache: `public, max-age=60, s-maxage=300` - `GET /history/normie/{id}/version/{version}/image.svg` - Historical composited SVG for a transform version. - Cache: `public, max-age=60, s-maxage=300` - `GET /history/normie/{id}/version/{version}/image.png` - Historical composited PNG for a transform version. - Cache: `public, max-age=60, s-maxage=300` - `GET /history/stats` - Indexer summary counts for burn commitments, burned tokens, transforms, token data, zombies, Legendary Canvas, and total action points, plus `pixelSupply`, `market` totals and `totalCanvasSinks`. - Cache: `public, max-age=60, s-maxage=300` - `totalActionPointsDistributed` is the sum of every burn reward, which is the action point supply (points are only created by rewards; a burned Normie's points move to the receiver). `totalActionPointsCarried` is how many points moved that way and is not supply. ## Holders - `GET /holders/{address}` - Current indexed token IDs held by a wallet. - Cache: `public, max-age=10, s-maxage=10` - `GET /delegations/{address}` - Canvas edit rights delegated to a wallet, filtered to the delegations NormiesCanvas still honours. Delegations set by a previous owner are dropped. Returns tokenIds plus an owners map. - Cache: `public, max-age=10, s-maxage=10` ## Zombies - `GET /zombies/status` - Zombie contract status and pool configuration. - Cache: `public, max-age=60, s-maxage=300` - `GET /zombies/conversions` - Paginated zombie conversion commitments and reveal state. - Query: `limit`, `offset`. - Cache: `public, max-age=60, s-maxage=300` - `GET /zombies/wallet/{address}` - Zombie conversions for a qualifying wallet. - Query: `limit`, `offset`. - Cache: `public, max-age=60, s-maxage=300` - `GET /zombies/token/{id}` - Zombie info plus conversion history for a token. - Cache: `public, max-age=60, s-maxage=300` - `GET /zombies/token/{id}/attributes` - Zombie attributes for a token. - Cache: `public, max-age=60, s-maxage=300` - `GET /zombies/token/{id}/pixels` - Zombie bitmap as a 1600-character string. - Cache: `public, max-age=60, s-maxage=300` - `GET /zombies/token/{id}/image.svg` - Zombie SVG image. - Cache: `public, max-age=60, s-maxage=300` - `GET /zombies/token/{id}/image.png` - Zombie PNG image. - Cache: `public, max-age=60, s-maxage=300` ## Legendary Canvas - `GET /legendary-canvas` - Paginated list of tokens marked with the Legendary Canvas artist trait. - Query: `limit`, `offset`. - Cache: `public, max-age=60, s-maxage=300` - `GET /legendary-canvas/token/{id}` - Legendary Canvas state for one token. - Cache: `public, max-age=60, s-maxage=300` ## ERC-8004 Agents - `GET /agents/metadata/{tokenId}` - ERC-8004 metadata JSON served as the on-chain agent URI. - Cache: `public, max-age=60, s-maxage=120, stale-while-revalidate=300` - `GET /agents/persona-preview/{tokenId}` - Persona JSON for any token, whether or not it is registered as an agent. - Cache: `public, max-age=30, s-maxage=60, stale-while-revalidate=300` - `GET /agents/identity/{tokenId}` - Trait-derived agent name, type, and raw trait map. - Cache: `public, max-age=300, s-maxage=600, stale-while-revalidate=3600` - `GET /agents/info/{tokenId}` - Registered-agent persona, traits, live canvas state, registration metadata, and placeholder interaction/MCP status. - Cache: `public, max-age=30, s-maxage=60, stale-while-revalidate=300` - `GET /agents/by-agent-id/{agentId}/info` - Reverse lookup by ERC-8004 agent ID, returning the same shape as `/agents/info/{tokenId}`. - Cache: `public, max-age=30, s-maxage=60, stale-while-revalidate=300` - `GET /agents/list` - Paginated registered-agent gallery feed enriched with identity. - Query: `limit` 1-100, `sort=newest|oldest`, optional `cursor` agent ID. - Cache: `public, max-age=30, s-maxage=60, stale-while-revalidate=300` - `GET /agents/search` - Search registered agents by name, token ID, or agent ID. - Query: `q`, `limit` 1-50. - Cache: q present: `public, max-age=15, s-maxage=30, stale-while-revalidate=120`; empty q: `none` - `GET /agents/count` - Total registered Normies agents. - Cache: `public, max-age=30, s-maxage=60, stale-while-revalidate=300` - `GET /agents/agent-card/{tokenId}` - A2A v0.3.0 Agent Card JSON linked from ERC-8004 metadata. - Cache: `public, max-age=60, s-maxage=120, stale-while-revalidate=300` - `GET /agents/image/{tokenId}` - Composited SVG image for an agent. - Cache: `public, max-age=60, s-maxage=60, stale-while-revalidate=300` - `GET /agents/binding/{tokenId}` - Normies-only ERC-8004 binding lookup for one token. - Cache: `public, max-age=30, s-maxage=60, stale-while-revalidate=300` - `POST /agents/binding/batch` - Batch binding lookup. Body: `{ "tokenIds": [...] }`. - Cache: `public, max-age=30, s-maxage=60` - `GET /agents/by-agent-id/{agentId}` - Reverse lookup returning the raw binding for an agent ID. - Cache: `public, max-age=60, s-maxage=300` ## Rarity Rarity endpoints power `rarity.normies.art`. They are backed by a bulk Ponder snapshot and short API-server caches. Historical routes recompute ownership, burn counts, traits, and ranks at an Ethereum block number from indexed event state. Historical routes omit OpenSea listings and floor price because those are current external marketplace state. - `GET /rarity/docs` - Small JSON list of rarity endpoints. - Cache: `public, max-age=15, s-maxage=30, stale-while-revalidate=120` - `GET /rarity/stats` - Live rarity stats: indexed count, live supply, burned count, weights, listing count, floor price, and awakened-agent count. - Cache: `public, max-age=15, s-maxage=30, stale-while-revalidate=120` - `GET /rarity/normies` - Paginated live rarity list with rank, score, attributes, listing data, fair value, underpriced flag, burn count, and awakened-agent metadata. - Query: `page`, `limit` 1-100, `sort=rank|id|score|level|action_points|pixel_count|price|awake_registered`, `order=asc|desc`, `search`, `listed=1`, `underpriced=1`, `the100=1`, `awake=1`, `px_tier=low,mid,high`, `wallet_ids`, `trait_*` filters. - Cache: `public, max-age=15, s-maxage=30, stale-while-revalidate=120` - `GET /rarity/normie/{id}` - Full live rarity detail for one token. Returns 410 if burned. - Cache: `public, max-age=15, s-maxage=30, stale-while-revalidate=120` - `POST /rarity/normie/{id}/refresh` - Forces the live rarity collection cache to reload, then returns the same detail shape as `/rarity/normie/{id}`. - Cache: `public, max-age=15, s-maxage=30, stale-while-revalidate=120` - `GET /rarity/normie/{id}/persona` - Awakened-agent persona fields used by the rarity modal. Returns 404 if the token is not an agent. - Cache: `public, max-age=15, s-maxage=30, stale-while-revalidate=120` - `GET /rarity/traits` - Trait filter counts over live, non-burned tokens. - Cache: `public, max-age=15, s-maxage=30, stale-while-revalidate=120` - `GET /rarity/holder/{addressOrEns}` - Current indexed rarity holdings for a wallet. ENS names are accepted and resolved at request time. - Cache: `public, max-age=15, s-maxage=30, stale-while-revalidate=120` - `GET /rarity/recursive-burn-holders` - Leaderboard of current wallets by recursive burn count of held customized tokens. - Query: `limit` 1-200, optional `wallet`. - Cache: `public, max-age=15, s-maxage=30, stale-while-revalidate=120` - `GET /rarity/historical/{blockNumber}/stats` - Rarity stats recomputed at an Ethereum block number. Listings and floor price are omitted. - Cache: `public, max-age=15, s-maxage=30, stale-while-revalidate=120` - `GET /rarity/historical/{blockNumber}/normies` - Paginated rarity list at a block number. Supports the same non-marketplace filters and sort modes as the live list. - Cache: `public, max-age=15, s-maxage=30, stale-while-revalidate=120` - `GET /rarity/historical/{blockNumber}/normie/{id}` - Full rarity detail for one token at a block number. Returns 410 if burned at that block and 404 if not indexed yet. - Cache: `public, max-age=15, s-maxage=30, stale-while-revalidate=120` - `GET /rarity/historical/{blockNumber}/traits` - Trait filter counts over live, non-burned tokens at a block number. - Cache: `public, max-age=15, s-maxage=30, stale-while-revalidate=120` - `GET /rarity/historical/{blockNumber}/holder/{addressOrEns}` - Indexed wallet holdings at a block number. ENS names are accepted but resolved at request time. - Cache: `public, max-age=15, s-maxage=30, stale-while-revalidate=120` - `GET /rarity/historical/{blockNumber}/recursive-burn-holders` - Leaderboard of wallets by recursive burn count of held customized tokens at a block number. - Query: `limit` 1-200, optional `wallet`. - Cache: `public, max-age=15, s-maxage=30, stale-while-revalidate=120` - `GET /rarity/listings/stream` - Server-Sent Events for listing changes: `listed`, `sold`, `cancelled`. - Cache: `no-store` - `GET /rarity/legendary` - Rarity-app Legendary Canvas curation config with `current` and `upcoming` arrays, loaded from the indexer database. - Cache: `public, max-age=15, s-maxage=30, stale-while-revalidate=120` - `PUT /rarity/admin/legendary` - Admin-only save for Legendary Canvas curation config into the indexer database. Requires `x-admin-key`. - Body: `{ "current": [{ "id": number, "artist": string }], "upcoming": [...] }` - Cache: `no-store` ## Smart Contracts (Ethereum Mainnet) - Normies: `0x9Eb6E2025B64f340691e424b7fe7022fFDE12438` - Core ERC721C token with ERC-2981 royalties. - NormiesStorage: `0x1B976bAf51cF51F0e369C070d47FBc47A706e602` - SSTORE2 bitmap and trait storage with XOR encryption. - NormiesRenderer: `0xBe57fC4D0c729b8e8d33b638Dd441F57365e4c25` - V1 renderer: animated noise pre-reveal, static SVG post-reveal. - NormiesRendererV2: `0x7818f24d3239c945510e0a1a523dd9971812c6c0` - V2 renderer: static noise pre-reveal. - NormiesRendererV3: `0x1af01b902256d77cf9499a14ef4e494897380b05` - V3 renderer: RLE-optimized SVG, Pixel Count trait, canvas animation URL. - NormiesMinter: `0xC74994dD70FFb621CC514cE18a4F6F52124e296d` - V1 EIP-191 signature-verified minting. - NormiesMinterV2: `0xc513272597d3022D77b3d7EEBA92cea5D7fb2808` - V2 minting with delegate.xyz v1/v2 cold wallet delegation. - NormiesCanvas: `0x64951d92e345C50381267380e2975f66810E869c` - Burn-to-edit orchestrator: commit-reveal burns, action points, and pixel transforms. - NormiesCanvasStorage: `0xC255BE0983776BAB027a156681b6925cde47B2D1` - SSTORE2 storage for transform layer bitmaps. - NormiesRendererV4: `0x8eC46Cc1f306652868a4dfbAAae87CBa2715A0eB` - V4 Canvas-aware renderer with composited SVG and extra traits. - NormiesZombie: `0x18533ad55a54c3847Da06A48b51aD7DcB2551202` - Merkle-gated commit-reveal converter that turns eligible Normies into bespoke Zombies. - NormiesZombieStorage: `0xA331bD22C90D1DA096934Db8bc6b69F0e1491E26` - SSTORE2 storage for zombie pool assets and conversion records. - NormiesLegendaryCanvas: `0xfA55f6592522dA74224a67c7D3Fd1DF759c628e8` - Owner-managed registry of selected Legendary Canvas artist traits. - NormiesRendererV5: `0x7c726f02C5e840e1656b522A5C22caaf87C1C35C` - V5 renderer: V4-compatible renderer with zombie metadata and art branches. Pixel Market stack: - NormiesCanvasV2: `0xF14f2852e1fD6A4108156054AF49B3915dc40E2e` - Burns, painting, withdraw/deposit of pixels, canvas enlargement and blank canvas. The original NormiesCanvas is paused. - NormiesCanvasStorageV2: `0x96F2DA32Bb9D429d59ac13dB469f4950cBe02084` - Overlay bitmaps of any grid size, emitting on every write, falling back to NormiesCanvasStorage for older overlays; and the pixel accounting (wallet and per-Normie balances, copied from NormiesCanvas once at cutover). - NormiesPixelMarket: `0x86156A8d6e4B9925F7fEca527ea5D71B0deeDB64` - Sell-side order book with partial or all-or-nothing fills and a fee taken out of seller proceeds. - NormiesRendererV6: `0xd6747533697878a6a3a29B5cCf815740BA23998D` - Grid-size aware renderer with Canvas Size and Blank Canvas traits. - NormiesRevenuePool: `0x481384812e79bf0d11FC0b1704af445D5F06813c` - Holds the holders' half of market fees and royalties and pays it out in epochs with Merkle proofs. - NormiesRoyaltySplitter: `0xA68A225f62772E6158f2B5f8afC184AdB69c3282` - Royalty receiver: splits royalties between the revenue pool and the team. ## Status Codes Common responses: - `200`: success - `400`: invalid token, address, query, or body - `401`: invalid admin key - `403`: admin disabled - `404`: not found or not indexed - `410`: burned token on rarity detail - `502`: upstream indexer, RPC, or provider failure