# TBAM Public API

> Public API for To Be a Machine — an on-chain generative art NFT project on Ethereum.
> Base URL: https://api.tbam.ripe.wtf/v0
> All responses are JSON. Prices are in ETH (numbers). Timestamps are unix seconds (strings). CORS open to all origins.
> Rate limit: 60 requests/minute per IP.

## Concepts

- Each TBAM token is a "screen test" — a generative artwork that changes every Ethereum block.
- Tokens have two trait types: "token DNA" (constant, derived from mint hash) and "block traits" (change every block for live tokens, permanent once settled).
- When a token is "settled", its visual is permanently locked to a specific block.
- Settling creates a 24-hour open edition for that frame.
- The "calibration seed" is a global constant (Token 0's settled block hash) that influences all rendering.

## Contracts

- Machine (ERC-721): 0xc392fbdc128bfc8e72cb78961922e1cedd777263
- Editions (ERC-1155): 0x324c68bb517b43ca96bcabfb57ff90e1d5101152
- Renderer: 0xAd7b9D2e27241666AA7F6bf562B20161b207219a

## Endpoints

### GET /v0/collection
Project overview: supply, lock rate, editions, mint state, secondary market floors, participants.
Response: { supply: { total, settled, live }, lockRate, editions: { total, open, totalCopiesMinted }, participants: { uniqueCollectors, uniqueSettlers, uniqueEditionMinters, total }, totalEditionRevenue, launchedAt, mintState: { isOpen, isFirstRun, currentPrice, currentWindowId, windowClosesAt, queueLength }, secondary: { floorPrice, settledFloorPrice, unsettledFloorPrice } }

### GET /v0/contract/state
Current mint price, window status, supply. Cached 12s.
Response: { currentMintPrice, totalSupply, isMachineOpen, isFirstRun, windowTimeRemaining, currentWindowStartedAt, currentWindowId, windowDuration, queueLength, mintWindowClosesAt, serverTimestamp }

### GET /v0/tokens
Paginated token list.
Params: limit (1-100, default 20), offset, owner (address), settled (true/false), sort (id|mintTime|lockTime)
Response: { tokens: [{ id, owner, mintBlock, mintTimestamp, settled, settledBlock, settledAt }], total, limit, offset, hasMore }

### GET /v0/token/:id/info
Token detail with ENS.
Response: { id, owner, ownerEns, mintBlock, mintBlockHash, mintTimestamp, settled, settledBlock, settledBlockHash, settledAt }

### GET /v0/token/:id/traits
Computed traits grouped by token DNA and block traits.
Response: { id, settled, tokenTraits: { paletteType, rotation, hueCount }, blockTraits: { gridSize, border, substrate, pixelBias, flowMode, ditherMethod, blendMode, isBlackWhite } }

Token DNA trait values:
- paletteType: Monochrome, Duotone, Triadic, Tetrad, Rich, Spectrum
- rotation: 0-359 (hue rotation degrees)
- hueCount: 1-6

Block trait values:
- gridSize: 1×1, 3×3, 4×4, 6×6, 8×8, 12×12, 16×16, 24×24
- border: true/false
- substrate: pure, tinted
- pixelBias: uniform, small-biased, large-biased, extremes
- flowMode: full, mixed, none
- ditherMethod: floyd-steinberg, ordered, mixed
- blendMode: Multiply, Hard Light, Screen
- isBlackWhite: true (0.5% chance), false

### GET /v0/token/:id/render-data
Seeds and full DNA for client-side rendering.
Settled response: { tokenId, settled: true, settledBlock, settledBlockHash, paletteSeed, renderSeed, calibrationSeed, dna: { vocabulary, palette, contractTraits }, imageUrl }
Unsettled response: { tokenId, settled: false, currentBlock, currentBlockHash, paletteSeed, renderSeed, calibrationSeed, dna }

### GET /v0/token/:id/image
Settled token PNG image. Returns 403 for unsettled tokens.
Params: size (200-2000, default 1536)

### GET /v0/token/:id/live
Self-contained HTML page rendering full artwork. Works for both live and settled tokens. Embeddable via iframe.
For settled tokens: always renders the settled frame, immutably cached.

### GET /v0/token/:id/live/:blockNumber
Artwork at a specific block. Block must be >= mint block. Settled tokens always render settled frame regardless of param.

### GET /v0/editions
Paginated edition list.
Params: limit (1-100, default 20), offset, open (true/false)
Response: { editions: [{ id, printer, openUntil, isOpen, startBlock, startTimestamp, totalMinted }], total, limit, offset, hasMore }

### GET /v0/editions/:id
Single edition detail. Same shape as list item. 404 if not found.

### GET /v0/activity/feed
Unified activity feed.
Params: limit (1-50, default 20), offset, type (mint|settle|edition_mint|edition_closing), actor (address)
Response: { events: [{ type, timestamp, block, actor, actorEns, tokenId, editionId, amount, totalPaid, timeRemaining, totalMinted }], limit, offset, hasMore }

### GET /v0/address/:address
Collector profile. Accepts 0x addresses only.
Response: { address, ens, tokens: { held: [ids], settled: [ids], count, settledCount }, editions: { created: [{ id, totalMinted, openUntil }], collected: [{ editionId, quantity, totalPaid }] }, firstActivity, lastActivity }

## Error codes

- 400: Invalid parameters
- 403: Token not settled (image endpoint only)
- 404: Not found
- 429: Rate limit exceeded
- 503: Indexer unavailable

## Links

- Project: https://tbam.ripe.wtf
- Interactive demo: https://tbam.ripe.wtf/api
- Endpoint reference: https://api.tbam.ripe.wtf/v0/
- Swagger UI: https://api.tbam.ripe.wtf/docs
- Contact: https://x.com/ripe0x