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-Keyheader. - The status code tells you the next step:
200means read the data,304means nothing changed,401and403mean check the key and plan,429and503mean waitRetry-Afterseconds. - A Genesis API response is an envelope of
success,dataandmeta. Percentages arrive as plain numbers (0.01means 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
| Part | In the example | What it means |
|---|---|---|
| Method | GET | Read data; every Genesis API endpoint is GET |
| Base URL | https://api.genesisarbitrage.com/v1 | Server and API version |
| Path | /funding/rates | The funding rates endpoint |
| Parameters | ?coin=BTC | Filter: BTC only |
| Header | X-API-Key | The 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:
| Code | What it means | What to do |
|---|---|---|
200 | Request served, data in the body | Read data and meta |
304 | Data unchanged since your last response | Reuse the previous data |
401 | Key missing, invalid, revoked or subscription expired | Check the header and the subscription |
403 | Endpoint not in your plan (plan_restricted) | Change the plan or drop the request |
429 | Request, download or quota limit exceeded | Wait Retry-After seconds |
503 | Data 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:
- the envelope:
successistrue, the data sits indata, and service fields sit inmeta;meta.countis the number of items indata, which is one coin forcoin=BTC, with anexchangesarray inside it; - percentages arrive as plain numbers:
"funding_pct": 0.01means 0.01% per interval, not 1%; on a $10,000 position, one payment at this rate is 10,000 × 0.01 / 100 = $1; funding_8h_pctnormalizes the rate to 8 hours so that exchanges with different intervals compare directly: Hyper settles every hour, and 0.0013 × 8 = 0.0104% per 8 hours;next_payoutis the next payment time in UTC as an "HH:MM" string, andnullmeans no data, not zero;meta.updated_atis the unix time the snapshot was built: 1794675861 is November 14, 2026, 17:04:21 UTC; on Trial the snapshot refreshes every 60 seconds.
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
| Mistake | What the server returns | How 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 variable | 401 with the same text: curl drops an empty header | Check the length: echo ${#GENESIS_API_KEY} |
Typo in the path: /v1/funding/rate or no /v1 | 404 | Check the path against the docs |
Typo in a parameter name: coins=BTC | 200 and every coin: an unknown parameter is ignored | Check meta.count: with coin=BTC it is 1 |
Decimal comma: min_spread=0,5 | 200 with no filter applied | Use a dot: 0.5 |
Pair instead of ticker: coin=BTCUSDT | 200, empty data, meta.count of 0 | Use 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
Send a request without a key
curl -i "https://api.genesisarbitrage.com/v1/account/usage"returns401withinvalid_keyand "Missing X-API-Key header." in the body. Findx-request-idamong the headers.Repeat it with the key
Set the variable with
read -sand send the request from the/account/usagesection. You get a200and your plan indata.plan.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.
Find the highest rate
Add the second block to the script and find the exchange with the highest
funding_8h_pct. Normalize itsfunding_pctto 8 hours by hand: rate × 8 / interval in hours.Break the request on purpose
Change
cointocoinsand comparemeta.count, then drop thesfrom/funding/ratesand 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.