Genesis Arbitrage

Genesis Arbitrage · · 11 min read

Genesis API responses and errors: JSON format, ETag and 304, HTTP codes

In short

  • A successful Genesis API response is an envelope of success, data and meta; an error is success: false plus an error object with a code and a message.
  • Sending the previous ETag in If-None-Match returns 304 with no body when the data has not changed, and a 304 costs no quota.
  • Retry 429 and 503 after the Retry-After pause. A retry will not fix 400, 401, 403, 404 or 410 — change the request, the key or the plan.

Genesis API answers every request in JSON, a text data format built from key–value objects and arrays. A successful response always comes in the same envelope of success, data and meta; an error comes with an HTTP status code and an error object. The status code tells your program what to do next: use the data, wait Retry-After seconds and retry, or fix the request.

Response envelope: success, data and meta

A shortened GET /arbitrage/spot-spot response from the documentation (the endpoint is available on every plan):

{
  "success": true,
  "data": [
    {
      "coin": "FUEL",
      "exchange_buy": "ByBit",
      "exchange_sell": "Gate",
      "spread_pct": 0.11,
      …
    }
  ],
  "meta": {
    "count": 214,
    "updated_at": 1783802410,
    "freshness_sec": 10,
    "plan": "pro"
  }
}
FieldTypeContents
successbooleantrue — the request succeeded, false — an error
dataarray or objectThe endpoint's data
meta.countintNumber of items in data
meta.updated_atintUnix time the data was built
meta.freshness_secintServing delay for your plan, seconds
meta.planstringYour plan, pro in the example

The exception is funding analytics: its meta carries count, updated_at and schema_version, with no freshness_sec or plan. The envelope is described in the Response format section of the documentation, and the data fields on each endpoint's page.

Three conventions apply to every endpoint:

data: an array of rows or an object

The shape of data is stated in each endpoint's description. For GET /arbitrage/spot-spot it is an array: one item per arbitrage pair, like a row of the table on the site. For GET /account/usage it is a single object with the state of your key:

curl "https://api.genesisarbitrage.com/v1/account/usage" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
  "success": true,
  "data": {
    "plan": "pro",
    "calls_used": 184201,
    "calls_limit": 5000000,
    "rps_limit": 5,
    "freshness_sec": 10,
    "period_resets_at": 1786492800
  },
  "meta": { … }
}

/account/usage is available on every plan and shows your plan, quota usage and freshness_sec: polling more often than that gains nothing. The fields are described in Usage, and the first request is walked through in the quick start. Code that works with several endpoints should check the shape explicitly: isinstance(data, list) in Python.

Filters: optional, full dataset without them

All filter parameters are optional: a request without them returns the endpoint's full dataset. List several exchanges in exchange separated by commas, and set a coin by its ticker in coin:

curl -G --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -d coin=BTC -d exchange=Binance,OKX -d min_spread=0.5 \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

The -G flag turns the -d parameters into a query string: ?coin=BTC&exchange=Binance,OKX&min_spread=0.5. Spell exchange names the way they come back in response fields: ByBit, Gate, MEXC. Arbitrage endpoint parameters are in the arbitrage endpoints guide.

The quota counts responses, not rows: a request with or without filters is one call. A filter shrinks the response body, and with it the traffic and the download-limit usage. All limits are covered in the Genesis API limits guide.

gzip compression

Genesis API sends full datasets and large responses gzip-compressed when the client sends the Accept-Encoding: gzip header (RFC 9110, section 12.5.3). A small response may arrive uncompressed.

Python requests sends that header itself and decompresses the response. curl does not ask for compression without the --compressed flag; with the flag, it asks and decompresses.

The download limit counts compressed data: at most 60 MB per 10 seconds per key, and responses under 64 KB are not counted. Over the limit you get 429 download_limited.

ETag and 304: skip unchanged data

ETag is a response header with a version tag of the data. The client sends that tag back in the If-None-Match header. If the data has not changed, the server answers 304 Not Modified with no body; if it has, a regular 200 with new data and a new ETag.

# Full dataset, no filters: print the response headers only
curl -sS -D - -o /dev/null --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

# Repeat with the ETag from the first response (illustrative value)
curl -sS -D - -o /dev/null --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX" \
  -H 'If-None-Match: W/"5d1f0c9a"'

An ETag comes with the response to a request without filters and changes with every new data snapshot. A response to a filtered request is built for that request and comes without an ETag; there the filter itself saves the traffic. ETags help most on slow-moving data: the funding analytics summary changes its ETag roughly every 15 minutes, and 304 replies do not count toward its full-download limit.

A 304 response uses no quota but counts toward the requests-per-second limit. Send the tag back exactly as it arrived: under RFC 9110 it is a quoted string, and the W/ prefix marks a weak tag.

Error codes and what to do

On an error, Genesis API returns the matching HTTP status and a body with success: false:

{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Requests per second limit exceeded."
  }
}

error.code is a machine-readable code your program can branch on. error.message is the explanation for a human: for 400 it gives the reason, for 410 the replacement address.

