Overview

#The shape of a request

GET https://api.bytnode.com/v1/<family>/<metric>
  ?symbol=BTCUSDT       # required on per-asset routes
  &timeframe=1h         # on bucketed routes
  &limit=100            # on /history routes
  &fields=time,rate_pct

X-API-KEY: your_key

The path says the family and the metric. The parameters say the asset, the timeframe and the depth. The header carries the key. There is nothing else to know to call any of the routes.

One endpoint alone escapes this shape: POST /v1/indicators, which takes a JSON body because it describes a computation, not a read.

#Latest value or history

Most metrics come in two versions. The bare route returns the latest value: an object, or null. The /history suffix returns a list of closed windows only, from the newest to the oldest.

# The latest value
GET /v1/basis?symbol=BTCUSDT

# The last 24, from newest to oldest
GET /v1/basis/history?symbol=BTCUSDT&timeframe=1h&limit=24

# A dated window, in epoch milliseconds (here the last 12 hours, computed by the shell)
NOW=$(( $(date +%s) * 1000 ))
curl -H "X-API-KEY: $BYTNODE_API_KEY" \
  "https://api.bytnode.com/v1/basis/history?symbol=BTCUSDT&timeframe=1h&since_ms=$(( NOW - 43200000 ))&until_ms=$NOW"

#Common parameters

#Paginating a history

Every /history route pages with next: each response carries the URL of the following page, or null once the range is read. Rows come newest first by default; with order=asc (and since_ms), oldest first. Every row carries time and is_closed.

1. Ask for a first page: limit rows, with no bound for the most recent ones, or since_ms and order=asc to read forward from a date.
2. Call next as is: it is the relative URL of the following page (/v1/klines/history?symbol=BTCUSDT&timeframe=1h&limit=500&before_ms=…), your parameters included — prefix it with the API host. Backwards, it uses before_ms, an EXCLUSIVE bound: no row comes back twice, nothing to subtract.
3. Stop when next is null: the range is read, or the following page would leave the history window of your plan (the last page then asks only for the rows that still fit). A 403 history_depth only comes back if you write a bound beyond that window yourself; GET /v1/limits gives the windows of your plan. On individual trades (/v1/trades/*) a page covers at most 15 minutes and can be empty or partial while next is not null: only next: null ends the range. The same holds on every paged route: a history read that reaches a dense period returns, within its time budget, the rows it has read — a short page with a next, never a timeout. The official SDKs follow next for you.

import os

import requests  # pip install requests


def history(path: str, params: dict, max_pages: int = 20) -> list[dict]:
    """Every row of a /history route, following `next` until the range is read."""
    rows: list[dict] = []
    url, query = f"https://api.bytnode.com{path}", params
    for _ in range(max_pages):
        body = requests.get(
            url,
            params=query,
            headers={"X-API-KEY": os.environ["BYTNODE_API_KEY"]},
            timeout=30,
        ).json()
        if body["status"] == "error":
            # history_depth: the range asked goes further back than your plan's window;
            # error.message gives the largest limit that fits. Never swallow it.
            raise RuntimeError(f'{body["error"]["code"]}: {body["error"]["message"]}')
        page = body["data"] or []
        rows += page
        if body.get("next") is None:
            break  # the range is read
        # `next` is the relative URL of the following page, your parameters
        # included: call it as is. It never repeats a row.
        url, query = f"https://api.bytnode.com{body['next']}", None
    return rows


# Without `limit`, each page stops at your plan's history window: no 403.
candles = history("/v1/klines/history", {"symbol": "BTCUSDT", "timeframe": "1h"})

#The families

Every route fits on one page in the endpoint catalogue; every field of every route, with its unit and a real response, is in the interactive reference.