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":
| Step | Request | Response |
|---|---|---|
| 1 | GET /v1/funding/rates | 200, ETag: "a7f3c9", JSON body |
| 2 | Same URL with If-None-Match: "a7f3c9" | 304 Not Modified, no body |
| 3 | Same request after the data updates | 200, 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.