API reference, Market data

WebSocket replay

Replay a past window over the same WebSocket, in exactly the live frames: a bot written for the live stream runs unchanged on the past. For backtests, debugging and demos.

Connect

Add the window to the WebSocket URL. Without replay_from the socket is the live one.

wss://api.femtos.xyz/v1/ws?ticket=$TICKET&replay_from=<ms|ISO>&replay_to=<ms|ISO>&speed=1|10|100|max

The ticket is the live socket's: POST /v1/ws-ticket with your key (single use, valid 30 s).

What you receive

• Subscribe as on the live socket: same channels, same filters, same "batch":"block".
• Each subscription first gets its snapshot: the state at replay_from, with the live semantics (last candles, last trades, last events).
• The clock starts on {"op":"replay.start"}, or 500 ms after your last subscribe.
• Frames are the live ones plus "replay":{"session","clock"}. ts.source is the original block time, ts.sent the replay clock: the node's data as it happened, no network latency added.
• Events of the three layers come in time order; at the same time HyperCore, then HyperEVM, then Elysium, then by block and log index.
• The replay waits for you when you read slower than it sends: it never cuts a slow reader.

Controls

Frames you send. Each is answered with a replay.status frame.

Frames the server sends about the replay itself. Each carries session and clock.

Channels

11 channels are replayed. A subscribe to any other channel is refused with invalid_param.

Not replayed yet: hc.bbo, hc.book, bridge.transfers and wallet.

Limits

Per key, by tier: the replay sessions open at once, the longest window one replays, and its fastest speed.

• Past them the upgrade answers replay_limit (429) or replay_window_too_large (400).
• speed=max is for paid tiers: a free key, or one past its credits, gets replay_speed_not_allowed (403 at the upgrade, an error frame on replay.speed) and replays at 100x at most.
• A session paused, not started, or running with no subscription for 5 minutes ends. A seek does not count as activity.
• The usual connection and subscription limits apply: 64 subscriptions per connection.
• The limits of your key: GET /v1/account, quotas.replay.

Billing

A replay counts as the live socket does: each frame by its bytes (1 credit per 48 KiB, uncompressed). A "batch":"block" frame counts as any other: its size grows with the events it carries. The replay.* frames, errors and pongs count nothing.

Good to know

• prices.hype replays the stored samples: the oracle and mark prices written every 30 s, and the exchange candles. What the live channel sends between them (the spot mid of each block, the oracle and mark as pushed) is not replayed.
• Order statuses (hc.orders) older than 7 days are read from slower storage: their replay runs at 10x at most.
• hyperevm.trades and elysium.trades need filter.pair, as on the live socket.
• replay_unavailable (503 at the upgrade): the replay engine cannot answer now, or the replays of free keys hold their whole share of it. The live socket is not affected.

Backtest example

Python (pip install websockets requests): one hour of BTC 1-minute candles at 100x (speed=max with a paid key), a moving average crossover.

import asyncio, json, os, requests, websockets

API, KEY = "https://api.femtos.xyz/v1", os.environ["FEMTOS_KEY"]

async def backtest():
    ticket = requests.post(f"{API}/ws-ticket", headers={"Authorization": f"Bearer {KEY}"}).json()["ticket"]
    url = f"wss://api.femtos.xyz/v1/ws?ticket={ticket}&replay_from=2026-10-20T12:00:00Z&replay_to=2026-10-20T13:00:00Z&speed=100"
    closes, position, pnl = [], 0, 0.0
    async with websockets.connect(url, max_size=None) as ws:
        await ws.send(json.dumps({"op": "subscribe", "channel": "hc.candles", "filter": {"coin": "BTC", "tf": "1m"}}))
        await ws.send(json.dumps({"op": "replay.start"}))
        async for raw in ws:
            m = json.loads(raw)
            if m.get("op") == "replay.end":
                break
            if m.get("channel") != "hc.candles" or m.get("snapshot"):
                continue
            c = m["data"]
            if closes and closes[-1][0] == c["t"]:
                closes[-1] = (c["t"], float(c["c"]))     # the open candle, updated
                continue
            closes.append((c["t"], float(c["c"])))
            px = [x for _, x in closes]
            if len(px) < 21:
                continue
            fast, slow = sum(px[-6:-1]) / 5, sum(px[-21:-1]) / 20
            target = 1 if fast > slow else -1
            if target != position:
                pnl -= (target - position) * px[-2]
                position = target
    print("pnl (1 BTC):", pnl + position * closes[-1][1])

asyncio.run(backtest())

More

• WebSocket streams: the live channels, each with its filter and frames.
• Plans and limits: what each tier can call and replay.
• Error codes: replay_limit, replay_window_too_large, replay_speed_not_allowed, replay_unavailable.
• This page as Markdown
• agents.md: the same text, with the whole API

Agent guide (agents.md)llms.txtOpenAPIMCP serverGet an API keyChangelog