Data freshness
Data freshness is the age of data at the moment it reaches you: how many seconds have passed between the data being built and your response arriving. In arbitrage it decides whether a spread is still alive: a pair priced on minute-old quotes may have closed before your request.
Freshness by Genesis API plan
The Genesis Arbitrage core refreshes data every second, and your Genesis API plan sets how often the API output is updated. Every response carries your plan's value in meta.freshness_sec and the data build time in meta.updated_at (response format).
| Plan | freshness_sec | Poll at most |
|---|---|---|
| Trial | 60 | once per 60 s |
| Start | 30 | once per 30 s |
| Pro | 10 | once per 10 s |
| Max | 5 | once per 5 s |
Polling faster than freshness_sec returns the same snapshot. Send the ETag of your previous response in If-None-Match: if nothing has changed, the API answers 304 with no body, and that response does not use quota (ETag and If-None-Match, API polling). While data is being rebuilt you get 503 snapshot_not_ready; retry after Retry-After seconds.
Order book and venue age
Order books carry their own time. In /orderbooks/book and /orderbooks/coin/{coin} every book has book_ts (the book time), age_sec (its age in seconds) and stale, which is true when the book is older than 30 s. Books lag the exchange by 5–20 seconds (market order book).
age_sec is computed when the response is built, so at the moment of receipt now − book_ts is more accurate. For prediction markets, /predictions/platforms shows freshness per venue: quotes_at is the time of its latest quotes and full_scan_at of its latest full scan.
Checking it in code
Order books are on the Pro and Max plans, while the meta check is the same for every endpoint.
import os
import time
import requests
URL = "https://api.genesisarbitrage.com/v1/orderbooks/book"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
def get_json(params, tries=3):
for _ in range(tries):
r = requests.get(URL, headers=HEADERS, params=params,
timeout=10)
if r.status_code in (429, 503): # rate limit or rebuild
time.sleep(int(r.headers.get("Retry-After", "5")))
continue
r.raise_for_status()
return r.json()
raise RuntimeError("data not ready")
params = {"exchange": "Binance", "market": "spot", "coin": "BTC"}
body = get_json(params)
now = time.time()
meta = body["meta"]
print(f"snapshot age {now - meta['updated_at']:.0f} s,"
f" plan freshness {meta['freshness_sec']} s")
book = body["data"]
ts = book["book_ts"]
if book["stale"] or ts is None or now - ts > 30:
print("order book is stale, skipping the signal")
See also: Genesis API limits, polling an API without hitting limits, automation risks, order book.
Questions and answers
How is freshness different from latency?
Latency is the whole path from an event on the exchange to your code: the exchange publishing it, collection, calculation, delivery and your polling interval. Freshness is the part you can see in the response: how long ago the snapshot was built. A server can answer in a fraction of a second and still return a minute-old snapshot.