Public API Contract
Public reference for the endpoints the current PolyLab web app relies on.
This page is intentionally explicit and implementation-first. If the product or upstream APIs change, the current behavior described here can change with them.
GET /api/homepage-bootstrap
Returns the precomputed homepage payload used for the marketing homepage first paint.
Important response fields include:
| Field | Meaning |
|---|---|
generated_at | Snapshot generation timestamp |
market_last_updated | Latest snapshot_at used when building the snapshot |
smart_money_last_updated | Latest smart-money refresh timestamp available to the snapshot |
cache_max_age_ms | Suggested client-side cache TTL for local bootstrap hydration |
spotlight_markets | Ready-to-render smart-money spotlight cards |
playbook_previews | Per-playbook preview rows keyed by preset id |
GET /api/app-bootstrap
Returns the precomputed first-paint payload for /app.
Query params:
| Param | Meaning |
|---|---|
view | scanner or smart |
preset | Optional preset id such as smart_money_edge |
Important response fields include:
| Field | Meaning |
|---|---|
generated_at | Snapshot generation timestamp |
market_last_updated | Latest snapshot_at used when building the snapshot |
smart_money_last_updated | Latest smart-money refresh timestamp available to the snapshot |
view | Resolved app view after preset application |
active_preset_id | Resolved preset id, or null for default bootstraps |
filters | Resolved initial filter state for the first paint |
markets | Initial market rows rendered before live revalidation |
tags | Initial tag stats used by include/exclude autocomplete |
cache_key | Storage key used by the frontend for bootstrap caching |
GET /api/tags
Returns tag statistics used by the include/exclude tag UI.
| Field | Meaning |
|---|---|
tag_label | Tag label |
count | Number of occurrences in the current snapshot |
GET /api/status
Returns the last known refresh timestamps used by the UI header.
| Field | Meaning |
|---|---|
last_updated | Latest snapshot_at in active_market_outcomes |
smart_money_last_updated | Latest last_updated_at in market_smart_money_stats |
GET /api/markets
Returns the main scanner rows and accepts the query parameters documented in Scanner Query and Filter Contract.
Important response fields include:
| Field | Meaning |
|---|---|
market_id | Market identifier |
condition_id | Condition identifier used for holders lookup |
question | Market question |
outcome_name | Row outcome |
price | Stored outcome price |
apr | Computed APR |
spread | Stored spread |
volume_usd | Stored volume |
liquidity_usd | Stored liquidity |
start_date | Start date |
end_date | End date |
category | Primary category from tags |
icon_url | Event image/icon |
yes_profitable_count | Sampled profitable YES wallets |
yes_losing_count | Sampled losing YES wallets |
yes_total | Total sampled YES holder rows |
no_profitable_count | Sampled profitable NO wallets |
no_losing_count | Sampled losing NO wallets |
no_total | Total sampled NO holder rows |
GET /api/markets/{market_id}/holders
Returns holder rows for the condition represented by the selected market detail view.
| Field | Meaning |
|---|---|
wallet_address | Normalized holder wallet |
position_size | Current sampled position size |
outcome_index | YES / NO side index |
total_pnl | Joined wallet PnL if available |
alias | Optional wallet alias |
wallet_tag | Optional operational tag such as SYSTEM |
Contract stability
The homepage and initial /app load are intentionally snapshot-backed for speed. Live /api/markets remains the source for interactive filtering, pagination, and silent revalidation after first paint.
This reference documents what the current public app uses today. It should be read as a current implementation contract, not a long-term versioned API promise.