HTTPerror.codeMeaningWhat to do
400bad_requestInvalid request parameters, for example volume=700 on /orderbooks/execFix the parameters per message: the same request will fail again
401invalid_keyKey missing, invalid or revoked, or the API subscription expiredCheck the X-API-Key header and the subscription status in your profile
403plan_restrictedThe endpoint is not in your planMove to a plan that includes it or drop the request
404not_foundEndpoint or resource not found: dataset, section, coin, order bookCheck the path and parameters against the documentation
410goneThe endpoint is retiredSwitch to the address given in message
429rate_limitedRequests-per-second limit exceeded, or the period quota is used upWait Retry-After seconds and slow down; if the quota is used up, wait for the reset or upgrade the plan
429download_limitedDownload volume exceeded: 60 MB of compressed data per 10 s per keyWait Retry-After, cut traffic with filters, coin and If-None-Match
500internal_errorInternal errorRetry later; if it persists, contact support with the X-Request-Id
503snapshot_not_readyData is being rebuilt or its source is restartingRetry after Retry-After seconds

The Retry-After header comes with 429 and 503 and holds the number of seconds to wait: usually a few seconds, but when the period quota is used up it is the time until the quota resets, which can be days. 4xx and 5xx errors use no quota but count toward the requests-per-second limit, so an early retry will most likely return the same error. Glossary terms: HTTP 429 and rate limit.

X-Request-Id: what to send to support

Every Genesis API response, successful or not, carries an X-Request-Id header with the request's identifier. If an error keeps coming back or the data looks wrong, send support:

Do not send your key. If it ended up in a chat, logs or code that other people can see, reissue it in your profile: the old key stops working immediately.

Response handling order

  1. Check the status code

    200 — read data and meta, and store the ETag if one came. 304 — use the data from the previous response.

  2. Handle temporary errors

    429 and 503 with a short pause — wait Retry-After seconds and retry, at most three times in a row. 500 — retry later.

  3. Stop on request errors

    400, 401, 403, 404, 410, and a 429 with a pause of hours or days — fix the parameters, the key or the plan, or wait for the quota reset.

  4. Check the data age

    Compare meta.updated_at with the current time: a bot acting on an old snapshot sees spreads that are already gone.

  5. Schedule the next request

    No sooner than meta.freshness_sec seconds later, with If-None-Match for requests without filters.

A get_json function in Python

The function puts these rules together: it keeps the last ETag for each address and returns the previous data on 304, waits Retry-After on 429 and 503 and retries up to three times, but does not wait out pauses longer than a minute. Other errors raise an exception with the status, the message and the X-Request-Id. The key comes from the GENESIS_API_KEY environment variable.

import os
import time
import requests

BASE = "https://api.genesisarbitrage.com/v1"
session = requests.Session()
session.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}  # (path, params) -> (ETag, data)


class GenesisError(Exception):
    def __init__(self, status, text):
        super().__init__(f"{status} {text}")
        self.status = status


def get_json(path, params=None):
    key = (path, tuple(sorted((params or {}).items())))
    for attempt in range(4):  # one request plus up to 3 retries
        hdr = {"If-None-Match": cache[key][0]} if key in cache else {}
        r = session.get(BASE + path, params=params,
                        headers=hdr, timeout=15)
        if r.status_code == 304:
            return cache[key][1]  # the data has not changed
        wait = float(r.headers.get("Retry-After", 1))
        if r.status_code in (429, 503) and attempt < 3 and wait <= 60:
            time.sleep(wait)  # never wait out hours or days
            continue
        try:
            body = r.json()
        except ValueError:
            raise GenesisError(r.status_code, "not JSON") from None
        if r.status_code != 200 or not body.get("success"):
            err = body.get("error") or {}
            raise GenesisError(r.status_code, (
                f"{err.get('code')}: {err.get('message')}; "
                f"X-Request-Id {r.headers.get('X-Request-Id')}"))
        if "ETag" in r.headers:  # only on responses without filters
            cache[key] = (r.headers["ETag"], body["data"])
        return body["data"]

The timeout=15 parameter is a must: without a timeout, requests waits for a response forever.

Polling at your plan's interval: the full dataset comes with an ETag, and rows are filtered in code. 4xx errors stop the program; a server failure waits for the next cycle.

pause = get_json("/account/usage")["freshness_sec"]
while True:
    try:
        rows = get_json("/arbitrage/spot-spot")  # full dataset
        top = [x for x in rows if x["spread_pct"] >= 1]
        print(len(top), "pairs with a spread of 1% or more")
    except GenesisError as e:
        if e.status < 500:
            raise  # 4xx: the request, key, plan or quota
        print("server error, retrying next cycle:", e)
    time.sleep(pause)

Questions and answers

Does a 304 response use quota?

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

What should I do after a 410 ?

The endpoint is retired, and the replacement address is in error.message. For example, GET /arbitrage/predictions was retired on November 15, 2026, and its message points to /predictions/arbitrage. Update the path in your code.

Why is data empty when there is no error?

The filters removed every row: for example, min_spread is above every current spread. Such a response has meta.count equal to 0, so relax the filter.

Why is there no ETag in the response?

An ETag comes with the response to a request without filters. A response to a request with coin, exchange, min_spread or another filter is built for that request and comes without a tag, so If-None-Match does not apply to it.