# CuckooTrade

> Free, deterministic, Alpaca-compatible FAKE market data API. No API key, no
> signup. All data is synthetic — for development, CI, demos, and teaching,
> never for real trading decisions or strategy validation.

Path scheme: /api/v1/{provider}/<provider's own path> mimics that provider's
wire format; /api/v1/... without a provider segment is CuckooTrade-native.
Providers: alpaca (data.alpaca.markets), alphavantage (www.alphavantage.co),
polygon (api.polygon.io). All three serve the same deterministic world, so
the same symbol+day returns identical OHLCV through every surface.

## Why use it
- No auth: the first request works from curl, CI, or a coding agent.
- Deterministic: identical requests return identical bars, forever
  (generation-versioned). Optional &seed=<any-string> selects a different but
  equally deterministic dataset. Only completed bars are served, so responses
  are reproducible.
- Wire-compatible: alpaca-py works unmodified with
  url_override="https://cuckootrade.com/api/v1/alpaca" (API keys: any
  non-empty strings); Alpha Vantage and Polygon clients need only their base
  URL swapped (api keys accepted and ignored).
- Magic tickers with scripted behavior for testing edge cases.

## Endpoints
- GET /api — machine-readable index (start here)
- GET /api/v1/alpaca/v2/stocks/bars?symbols=AAPL,CRASH&timeframe=1Day&start=2026-07-01
  Alpaca-shaped bars: {"bars": {SYM: [{t,o,h,l,c,v,n,vw}]}, "next_page_token"}.
  Params: symbols (required, ≤50), timeframe ([1-59]Min, [1-23]Hour, 1Day,
  1Week, [1,2,3,4,6,12]Month), start, end, limit (total bars across symbols,
  ≤10000, then next_page_token → page_token), sort (asc|desc), seed,
  generation. adjustment/feed/asof/currency accepted and ignored.
- GET /api/v1/alpaca/v2/stocks/{symbol}/bars — single-symbol variant
- GET /api/v1/alpaca/v2/stocks/bars/latest?symbols=AAPL,SPY — last completed bar each
- GET /api/v1/alphavantage/query?function=TIME_SERIES_DAILY&symbol=IBM
  Alpha Vantage shape: {"Meta Data": {...}, "Time Series (Daily)": {date:
  {"1. open": "...", ...}}}, newest first, string values. Functions:
  TIME_SERIES_INTRADAY (interval=1min|5min|15min|30min|60min, premium on the
  real API but free here), TIME_SERIES_DAILY, TIME_SERIES_WEEKLY,
  TIME_SERIES_MONTHLY, GLOBAL_QUOTE. outputsize=compact(100)|full; month=
  YYYY-MM for intraday. Errors are HTTP 200 with {"Error Message": ...},
  matching the real API. Completed bars only; RTH only.
- GET /api/v1/polygon/v2/aggs/ticker/MSFT/range/1/day/2026-07-01/2026-08-01
  Polygon aggregates shape: {"ticker","queryCount","resultsCount","adjusted",
  "results":[{v,vw,o,c,h,l,t(ms),n}],"status":"OK","request_id","count",
  "next_url"?}. timespan: minute(1-59)|hour(1-23)|day|week|month(1,2,3,4,6,12)
  |quarter(1,2,4)|year; from/to as YYYY-MM-DD or Unix ms; sort, limit ≤50000,
  cursor pagination via next_url. Empty windows omit results/count. Errors:
  HTTP 4xx {"status":"ERROR","request_id","error"}.
- GET /api/v1/polygon/v2/aggs/ticker/MSFT/prev — previous session's daily bar
- GET /api/v1/stream?symbols=CUCKOO — SSE ticks. clock=demo (default) is an
  always-open synthetic session; clock=real follows the NYSE calendar.
  curl -N works. ≤10 symbols, ≤5 streams/address, 15-min max per connection.

## Behavior
- NYSE calendar: no bars on weekends/US market holidays; intraday bars only
  09:30–16:00 ET. Daily+ bars are timestamped midnight ET (in UTC).
- Coarser timeframes aggregate exactly from finer ones (coherent OHLCV).
- Any well-formed symbol works: ~130 famous tickers have curated plausible
  price levels; every other string gets a stable hash-derived personality.
- Magic tickers (calendar-anchored, visible in any 30-day window):
  CRASH (~25% mid-month crash), MOON (monthly parabolic pump), FLAT (o=h=l=c
  at $100), GAPPY (±5-15% overnight gaps), HALTS (missing minute bars),
  SPIKEY (one-minute wicks), PENNY (~$0.30, 4 decimals), CHOPPY (high vol,
  no drift).
- Errors: {"code": int, "message": str}; messages include the valid grammar
  and a working example URL. 429 = rate limited (60/min sustained per address,
  burst 120); honor RateLimit-Reset.
- Every response carries X-Cuckoo-Synthetic: true.

## Links
- Docs: https://cuckootrade.com/docs
- OpenAPI: https://cuckootrade.com/api/openapi.json
- Playground: https://cuckootrade.com/playground
- Source (MIT): https://github.com/tj-miller-dev/stock_simulator