# ResidualPlay API

> Free to query, public API over the ResidualPlay radar: overlooked Steam games still earning residual revenue. No key for reads; the screener CSV asks for a free identity (account or agent token), the bulk products are paid over x402, and the only writes are POST /analyze (open), the optional token issuance and the paid credits purchase (see auth.md). Cite ResidualPlay with a link when you publish something built on it.

- OpenAPI 3.1 description: https://residualplay.com/openapi.json
- API catalog (RFC 9727): https://residualplay.com/.well-known/api-catalog
- Machine index: https://residualplay.com/llms.txt
- Service health: https://residualplay.com/api/v1/health

## Reading the numbers

Every money field is NET to the developer and PER MONTH unless the name says lifetime. Net means VAT, refunds and Steam's cut are already removed, roughly 55% of gross. Estimates carry a +/-30-50% error range per title, tighter in aggregate.

- `residual_low_usd` / `residual_mid_usd` / `residual_high_usd`: estimated net revenue per month.
- `opportunity_usd`: that revenue weighted by how dormant the title is. Default sort.
- `neglect`: dormancy multiplier 1.0-3.0, fused from developer silence, discount history and build age.
- `reviews_per_month`: reviews posted, 6-month average. NOT units sold.
- `sales_12m`: number of discount promotions in the last 12 months. NOT units sold.
- `studio_status`: operating (active), fading (quiet), ghost (inactive, no public activity in 36+ months).

## Endpoints

| Endpoint | Returns |
|---|---|
| `GET /api/v1/radar` | The screener, with every filter below |
| `GET /api/v1/radar.csv` | The same query as CSV, up to 2000 rows (identified: free account or agent token) |
| `GET /api/v1/insights` | Catalog-wide research aggregates: decay, discounts, seasonality |
| `GET /api/v1/game/{appid}` | Full case file, including the analyst brief |
| `GET /api/v1/game/{appid}/history` | How the estimates moved over time |
| `GET /api/v1/game/{appid}/comps` | Comparable deals, same genre and era |
| `POST /api/v1/game/{appid}/analyze` | Queue an unanalyzed game, ready in about a minute |
| `GET /api/v1/game/{appid}/status` | Analysis state of that game |
| `GET /api/v1/studio/{slug}` | A developer's whole tracked catalog |
| `GET /api/v1/events` | Recent changes: wake-ups, first discounts, new grade A |
| `GET /api/v1/report/{YYYY-MM}` | The monthly Residual Report |
| `GET /api/v1/kpis` | Aggregates across the whole radar |
| `GET /api/v1/health` | Service health |

## Filters

Combine freely on `/api/v1/radar` and `/api/v1/radar.csv`: `q`, `genre`, `grade` (A|B|C|D), `status` (ghost|fading|operating), `ownership` (unclaimed|quiet|active|all; the screener DEFAULTS to ownership=unclaimed, the verified orphans, unless you pass an ownership value; status filters studio activity and does not lift that default), `evidence` (A|B: A means the full three-way case including a dead, parked or verifiably frozen studio website; B means Steam silence and no franchise, but no usable website evidence), `dormant=1`, `opp_min`, `opp_max`, `year_min`, `year_max`, `sent_min`, `owners_min`, `no_discount=1`, `proven=1`, `stale_build=1`, `loc_gap=1`, `sort` (opportunity|residual|rpm|silence), `page`, `per`.

Example, strategy titles from 2018 or earlier with at least $1k/month of opportunity:

`https://residualplay.com/api/v1/radar?genre=Strategy&year_max=2018&opp_min=1000`

Or any era, narrowed to titles whose players review in languages the game never shipped in:

`https://residualplay.com/api/v1/radar?opp_min=1000&year_max=2018&loc_gap=1`

## Markdown for agents

Send `Accept: text/markdown` to the main pages (/, /radar, /docs, /insights, /game/{appid}, /studio/{slug}, /report/{YYYY-MM}) for clean Markdown plus an `X-Markdown-Tokens` header. Case files are also at `/game/{appid}.md` with no header needed.

## Paid bulk data (x402)

Individual queries stay free. Bulk extracts are paid over x402 (scheme exact, USDC on Base, settling through Stripe): orphans.csv with evidence 15 USDC, full catalog.csv 5, 10k request credits 5 (POST /api/v1/agent/credits with your bearer), research.json 2, bulk/radar.json 1, bulk/game/{appid}.json 0.05. Flow: request the endpoint (GET; POST for the credits product), read the PAYMENT-REQUIRED header of the 402 (base64 JSON with price, asset, payTo, network), pay, retry with PAYMENT-SIGNATURE. The free JSON radar pages at up to 100 rows per request and the free identified CSV caps at 2,000 rows, while bulk/radar.json returns the whole result of any query in one JSON response with no cap; the paid game dossier bundles case file + full history + comps in one payload. Agents with card credentials can pay the same endpoints over MPP (a WWW-Authenticate Payment challenge rides on the same 402; a 0.70 USD floor applies). Full detail: https://residualplay.com/auth.md

## Rate limits

120 requests per minute per IP on reads, 10 on CSV exports, 5 on on-demand analysis; an agent bearer multiplies all three by 4, and purchased credits admit requests past an exhausted limit (see auth.md). For a NON-standard custom extract write to contact@residualplay.com.

## How these numbers are built

1. Units: Steam-purchase reviews only (key activations excluded) times a release-cohort multiplier, 40-75x depending on release year. Cohorts from 2020 on are calibrated against 182 sales milestones announced by the developers themselves; older cohorts follow the published Boxleiter tables.
2. Price: an effective price that accounts for lifetime discount depth and Steam regional pricing, not the US list price.
3. Net: VAT (~13%), refunds (~9.5%) and Steam's 30% cut are removed, so roughly 55% of gross reaches the developer. Every dollar figure on this site is net to the developer.

Estimates carry a +/-30-50% error range per title and are tighter in aggregate. They are built from public signals only (Steam reviews and review history, store metadata, developer announcements, price and discount history, public build dates) and are directional, not financial statements.

Famous titles and actively operating major publishers are excluded by design: this is the long tail nobody is watching.

Citation: please cite ResidualPlay (https://residualplay.com) when you publish or quote these estimates.