Read-only endpoints for discovering live BTC binary, BTC perp, and BTC parlay markets, reading order books, fetching candles and recent trades, and hydrating bots with BTC reference-price, geometry, and funding context. Public read paths do not require an API key, though providing one enables self_role on trade responses.
/v1/marketsPublicReturns markets sorted by status (OPEN first), then by expiry. Use kind=BTC_BINARY for rolling BTC windows, kind=BTC_PERP for native/mirror perps, and kind=BTC_PARLAY for accepted parlay markets.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
status | query | no | string[] | Filter by status. Repeatable: ?status=OPEN&status=PENDING. Values: PENDING, OPEN, EXPIRED, RESOLVED, VOID. |
limit | query | no | int | Max results (1–250). Default 50. |
kind | query | no | string | Filter by market kind. Live launch kinds are BTC_BINARY, BTC_PERP, and BTC_PARLAY; future/non-BTC kinds remain gated unless explicitly enabled. |
curl -s "https://raeth.exchange/api/v1/markets?kind=BTC_BINARY&status=OPEN&limit=10" \
-H "Authorization: Bearer rk_live_…"
# Response (truncated)
[
{
"market": {
"id": "a7f3e2d1-4c5b-6a7b-8c9d-0e1f2a3b4c5d",
"symbol": "BTC-1M-20260601T1030Z",
"kind": "BTC_BINARY",
"metadata_json": {
"contract_type": "BTC_1M_UP_DOWN",
"window_seconds": 60,
"outcome_rule": "YES iff close_price_cents > open_price_cents (tie voids)"
},
"open_at": "2026-06-01T10:29:00Z",
"expiry_at": "2026-06-01T10:30:00Z",
"status": "OPEN",
"resolution": null,
"resolution_price_cents": null,
"created_at": "2026-06-01T10:29:00Z"
},
"best_bid_cents": 44,
"best_ask_cents": 51,
"last_trade_cents": 48,
"volume_24h_contracts": 1247,
"open_interest_contracts": 334
},
...
]| Name | In | Required | Type | Description |
|---|---|---|---|---|
market.id | body | no | UUID | Market UUID. |
market.symbol | body | no | string | Human label, e.g. "BTC-1M-20260601T1030Z". |
market.kind | body | no | string | Market kind, e.g. BTC_BINARY, BTC_PERP, or BTC_PARLAY. |
market.status | body | no | string | PENDING | OPEN | EXPIRED | RESOLVED | VOID. |
best_bid_cents | body | no | int | null | Best resting bid in market-scaled price units. Null if no bids. |
best_ask_cents | body | no | int | null | Best resting ask in market-scaled price units. Null if no asks. |
last_trade_cents | body | no | int | null | Most recent trade price in market-scaled price units. |
volume_24h_contracts | body | no | int | Total qty traded in last 24h. |
open_interest_contracts | body | no | int | Sum of open long positions (= short positions). |
Repeating BTC windows are grouped into a series so agents do not need to rediscover a new market every 60 seconds. Use /v1/seriesfor the current list and /v1/series/btc-up-down-1m/marketsfor recent/upcoming individual windows.
/v1/seriesPublicList the active repeating binary series.
/v1/series/btc-up-down-1m/marketsPublicRecent and upcoming individual BTC 60s binary markets in the series.
/v1/series/btc-up-down-1m/contextPublicThe main bot context endpoint for the rolling BTC binary. It includes the active window, next window, feed health, spot reference price, and seq_at_snapshot for WebSocket resume.
curl -s "https://raeth.exchange/api/v1/series/btc-up-down-1m/context?history_limit=6&upcoming_limit=5"
# Response (truncated)
{
"series_id": "btc-up-down-1m",
"kind": "BTC_BINARY",
"window_seconds": 60,
"seq_at_snapshot": 25973330,
"spot_price_cents": 7274623,
"spot_source": "median(binance,coinbase)",
"feed_health": { "connected": true, "active_source": "median(binance,coinbase)" },
"active_window": {
"market_id": "a8960a7d-5d6e-45da-b8c7-a7d7c85f5bae",
"symbol": "BTC-1M-20260601T1001Z",
"status": "OPEN",
"open_at": "2026-06-01T10:00:00Z",
"expiry_at": "2026-06-01T10:01:00Z",
"seconds_to_close": 42,
"open_price_cents": 7284148,
"reference_price_cents": 7274623,
"best_bid_cents": 1,
"best_ask_cents": 3,
"implied_yes_cents": 2,
"in_the_money": "NO"
},
"next_window": { "status": "PENDING", "seconds_to_open": 42 },
"upcoming_windows": [
{ "status": "PENDING", "seconds_to_open": 42 }
],
"recent_windows": []
}/v1/feed/btc-spot/historyPublicBucketed BTC spot history for chart pre-fill and strategy context. Live updates also arrive on the feed.btc WebSocket channel.
curl -s "https://raeth.exchange/api/v1/feed/btc-spot/history?seconds=900"
{
"symbol": "btc",
"source": "median(binance,coinbase)",
"points": [
{ "ts_ms": 1780317540000, "price_cents": 7274623 },
{ "ts_ms": 1780317541000, "price_cents": 7275031 }
]
}/v1/markets/{market_id}PublicSingle market by UUID. Same response shape as the list endpoint.
Try in Swagger →/v1/markets/{market_id}/bookPublicLive L2 snapshot from the in-memory book (always up to date — no DB round-trip). Use the returned seq_at_snapshot as since_seq when opening a WebSocket subscription; replay is at-least-once, so ignore duplicate or stale seqs.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
market_id | path | yes | UUID | The market to snapshot. |
depth | query | no | int | Number of price levels per side (1–99). Default 20. |
curl -s "https://raeth.exchange/api/v1/markets/{market_id}/book?depth=5" \
-H "Authorization: Bearer rk_live_…"
# Response
{
"market_id": "a7f3e2d1-…",
"bids": [[44, 15], [43, 8], [42, 22]], ← [price_cents, total_qty]
"asks": [[51, 12], [52, 6], [53, 19]],
"last_trade_price_cents": 48,
"seq_at_snapshot": 84721 ← use this with the WS since_seq to resume
}[price_cents, total_qty] where total_qty is the sum of all resting orders at that price level./v1/markets/{market_id}/candlesPublicServer-side OHLC buckets folded from trades, newest first. Prices stay in market-scaled price units; volume is a decimal string so JavaScript clients can parse large contract counts with BigInt.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
market_id | path | yes | UUID | The market to query. |
period_seconds | query | no | int | Bucket size in seconds (60-86400). Default 60. |
limit | query | no | int | Max buckets (1-2000). Default 500. |
curl -s "https://raeth.exchange/api/v1/markets/{market_id}/candles?period_seconds=60&limit=3"
# Response
[
{
"bucket_start_ts": "2026-06-17T12:00:00Z",
"period_seconds": 60,
"open_cents": 6000000,
"high_cents": 6001000,
"low_cents": 5999000,
"close_cents": 6000500,
"volume": "9007199254740993",
"trade_count": 42
}
]| Name | In | Required | Type | Description |
|---|---|---|---|---|
bucket_start_ts | body | no | datetime | Bucket start timestamp (UTC). |
open_cents / high_cents / low_cents / close_cents | body | no | int | OHLC price in market-scaled price units. |
volume | body | no | string | Decimal contract volume string; parse as BigInt in JavaScript when summing. |
trade_count | body | no | int | Number of trades folded into the bucket. |
/v1/markets/{market_id}/tradesPublicRecent trades, newest first. Cursor-based pagination — pass next_cursor from the previous response as the cursor query param to get the next page.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
market_id | path | yes | UUID | The market to query. |
limit | query | no | int | Results per page (1–1000). Default 100. |
cursor | query | no | string | Pagination cursor from a previous response. |
curl -s "https://raeth.exchange/api/v1/markets/{market_id}/trades?limit=5" \
-H "Authorization: Bearer rk_live_…"
# Response
{
"items": [
{
"seq": 84720,
"market_id": "a7f3e2d1-…",
"price_cents": 48,
"qty": 3,
"taker_side": "BUY",
"occurred_at": "2026-05-26T10:42:18.331Z",
"self_role": null
},
...
],
"next_cursor": "eyJzZXEiOiA4NDcxMH0"
}
# Paginate with cursor
curl -s "https://raeth.exchange/api/v1/markets/{market_id}/trades?cursor=eyJzZXEiOiA4NDcxMH0"| Name | In | Required | Type | Description |
|---|---|---|---|---|
seq | body | no | int | Globally monotonic trade sequence number. Use with WS since_seq. |
price_cents | body | no | int | Trade price in market-scaled price units. |
qty | body | no | int | Number of contracts traded. |
taker_side | body | no | BUY|SELL | Aggressor direction. "BUY" = taker lifted an ask. |
occurred_at | body | no | datetime | Trade timestamp (UTC). |
self_role | body | no | string|null | "maker", "taker", or null if not authenticated or not a party. |