documentation

API reference

Every route pons exposes publicly, grouped by resource. All bodies and responses are JSON except the render endpoint, which returns a PNG.

Route map

/api/collections
GET, POST /api/collections
GET /api/collections/[slug]
GET /api/collections/[slug]/tokens
GET /api/collections/[slug]/tokens/[token]
POST /api/collections/[slug]/mint
/api/tokens, /api/render, /api/metadata
GET /api/tokens
GET /api/render/[slug]/[token]
GET /api/metadata/[tokenId]
/api/generate-shader
POST /api/generate-shader

Collections

GET/api/collections

List every published collection.

200
{ "collections": [ { "slug": "spectra", "name": "Spectra", "minted": 41, "maxSupply": 512, "priceEth": "0.01", ... } ] }
POST/api/collections

Publish a new collection. Rate limited to 5 per minute per client.

request bodyjson
{
  "auth": { "address": "0x...", "signature": "0x...", "timestamp": 1735000000000 },
  "name": "Spectra",
  "description": "Beams of dispersed light...",
  "creatorName": "pons studio",
  "shaderWgsl": "struct Params { ... } ...",
  "paramSpecs": [{ "key": "beams", "label": "Beams", "min": 2, "max": 6 }],
  "maxSupply": 512,
  "priceEth": "0.01"
}
201 or error
201 { "collection": { "slug": "spectra", ... } }
400 { "error": "shader failed validation: ..." }
401 { "error": "signature rejected: ..." }
GET/api/collections/[slug]

Fetch one collection by slug. 404 if it doesn't exist.

GET/api/collections/[slug]/tokens

List minted tokens in a collection. Query param limit, default 64, max 256.

GET/api/collections/[slug]/tokens/[token]

A single token's full ERC-721 style metadata document. See the Metadata page for the shape.

POST/api/collections/[slug]/mint

Mint the next token. Rate limited to 20 per minute per client.

request bodyjson
// off-chain mode
{ "minter": "0x..." }

// on-chain mode: send the mint transaction first, then verify it here
{ "minter": "0x...", "txHash": "0x..." }
201 or error
201 { "token": { "tokenNumber": 42, "seed": "...", "params": {...} }, "receipt": { "txHash": "...", "onChain": true } }
404 { "error": "collection not found" }
409 { "error": "collection is sold out" }

Tokens, render, and on-chain metadata

GET/api/tokens?owner=0x...

Every token owned by an address, across all collections. Backs the /me page.

200
{ "tokens": [ { "tokenNumber": 7, "seed": "...", "params": {...}, "collectionSlug": "spectra", "collectionName": "Spectra", "shaderWgsl": "..." } ] }
GET/api/render/[slug]/[token]?w=1024&h=1024

A deterministic PNG still of the token, rendered server-side. w and h clamp to 64-1600, default 1024. Cached immutably; 503 if no render backend is available on the host.

GET/api/metadata/[tokenId]

Resolves a global on-chain token id to its collection and token number by reading the contract, then 308-redirects to the canonical tokens/[token] metadata. 503 if the launchpad contract isn't deployed for this environment.

Shader authoring

POST/api/generate-shader

Describe an idea in plain language, get back a validated shader and param specs. Rate limited to 5 per minute per client.

request bodyjson
{ "prompt": "a slow magnetic storm of violet filaments around a dark core" }
200 or error
200 { "name": "...", "description": "...", "shaderWgsl": "...", "paramSpecs": [...] }
422 { "error": "the model could not produce a valid shader (last error: ...)" }
← prevCreating a collectionnext →The contract