CuckooTrade is a free, deterministic synthetic market data API for building and testing trading software. It serves openly fake data over the wire formats of Alpaca, Alpha Vantage, and Polygon, so an existing client works by changing only its base URL. There is no API key and no signup.

Do I need an API key or an account?

No. There is no key, no signup, and no billing. Requests are rate limited by address at 60 per minute sustained with a burst of 120. Keylessness is deliberate: CI pipelines and coding agents cannot sign up for accounts.

What does deterministic mean here?

Every bar is a pure function of symbol, timestamp, generation, seed, and as_of. There is no database - data is computed, not stored - so identical requests return identical bytes permanently. That makes committed test fixtures stay valid and CI runs reproducible. If the generator is ever improved, that becomes a new generation and the old one stays queryable forever.

What are scenario tickers?

Reserved ticker symbols that return scripted market behavior on demand: CRASH produces a roughly 25% drawdown, HALTS omits minute bars mid-session, STALE freezes the feed while timestamps keep advancing, GAPPY produces large overnight gaps, FLAT returns zero-range bars, PENNY returns sub-dollar prices with four decimals. Each is anchored to the calendar so its signature appears in any 30-day window. No real data provider can offer this at any price.

Can I make the API fail on purpose to test error handling?

Yes. Add scenario= to any request: flap:2 fails twice then succeeds, status:503 returns that status in the provider's own error shape, slow:2000 delays the response, truncate cuts the body short, and on the stream drop:20s kills the socket mid-frame. Nothing fires without the parameter, and every fault is deterministic, so the resulting tests are not flaky and can live in CI.

Can I use CuckooTrade to backtest a trading strategy?

No, and this is the one way the tool can genuinely mislead someone. The data is synthetic, so a strategy that profits against it has learned the generator rather than the market. CuckooTrade exists to exercise code paths - parsing, pagination, retries, charting, alerting - not to validate strategies. Every response is marked X-Cuckoo-Synthetic: true.

Yes. The engine is stateless and MIT licensed, and the container image is published to GHCR: docker run -p 8000:8000 ghcr.io/tj-miller-dev/cuckootrade. Because the data is computed rather than stored, a local instance serves byte-identical responses to cuckootrade.com for the same generation.

Synthetic market data API

What happens ifyou need a live feed on Saturday?

the endpoint that answers it

$curl -N 'https://cuckootrade.com/api/v1/stream?symbols=CUCKOO,CRASH'

Server-sent events, curl-able, no key and no WebSocket client — and the synthetic session never closes.

CuckooTrade is a free, deterministic market data API that speaks Alpaca, Alpha Vantage, and Polygon — and serves the market conditions you can't schedule and the failures no provider will sell you. Every answer is one URL, with no key and no signup behind it.

Open the playground Read the docs

No API key, no signup
Free — 60 requests/min
Open source, MIT

1 lineto switch to your real provider

3provider wire formats mimicked

100%reproducible, byte for byte

24/7synthetic sessions, even when markets close

Compatibility

A drop-in for the API you already use

Same paths, same parameters, same JSON shape as the provider you're replacing — Alpaca, Alpha Vantage, or Polygon. Your client works unmodified: change the base URL to develop against CuckooTrade, then point it back when you're ready for live data.

The provider lives in the path — /api/v1/alpaca/…, /api/v1/alphavantage/…, /api/v1/polygon/… — and every surface serves the same deterministic world, so a symbol's bars agree across all of them.

See the full endpoint reference →

  client = StockHistoricalDataClient(
      api_key, secret_key,
-     url_override="https://data.alpaca.markets",
+     url_override="https://cuckootrade.com/api/v1/alpaca",
  )

- curl 'https://www.alphavantage.co/query?
+ curl 'https://cuckootrade.com/api/v1/alphavantage/query?
      function=TIME_SERIES_DAILY&symbol=IBM&apikey=any'

- curl 'https://api.polygon.io/v2/aggs/
+ curl 'https://cuckootrade.com/api/v1/polygon/v2/aggs/
      ticker/MSFT/range/1/day/2026-07-01/2026-08-01'

Why CuckooTrade

Built for development, CI, and demos

Real market data APIs need keys, cost money, rate-limit your CI, and go quiet when markets close. CuckooTrade removes all of that for the phases where real data isn't the point.

No key, no signup

Your first request works from curl, CI, or any HTTP client — no account and no secrets to manage. Free at 60 requests per minute per address, with standard rate-limit headers.

Deterministic by design

Every bar is a pure function of symbol, timestamp, and seed. Identical requests return identical bytes, so committed fixtures stay valid and test runs stay reproducible.

Always open

