For developers

Racerverse API

JSON endpoints, free for personal and commercial use. Most endpoints require an API key for cross-origin / programmatic access; share-friendly endpoints (OG images, embeds, RSS) stay open. Rate-limited per IP. Hit [email protected] if you need a higher limit or have a question.

Authentication

Request a free key at /account/api-keys (sign-in required). Pass it on every request via:

Authorization: Bearer rk_<your-key>

Keys can be revoked at any time from the same page. The website's own pages call these endpoints without keys (same-origin requests are allowed automatically), so you only need a key for off-domain use: scripts, bots, dashboards, mobile apps, etc.

Endpoints marked open below stay accessible without a key — they're meant for sharing (OG images, embeds, RSS).

GET/api/collection/publicKey required

Paged list of all racers (minted + preview).

Param	Example	Notes
`page`	`1`	Page number, 1-indexed.
`limit`	`24`	Up to 200.
`sort`	`newest`	newest \| oldest \| name-asc \| name-desc
`q`	`goblin`	Search query against plate text.
`status`	`all`	all \| minted \| preview
`trait`	`jester`	Exact trait-value filter.
`view`	`viewer`	Use viewer for the compact canonical-art contract.
`assetsOnly`	`1`	Return only racers with published canonical assets.

{ "racers": [{ "publicKey": "dna-<artUuid>", "artUuid": "...", "canonicalAssetBase": "https://cdn.racerverse.com/art/dna/...", "canonicalGlb": ".../model_embed.glb", "canonicalHero": ".../reveal/complete.webp", "canonicalUsdz": ".../model.usdz", "animationManifestUrl": ".../animation-manifest.json", "assetReady": true }], "total": 505, "totalPages": 3 }

GET/.well-known/x402-discoveryOpen

Machine-readable discovery document for the agent-only x402 purchase rail.

{ "agentFacing": true, "userFacing": false, "protocol": "x402", "pricing": "https://racerverse.com/api/x402/pricing", "endpoints": [...] }

GET/api/og/racerOpen
1200×630 candy-card OG image for a single racer.
Param Example Notes
id uz-80-0830 / dna-... Plate slug or DNA public key.
```
<image/png response>
```
GET/api/racers/similarKey required
Trait-distance similarity ranking.
Param Example Notes
id uz-80-0830 Seed racer plate slug or DNA public key.
limit 8 Up to 24.
```
{ "racers": [...] }
```
GET/api/searchKey required
Global search across plates / traits / places / collectors.
Param Example Notes
q banana Min 2 chars.
```
{ "plates": [...], "traits": [...], "places": [...], "collectors": [...] }
```
GET/api/activityKey required
Recent global activity (mints, gifts).
Param Example Notes
limit 80 Up to 200.
```
{ "events": [{ "kind": "mint", "publicKey": "dna-...", "plate": "UZ 80-0830", "at": "..." }] }
```
GET/api/mints/streamKey required
Server-Sent Events feed of new mints, real time.
```
data: { "kind": "mint", "publicKey": "dna-...", "plate": "...", "at": "..." }
```
GET/api/rss?tag=<id>Open
RSS feed of devlog entries, optionally filtered by tag.
Param Example Notes
tag behind-the-scenes Optional tag id.
```
<application/rss+xml>
```
GET/embed/racer/[id]Open
Chrome-less iframe-friendly racer card. CSP allows embedding from any origin.
Param Example Notes
id uz-80-0830 or dna-... Plate slug or DNA public key.
```
<HTML page suitable for an iframe>
```

Param	Example	Notes
`id`	`uz-80-0830 / dna-...`	Plate slug or DNA public key.

Param	Example	Notes
`id`	`uz-80-0830`	Seed racer plate slug or DNA public key.
`limit`	`8`	Up to 24.

Param	Example	Notes
`q`	`banana`	Min 2 chars.

Param	Example	Notes
`limit`	`80`	Up to 200.

Param	Example	Notes
`tag`	`behind-the-scenes`	Optional tag id.

Param	Example	Notes
`id`	`uz-80-0830 or dna-...`	Plate slug or DNA public key.

See /embed for the iframe how-to, and /press for brand assets.