API

THE TICKET, AS JSON

Same rules, same numbers, no HTML. The public tier needs no key: cached reads are public. Uncached computations share a site-wide budget of one wallet per minute; unavailable sources or exhausted capacity return 503.

GET/api/v1/roast/{address}

One ticket. Complete reads expire after six hours, partial reads after five minutes. Legacy numbers.worstTrade is unavailable; daysOnChain is the observed history span.

curl -s https://roast.xyz/api/v1/roast/0x7f21…9c04
{
  "address": "0x7f21…9c04",
  "doneness": 26,
  "band": "MEDIUM",
  "numbers": { "worstTrade": "-", "deadBags": 4, "tokensTouched": "17+", "daysOnChain": "63" },
  "lines": [ { "code": "R02", "name": "Thin liquidity", "line": "…", "href": "https://…/tx/0x…" } ],
  "fired": [ … ],
  "partial": false,
  "cached_at": "2026-09-08T07:41:12.004Z",
  "rules_version": "v3-transfer-evidence"
}

GET/api/v1/wall?page=&limit=&band=&days=&sort=

The wall, paged. limit defaults to 50 and is capped at 50. band is RARE|MEDIUM|WELL DONE|BURNT, sort is recent|hottest|viewed.

curl -s 'https://roast.xyz/api/v1/wall?band=BURNT&limit=50'
{ "items": [ { "address": "0x…", "doneness": 32, "band": "MEDIUM", "headline": "…", "views": 41, "read_at": "…" } ],
  "page": 1, "per_page": 50, "total": 1204, "next": 2 }

GET/api/v1/rules

Every rule, its weight and its exact condition, plus the doneness formula and bands.

curl -s https://roast.xyz/api/v1/rules
{ "rules_version": "v3-transfer-evidence", "formula": "doneness = min(100, …)",
  "bands": [ … ], "rules": [ { "code": "R01", "enabled": false, "name": "Top of the menu", "weight": 18, "condition": "…" } ] }

GET/api/v1/stats

Tickets printed in total and today, how many came out burnt, and when the last one printed.

curl -s https://roast.xyz/api/v1/stats
{ "tickets": 1204, "today": 88, "burnt": 143, "lastAt": "2026-09-08T07:41:12.004Z", "rules_version": "v3-transfer-evidence" }

GET/api/og/{address}

The shareable card as a 1200×630 PNG, printed from the same ticket the page shows.

curl -s -o card.png https://roast.xyz/api/og/0x7f21…9c04
(image/png)

Conventions

  • — Every list returns { items, page, per_page, total, next } and never more than 50 rows.
  • — Every response that involves rules carries rules_version.
  • — A wallet that opted out returns 410 Gone, not an empty ticket.
  • — A malformed address returns 400; unavailable sources return 503.
  • — Keys, higher limits and batch reads open when the token launches. Nothing to buy today.