The data follows the real NYSE calendar, but the API never closes. Charts stay realistic and streams keep ticking on nights, weekends, and holidays.

Scenario tickers

Test the market conditions you can't schedule

Reserved symbols return scripted market behavior on demand — crashes, halts, overnight gaps, fat-finger spikes. Each pattern repeats on a calendar anchor, so it appears in any 30-day window and reproduces in every environment. Select a ticker to open it in the playground.

$CRASH — a ~25% crash mid-month with a slow recovery, every month.
$MOON — parabolic run-up peaking late in the month, then a hard correction.
$FLAT — zero-range bars pinned at exactly $100.00.
$GAPPY — overnight gaps of 5–15% most days.
$HALTS — minute bars missing during intraday halt windows.
$STALE — the feed freezes mid-session: same price, no trades, clock moves on.
$SPIKEY — single-minute wicks that spike and instantly revert.
$PENNY — sub-dollar prices with four decimal places.
$CHOPPY — high volatility with zero net drift.

Testing a bot against a crash, halt, or gap →

Fault injection

And the failures no provider will sell you

Scenario tickers break the data. scenario= breaks the transport: a 503 on demand, a response that hangs, a body that stops halfway through, a socket that dies mid-frame. The one that matters most is flap:2 — the endpoint fails twice and then works, so your retry and backoff have something to actually recover from.

Nothing fires without the parameter, and every fault is deterministic: drop:20s drops at twenty seconds, every time, for everyone. Random chaos makes flaky tests. These are built to live in CI.

How to test retry logic →

break it on purpose

$ curl '…/bars?symbols=AAPL&scenario=flap:2'
fails twice, then serves normally

$ curl '…/bars?symbols=AAPL&scenario=status:503'
that status, in the provider's error shape

$ curl -N '…/stream?symbols=CUCKOO&scenario=drop:20s'
socket dies at 20s, mid-frame, no close event

Determinism

Same request, same bytes

Don't take our word for it. Your browser is fetching the identical request twice right now and comparing SHA-256 hashes of the two raw responses.

Because every bar is computed, not stored, data you fetched yesterday never shifts underneath you — and neither does next month's re-run of your test suite. The guarantee is versioned: if the generator ever changes, that becomes generation 2, and generation 1 stays queryable.

How the guarantee works →

Integration

Works from any stack

Plain HTTP with permissive CORS — no client library required. Use the official Alpaca SDKs, fetch from the browser, script it with curl, or subscribe to the live SSE stream — the ticker running at the top of this page is that stream, and curl -N gets you the exact same feed.

AI coding tools are covered too: a machine-readable index at /api and llms.txt let them discover and use the whole API on their own.

curl 'https://cuckootrade.com/api/v1/alpaca/v2/stocks/bars?symbols=AAPL,CRASH&timeframe=1Day&start=2026-07-01'

from datetime import datetime

from alpaca.data.historical import StockHistoricalDataClient
from alpaca.data.requests import StockBarsRequest
from alpaca.data.timeframe import TimeFrame

client = StockHistoricalDataClient(
    api_key="any", secret_key="any",  # never checked
    url_override="https://cuckootrade.com/api/v1/alpaca",
)
bars = client.get_stock_bars(StockBarsRequest(
    symbol_or_symbols=["AAPL", "CRASH"],
    timeframe=TimeFrame.Day,
    start=datetime(2026, 7, 1),
))
print(bars["CRASH"][0])

const res = await fetch(
  'https://cuckootrade.com/api/v1/alpaca/v2/stocks/bars' +
  '?symbols=AAPL,CRASH&timeframe=1Day&start=2026-07-01'
)
const { bars } = await res.json()
console.log(bars.CRASH[0])

# server-sent events: a live synthetic feed
curl -N 'https://cuckootrade.com/api/v1/stream?symbols=CUCKOO,CRASH'

Synthetic by design

Openly fake, clearly labeled

Nothing on CuckooTrade is real market data, and nothing pretends to be. Every response is generated on demand and marked with an X-Cuckoo-Synthetic: true header, so a test fixture can never be mistaken for the real thing.

That also defines the boundary: CuckooTrade is for exercising code paths — development, testing, demos, teaching. It is not suitable for backtesting or strategy validation, because results against synthetic data say nothing about real markets.

response headers

HTTP/2 200
content-type: application/json
x-cuckoo-synthetic: true
x-cuckoo-generation: 1
cache-control: public, max-age=31536000, immutable

Make your first request

No key, no signup, no setup — this command works right now.

$ curl 'https://cuckootrade.com/api/v1/alpaca/v2/stocks/bars?symbols=AAPL,CRASH&timeframe=1Day'

Open the playground Read the docs