# 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, and rarity data.

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`
- 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.
- `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, customized flag, delegate, and delegate setter.
  - 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.
  - Cache: `public, max-age=300, s-maxage=300`

## 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.
  - 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/{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 with change count, new pixel count, transformer, block, timestamp, and tx hash.
  - 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.
  - Cache: `public, max-age=60, s-maxage=300`

## Holders

- `GET /holders/{address}`
  - Current indexed token IDs held by a wallet.
  - 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.

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