# Launchpad read API

> Read-only JSON endpoints of the Launchpad web app (Robinhood Chain: mainnet 4663, testnet 46630). They serve display and discovery hints: coin lists and search, candidate coins for an account, a coin's governance events and Treasury / stock reserve history, and the Total treasury of all Trading coins. They never prove a deployment, a balance, a right, or that a transaction will succeed.

API specification: /openapi.json (OpenAPI 3.1), not a contract ABI. Paths below are relative to the origin that serves this file. For signing your own on-chain calls, see [the direct-contract guide](/direct-contracts.md).

## Core rule

- Index and snapshot answers (Discover, candidates, governance, Total treasury, mobile) name the block they were read at (`asOf`, `block`, or `meta.coverage.indexed`). History answers carry only each sample's block time; /api/health carries nothing. Every value is a hint valid at that block or time, not current state.
- `status: "unknown"` or `"unavailable"` means no complete, canonical answer. Never treat it as 0, empty, or "no results". Fall back to reading the chain.
- A field that is `null` where a number is expected is unknown, not 0. For example `treasuryRfvWad: null` is a Trading coin that failed its identity check at the snapshot block or whose Treasury could not be read.
- Before signing anything: re-read the relevant contract views on chain at a fresh block, verify the coin's deployment identity (contract addresses and code) against an independently trusted deployment manifest, and simulate the transaction. Do not build a transaction from these responses alone. An SDK may offer verification helpers; a raw read alone does not authenticate its target.
- Amounts and block numbers are decimal strings. `*Wad` = 18 decimals, `*Raw` USDG = 6 decimals.

## Endpoints

- GET /api/discover/search — `view=home` (three rows), `filter=` (`all`, `new`, `ending` = open sales before deadline and below hard cap, `Genesis`, `Trading`, `official`; list with `sort`, `q`, `stock`, `limit` ≤ 32, `cursor`), or `q`/`stock` alone (text search, ≤ 50 matches).
- POST /api/positions/candidates — body `{"account":"0x…"}`; coins past events tied to the account. Candidates only: read each on chain.
- GET /api/coins/{chainId}/{factory}/{coinId}/governance-proposals — proposals and CTO / Creator recipient events, newest first, `cursor` for older pages. Read proposal state on chain.
- GET /api/coins/{chainId}/{factory}/{coinId}/treasury-history — Treasury total sampled since finalization (≤ 40 points).
- GET /api/coins/{chainId}/{factory}/{coinId}/reserve-history — stock reserve sampled the same way. Not backing.
- GET /api/discover/total-treasury — sum of every Trading coin's Treasury at one block; 503 unless complete and ≤ 5 minutes old.
- GET /api/discover/total-treasury/history — one point per UTC day, ≤ 366; missing days have no point.
- GET /api/health — `ok` when the process is up; reads nothing.
- /api/mobile/market and /api/mobile/portfolio are app-internal (used by the Launchpad mobile app); shapes may change.

## Snapshots and cursors

- Discover list and home answer from a stored snapshot at block B. It is served only while B is ≤ 5 minutes old and still canonical; otherwise `unknown` (`stale`, `reorged`, `not_indexed`).
- A list cursor is bound to B's block hash and to `filter`, `sort`, `q`, `stock`, `limit`. Pass it back unchanged with the same parameters; changing them is 400. When its snapshot is gone the answer is `unknown` with `expired`: start from the first page.
- A governance cursor is bound to the subgraph generation and block; a new generation answers `expired`.

## Status codes

- 400 invalid parameters, body, or cursor.
- 404 on indexer-backed endpoints (search, candidates, governance, mobile search): the index is not enabled. A feature flag, not "coin not found". 404 on a coin path can also mean the path is not a coin of this chain.
- 409 (mobile portfolio) the catalogue changed between pages; start again.
- 429 over a limit; wait `Retry-After` seconds.
- 503 read failed or unavailable; the body is `unknown` / `unavailable`, never partial data.

## Rate limits and etiquette

- Indexer-backed endpoints: per client IP (IPv4 address or IPv6 /64), per endpoint, per one-minute window. Shared across server instances only when the operator configures the shared counter; otherwise each server process counts on its own, and a process already tracking 10000 clients answers 429 to new ones. Default 20 requests/minute (operator setting); mobile app endpoints 5x, mobile portfolio continuations 50x. Over the limit: 429 with `Retry-After: 60`, nothing read.
- History endpoints: at most 2 running per server process; busy is 429 with `Retry-After: 2`. Ready histories are cacheable for 60 seconds.
- Honour `Retry-After` and `Cache-Control`. Do not poll faster than the data changes (snapshots are written every few minutes). Do not scrape every coin's history in a loop.

## SDK

- Call these endpoints directly and keep the rules above. Nothing here requires access to the project's SDK. For contract interaction, use the ABI from a trusted deployment record with a general-purpose Ethereum client.
