API

Public REST API. Everything the app shows comes from here; anything you can see, you can fetch.

Conventions

Item	Convention
Base URL	`https://hoodapi.mainnet.games`
Format	JSON. All endpoints are `GET` except `POST /v1/claims`, the API's only write.
Amounts	Decimal integer strings, denominated in wei. Parse as big integers, never as floats.
Timestamps	ISO-8601, UTC.
Addresses	Accepted case-insensitively. Pool endpoints accept either the pool address or the token address.
Pot balances	Served from the platform's internal wei-exact ledger, reconciled against chain balances via the published invariant on `/v1/transparency`.

GET /v1/pools

List pools.

Query param	Meaning
`status`	Filter: `active`, `graduated`, or `dead`.
`creator`	Filter by creator address.
`sort`	`pot` (default, largest pot first), `new`, or `trending` (24h volume).
`limit`	Default 100, max 500.

Returns { pools: [...] }. Each pool carries its addresses (pool, token, creator), name/symbol/image, status, era, created/graduated/last-trade timestamps, pot balance, cumulative fees, WETH raised, graduation progress, and 24h volume.

GET /v1/pools/:address

One pool in full: everything from the list view plus trade count, the current-era ticket leaderboard (top 20 wallets with ticket weight and share), the era's total tickets, and the last-10 window. Before graduation the last-10 window is live (the set as it stands now, minimum qualifying buy included); after graduation it is recorded (the final set that was paid). 404 if unknown.

GET /v1/pools/:address/candles

OHLCV candles derived from the pool's trade history.

Query param	Meaning
`res`	Bucket size in seconds: `60`, `300` (default), `900`, `3600`, or `86400`. Anything else is a 400.
`limit`	Number of candles, default 300, max 1000.

Candles come back in ascending time order: time (unix seconds, bucket start), open/high/low/close (floats, wei of WETH per whole token; display only, never money math), volume (WETH side, wei string), and trade count.

GET /v1/analytics

Platform-wide series. days query param: 1 to 365, default 30. Returns lifetime totals (volume, trades, unique traders, launches, graduations, prizes paid, winners paid) and a daily series of the same, computed from the trade ledger.

GET /v1/progressive

The network-wide progressive pot: current balance, next draw time (the next 20:00 UTC), the accruing period's id and ticket total, and a summary of the last settled draw. The pot balance is the ledger value, the same number the draw will pay.

GET /v1/draws

Draw history, newest first.

Query param	Meaning
`kind`	`graduation` or `progressive`.
`pool`	Filter graduation draws by source pool.
`limit`	Default 50, max 200.

GET /v1/draws/:id

The full provably-fair bundle for one draw: snapshot URL and hash, commitment bytes and commitment transaction, the exact commitment encoding string, drand round, revealed randomness and a direct drand verify URL, algorithm version, the announcer address, winners, and per-winner payouts with status and payout transaction. Everything needed to re-verify the draw independently.

GET /v1/winnings/:wallet

A wallet's prizes: totals for claimable, pending, and paid, plus every winning row with draw id, kind, source pool, amount, status, and timestamps. Status is one of unclaimed, pending, sending, paid. Unclaimed prizes never expire.

POST /v1/claims

Claim a wallet's winnings. The only write in the API. Body:

{
  "wallet":    "0x...",
  "message":   "jackpot:claim:<address>:<issuedAtMs>",
  "signature": "0x..."
}

The message is the literal string jackpot:claim: followed by the wallet address and the unix-millisecond timestamp at signing, signed with EIP-191 personal_sign by that wallet. The signature is fresh for 10 minutes; after that, sign a new message (the prize itself never expires). Addresses are compared case-insensitively.

A valid claim flips all of the wallet's unclaimed prizes to pending; the payout batch then pays them in ETH, typically within minutes. The call is idempotent: replaying it finds nothing left to flip. Responses: 200 with the count and total claimed, 400 on missing fields, 401 on a bad or expired signature.

GET /v1/events

Server-sent events stream (standard EventSource contract) of draw settlements and paid payouts, so a page can react to a win live. Each message carries an id; reconnecting with Last-Event-ID replays missed events from a ring buffer. Comment heartbeats keep idle connections open. Amounts in event payloads are decimal wei strings.

GET /v1/transparency

The receipt. Raw numbers, nothing withheld:

rake and routing splits, in basis points;
pot balances by class: per-pool pots, the progressive pot, treasury;
bank and payout wallet addresses with live balances, and whether reserves cover the pot total;
the daily payout budget, today's spend, and remaining headroom;
pending and unclaimed payout liabilities;
the published operational keys (bank, announcer, claimer, payout);
the reconciliation invariant, checked continuously:

sum(virtual accounts) == bank + payout - pendingPayouts

with the current drift and the time of the last check. If this page's numbers ever stopped adding up, that would be visible here first.

Prev: ContractsOverview