Genesis Arbitrage

Genesis Arbitrage · · 11 min read

Your first API request: HTTP, headers and JSON

In short

  • An HTTP request to an API is a method, an address built from a base URL, path and parameters, and headers. The Genesis API key goes only in the X-API-Key header.
  • The status code tells you the next step: 200 means read the data, 304 means nothing changed, 401 and 403 mean check the key and plan, 429 and 503 mean wait Retry-After seconds.
  • A Genesis API response is an envelope of success, data and meta. Percentages arrive as plain numbers (0.01 means 0.01%), and time comes in unix seconds.
  • Common beginner mistakes are a key in the URL, an empty environment variable, and a typo in the path or a parameter name. A parameter typo raises no error: you get the full dataset instead of the filtered one.

To call an API, your program sends an HTTP request made of a method, an address and headers, and the server returns a status code, its own headers and a body, which for Genesis API is JSON. You can send the request from a terminal with curl or from code in any language that has an HTTP client. The first request below checks the key with /account/usage, and the second fetches BTC funding rates from /funding/rates. What an API is and what you can automate with it is covered in lesson 1.

Anatomy of a request

This is the request for BTC funding rates that curl sends to the server, as the -v flag shows it in lines starting with > (the key is replaced by a placeholder):

> GET /v1/funding/rates?coin=BTC HTTP/1.1
> Host: api.genesisarbitrage.com
> User-Agent: curl/8.7.1
> Accept: */*
> X-API-Key: gns_live_XXXXXXXXXXXXXXXX
PartIn the exampleWhat it means
MethodGETRead data; every Genesis API endpoint is GET
Base URLhttps://api.genesisarbitrage.com/v1Server and API version
Path/funding/ratesThe funding rates endpoint
Parameters?coin=BTCFilter: BTC only
HeaderX-API-KeyThe key the server uses to identify your account and plan

Parameters follow the ? as name=value pairs joined by &: ?coin=BTC&exchange=Binance,OKX. Genesis API filters are optional, so without coin the same endpoint returns every coin. Decimals take a dot, never a comma: min_spread=0.5.

Headers are name: value lines that travel with the address. Header names are case-insensitive (RFC 9110, section 5.1): X-API-Key and x-api-key are the same header, and a lowercase x-request-id in curl output is the same X-Request-Id. Genesis API accepts the key only in X-API-Key.

Status codes

The first line of the response carries the status code, and your program decides what to do next based on it:

CodeWhat it meansWhat to do
200Request served, data in the bodyRead data and meta
304Data unchanged since your last responseReuse the previous data
401Key missing, invalid, revoked or subscription expiredCheck the header and the subscription
403Endpoint not in your plan (plan_restricted)Change the plan or drop the request
429Request, download or quota limit exceededWait Retry-After seconds
503Data being rebuilt (snapshot_not_ready)Retry after Retry-After seconds

Only a 200 uses your quota: 304 and errors are free but still count toward the requests-per-second limit. A 304 comes back only to a request with an If-None-Match header; that header and the 400, 404, 410 and 500 codes are covered in Genesis API responses and errors. Why a retry after 429 needs a pause is explained in the glossary entry HTTP 429 Too Many Requests.

First request: /account/usage

/account/usage shows the state of your key: plan, quota used and limits. It is available on every plan and does not use up a call, so your first request goes there. Put the key in an environment variable first, then send the request:

# paste the key and press Enter: it will not show on screen
read -s GENESIS_API_KEY
export GENESIS_API_KEY

curl -i "https://api.genesisarbitrage.com/v1/account/usage" \
  -H "X-API-Key: $GENESIS_API_KEY"

The -i flag prints the status line and headers before the body. The response body, an illustrative example for the Trial plan:

{
  "success": true,
  "data": {
    "plan": "trial",
    "calls_used": 0,
    "calls_limit": 500000,
    "rps_limit": 1,
    "freshness_sec": 60,
    "period_resets_at": 1796463000
  },
  "meta": {
    "count": 1,
    "updated_at": 1794730811,
    "freshness_sec": 60,
    "plan": "trial"
  }
}

plan is your plan, and calls_used out of calls_limit is quota usage for the 30-day period. The example shows 0 because no other requests have been made yet, and /account/usage itself does not use up a call. rps_limit is requests per second, freshness_sec is how often your plan's data refreshes, and period_resets_at is when the quota resets. The fields are described in the Usage docs section.

Among the headers, find X-Request-Id, the request ID you send to support instead of your key, and X-RateLimit-Remaining, the number of requests left in the current rate-limit window.

The same request in Python

A script for Python 3.10+ with the requests library reads the key from the same environment variable:

import os
from datetime import datetime, timezone

import requests

BASE = "https://api.genesisarbitrage.com/v1"
key = os.environ["GENESIS_API_KEY"]  # KeyError if it is not set

r = requests.get(
    BASE + "/account/usage",
    headers={"X-API-Key": key},
    timeout=10,  # without a timeout, requests can wait forever
)
body = r.json()
if r.status_code != 200 or not body.get("success"):
    err = body.get("error") or {}
    raise SystemExit(f"{r.status_code} {err.get('code')}")

usage = body["data"]
ts = usage["period_resets_at"]
resets = datetime.fromtimestamp(ts, timezone.utc)
print("plan:", usage["plan"])
print("calls:", usage["calls_used"], "of", usage["calls_limit"])
print("quota resets:", resets.strftime("%Y-%m-%d %H:%M UTC"))
print("X-Request-Id:", r.headers.get("X-Request-Id"))

os.environ["GENESIS_API_KEY"] stops the script if the variable is not set, which beats sending a request without a key and getting a 401. r.headers is case-insensitive, so X-Request-Id is found even when the server sends x-request-id.

period_resets_at is unix time: the number of seconds since January 1, 1970, 00:00 UTC. datetime.fromtimestamp(ts, timezone.utc) turns it into a date: 1796463000 is December 5, 2026, 09:30 UTC.

Second request: BTC funding rates

Funding is a periodic payment between longs and shorts on a perpetual futures contract, and exchanges settle it every 8, 4 or 1 hour. /funding/rates returns rates across all exchanges, and the coin parameter narrows them to one coin. The response to GET /funding/rates?coin=BTC, an illustrative example with two exchanges from the list:

{
  "success": true,
  "data": [
    {
      "coin": "BTC",
      "exchanges": [
        {
          "exchange": "Bitget",
          "funding_pct": 0.01,
          "funding_8h_pct": 0.01,
          "next_payout": "00:00",
          "interval": "8h",
          "price": 96021.5,
          "trade_url": "https://www.bitget.com/futures/usdt/BTCUSDT"
        },
        {
          "exchange": "Hyper",
          "funding_pct": 0.0013,
          "funding_8h_pct": 0.0104,
          "next_payout": null,
          "interval": "1h",
          "price": 96030.0,
          "trade_url": "https://app.hyperliquid.xyz/trade/BTC"
        },
        …
      ]
    }
  ],
  "meta": {
    "count": 1,
    "updated_at": 1794675861,
    "freshness_sec": 60,
    "plan": "trial"
  }
}

How to read this response:

All fields are in the Funding rates docs section. The next block continues the script: BASE, key and the imports are already there.

r = requests.get(
    BASE + "/funding/rates",
    headers={"X-API-Key": key},
    params={"coin": "BTC"},  # requests builds ?coin=BTC
    timeout=10,
)
r.raise_for_status()  # raises on 4xx and 5xx
body = r.json()
if not body["data"]:
    raise SystemExit("coin not in the data: check the ticker")

ts = body["meta"]["updated_at"]
snap = datetime.fromtimestamp(ts, timezone.utc)
print("snapshot from", snap.strftime("%Y-%m-%d %H:%M:%S UTC"))

rows = body["data"][0]["exchanges"]
rows.sort(key=lambda e: e["funding_8h_pct"], reverse=True)
for e in rows:
    print(f'{e["exchange"]:<8} {e["funding_pct"]:>7}% '
          f'per {e["interval"] or "?"}, '
          f'{e["funding_8h_pct"]:>7}% per 8h')

For the example response, the script prints:

snapshot from 2026-11-14 17:04:21 UTC
Hyper     0.0013% per 1h,  0.0104% per 8h
Bitget      0.01% per 8h,    0.01% per 8h

Hyper ranks above Bitget even though its per-interval rate is 0.01 / 0.0013 ≈ 7.7 times lower. Without normalizing to 8 hours, this comparison goes wrong.

Common beginner mistakes

MistakeWhat the server returnsHow to fix it
Key in the URL: ?api_key=…401 and "Missing X-API-Key header."Send the key only in the X-API-Key header
Empty key variable401 with the same text: curl drops an empty headerCheck the length: echo ${#GENESIS_API_KEY}
Typo in the path: /v1/funding/rate or no /v1404Check the path against the docs
Typo in a parameter name: coins=BTC200 and every coin: an unknown parameter is ignoredCheck meta.count: with coin=BTC it is 1
Decimal comma: min_spread=0,5200 with no filter appliedUse a dot: 0.5
Pair instead of ticker: coin=BTCUSDT200, empty data, meta.count of 0Use the coin ticker: BTC

A parameter typo is the sneakiest of these: there is no error, yet the script gets the full dataset instead of one coin and spends a call on it. After adding a new filter, compare meta.count with what you expect.

Try it yourself

  1. Send a request without a key

    curl -i "https://api.genesisarbitrage.com/v1/account/usage" returns 401 with invalid_key and "Missing X-API-Key header." in the body. Find x-request-id among the headers.

  2. Repeat it with the key

    Set the variable with read -s and send the request from the /account/usage section. You get a 200 and your plan in data.plan.

  3. Check the reset date

    Run the Python script and compare the quota reset date with the "resets …" line in the "Genesis API" block of your profile. Getting a key step by step is covered in the Genesis API quick start.

  4. Find the highest rate

    Add the second block to the script and find the exchange with the highest funding_8h_pct. Normalize its funding_pct to 8 hours by hand: rate × 8 / interval in hours.

  5. Break the request on purpose

    Change coin to coins and compare meta.count, then drop the s from /funding/rates and look at the status code.

Which endpoints serve decisions on spreads, order books and funding is the subject of lesson 3.

Questions and answers

Can I call the API from a browser?

Only addresses that need no key: https://api.genesisarbitrage.com/health opens in a browser and shows {"ok":true}. The address bar cannot add an X-API-Key header, so keyed requests go through curl, a script or the "Try it" form in the docs. Never embed the key in website or extension code: anyone who opens the page source will see it.

How is the -i flag different from -v in curl?

-i prints the status line and response headers before the body. -v also shows the request itself: lines with > are what went to the server, and lines with < are what came back.

How do I convert unix time to a date without Python?

On macOS, run date -u -r 1796463000; on Linux, date -u -d @1796463000. For this number, both show December 5, 2026, 09:30 UTC.