Genesis Arbitrage

Genesis Arbitrage · · 3 min read

ETag and If-None-Match

ETag is an HTTP response header that carries a version tag for the data: as long as the resource stays the same, so does the tag. The client sends the tag back in the If-None-Match header, and if the server still has that version, it answers 304 Not Modified with no body. Both headers are defined in RFC 9110 (HTTP Semantics, 2022).

How a conditional request works

A hypothetical exchange with the tag "a7f3c9":

StepRequestResponse
1GET /v1/funding/rates200, ETag: "a7f3c9", JSON body
2Same URL with If-None-Match: "a7f3c9"304 Not Modified, no body
3Same request after the data updates200, a new tag and new JSON

Under the standard, a 304 response ends with its headers and cannot carry a body, so the client reuses its own copy. The server compares the tags; the client only stores the last tag it received and sends it with the same request.

import os
import requests

URL = "https://api.genesisarbitrage.com/v1/funding/rates"
cache = {"tag": None, "data": None}  # the full set and its tag

def get_rates():
    headers = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
    if cache["tag"]:
        headers["If-None-Match"] = cache["tag"]
    r = requests.get(URL, headers=headers, timeout=10)
    if r.status_code == 304:
        return cache["data"]  # unchanged data, no quota used
    r.raise_for_status()
    cache["tag"] = r.headers.get("ETag")
    cache["data"] = r.json()["data"]
    return cache["data"]

# pick the coin locally: a request with coin comes without an ETag
btc = [row for row in get_rates() if row["coin"] == "BTC"]

ETag in Genesis API

Only a 200 response counts as a Genesis API call: a 304 does not use your quota, though it still counts toward the requests-per-second limit. It has no body, and responses under 64 KB do not count toward the download volume limit. Full datasets without filters carry the tag: a response to a request with coin or filters is built for that request and comes without an ETag, so there the filter itself saves the traffic (plans and limits).

Hypothetical example: a bot fetches the full funding analytics summary /funding/analytics/summary (Pro and Max plans) every 60 seconds. The section is about 600 KB gzipped, and its tag changes roughly every 15 minutes. Over 30 days that is 30 × 24 × 60 = 43,200 requests. With If-None-Match, only 30 × 24 × 4 = 2,880 of them download the full section; the other 40,320 come back as 304 with no body and no quota charge. Traffic drops from about 26 GB to 1.7 GB.

See also: API polling, HTTP 429, data freshness, Genesis API response format, ETag and errors, how to poll an API without hitting limits.

Questions and answers

Does a 304 response use Genesis API quota?

No. Only 200 responses use the quota; 304 and errors are free but still count toward the requests-per-second limit.

What if the response has no ETag?

Poll no more often than meta.freshness_sec and compare meta.updated_at with the previous response: the same value means the snapshot has not been updated.