Genesis API limits: call quota, requests per second, data freshness and 429 errors
In short
- Your plan sets the call quota per 30 days (from 500K on Trial to 10M on Max), the requests-per-second limit (from 1 to 15) and data freshness (from 60 to 5 seconds).
- Only a
200response uses the quota.304responses and errors are free but still take a slot in the requests-per-second limit; over a limit the server returns429and charges nothing. - Polling faster than
meta.freshness_secbrings no new data: your plan gets a fresh snapshot once per that interval, andIf-None-Matchturns extra polls into free304responses.
Genesis API limits are four caps per key: the call quota for a 30-day period, the rate limit in requests per second, data freshness and download volume. Your plan sets the first three; download volume is the same for everyone: 60 MB of compressed data per 10 seconds. Over any limit the server returns a 429 error and charges nothing.
Limits by plan
| Plan | Calls per 30 days | Requests per second | Freshness |
|---|---|---|---|
| Trial, $20/month | 500,000 | 1 | 60 s |
| Start, $50/month | 2,000,000 | 2 | 30 s |
| Pro, $100/month | 5,000,000 | 5 | 10 s |
| Max, $200/month | 10,000,000 | 15 | 5 s |
Data freshness is the interval at which your plan gets a new snapshot: every 60 seconds on Trial, every 5 on Max. Responses carry it in the meta.freshness_sec field. Paying for 3 months saves 10%, for 6 months 20%. The plan comparison is on the Genesis API Pricing page, and the rules are in the Plans & limits section of the documentation.
What uses the quota
A call is a 200 response. 304 responses (data not modified) and 4xx and 5xx errors do not use the quota, but they count toward the requests-per-second limit. A request to /account/usage does not use a call.
The quota covers a 30-day period, not a calendar month. The reset time is in the X-Quota-Reset header, the period_resets_at field and the "resets …" line in your profile. Once the quota runs out, the server answers 429 rate_limited, and Retry-After holds the number of seconds until the reset, which can be days.
Rate-limit headers
A response from a data endpoint carries the state of your limits (illustrative values):
| Header | Example | What it shows |
|---|---|---|
X-RateLimit-Limit | 5 | Requests-per-second limit of your plan |
X-RateLimit-Remaining | 4 | Requests left in the current window |
X-RateLimit-Reset | 1785200001 | Unix time the window resets |
X-Quota-Limit | 5000000 | Call quota for the 30-day period |
X-Quota-Remaining | 4815799 | Calls left in the period |
X-Quota-Reset | 1786492800 | Unix time the quota resets |
Retry-After | 1 | Seconds to wait before retrying, on 429 and 503 |
The requests-per-second window is one second, so in a normal response X-RateLimit-Reset points to the start of the next second. The quota left in the example: 5,000,000 − 184,201 = 4,815,799 calls, the same numbers /account/usage returns.
The /account/usage endpoint
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": { … }
}
| Field | Type | Meaning |
|---|---|---|
plan | string | Plan: trial, start, pro or max |
calls_used | int | Calls used in the current period |
calls_limit | int | Call quota per period |
rps_limit | int | Requests-per-second limit |
freshness_sec | int | Data delay, seconds |
period_resets_at | int | Unix time the quota resets |
The endpoint is available on every plan and described in the Usage section. Call it when a bot starts, to check the plan and the remaining quota before polling begins.
429 errors: rate_limited and download_limited
| Response | When it comes | What to do |
|---|---|---|
429 rate_limited | More requests per second than your plan allows | Wait for Retry-After and space requests out |
429 rate_limited | The period's quota is used up | Wait for the reset or change plans |
429 rate_limited | A full funding analytics download sooner than allowed | Take a slice with coin or send If-None-Match |
429 download_limited | Over 60 MB of compressed data in 10 seconds | Wait for Retry-After, narrow the request with filters |
The 429 Too Many Requests status code is defined in RFC 6585, where Retry-After is optional. Genesis API sends it with every 429, always in seconds.
Responses under 64 KB do not count toward download volume, and polling every data set at your plan's freshness fits within the limit with room to spare. Full funding analytics downloads without coin have their own limit: /funding/analytics/summary and /funding/analytics/recent once per 60 seconds, /funding/analytics/daily once per 300 seconds per key. Requests with coin and 304 responses are not limited; details are in the Funding analytics section.
Plan access and 403 plan_restricted
| Plan | What is open |
|---|---|
| Trial | CEX arbitrage (Spot – Spot, Spot – Futures, Futures – Futures), funding rates and funding spread, Fair – Last, CEX Pumps – Dumps, open interest, AI signals, coin search, /account/usage |
| Start | Everything in Trial, plus stocks /arbitrage/stocks, on-chain sections /onchain/{section}, prediction arbitrage in the exact and dutch modes, platform status |
| Pro and Max | Every endpoint: DEX – Spot, DEX – Futures, Crosschain, DEX Dumps, order books, funding analytics, prediction market analytics, smart money, trades, traders, the llm and sport modes, DEX swaps, OnChain analytics and coin |
An endpoint outside your plan returns 403, and so does a mode=sport request to /predictions/arbitrage on Start:
{
"success": false,
"error": {
"code": "plan_restricted",
"message": "This endpoint is not included in your plan."
}
}
A 403 does not use the quota. Retrying it is pointless: only a higher plan opens access.
How to size a plan for your load
Illustrative example: a bot polls three endpoints, /arbitrage/spot-spot, /funding/spread and /market/open-interest, every 10 seconds around the clock.
- Requests per second: 3 / 10 = 0.3 on average. If all three go out at once, they land in the same second, and Trial and Start return
429for the extra ones. - Calls per day: 86,400 / 10 = 8,640 polls, 8,640 × 3 = 25,920 calls.
- Calls per 30 days: 25,920 × 30 = 777,600. That is more than the Trial quota of 500,000; on Start it is 777,600 / 2,000,000 = 38.88% of the quota.
- Freshness: on Start the snapshot updates every 30 seconds, which is 86,400 / 30 = 2,880 times a day. New data comes from 2,880 × 3 × 30 = 259,200 calls, and the other 777,600 − 259,200 = 518,400 return the same thing.
The same bot polling at each plan's freshness:
| Freshness and polling | Calls per 30 days | Plan | Share of quota |
|---|---|---|---|
| Every 60 s | 129,600 | Trial | 26% |
| Every 30 s | 259,200 | Start | 13% |
| Every 10 s | 777,600 | Pro | 16% |
| Every 5 s | 1,555,200 | Max | 16% |
Polling every 10 seconds makes sense from Pro up: 777,600 / 5,000,000 = 15.552% of the quota, and the limit of 5 requests per second covers sending all three at once. If the bot can live with 30-second-old data, Start with polling every 30 seconds costs 259,200 / 2,000,000 = 12.96% of the quota.
Polling without wasted calls: ETag and Retry-After
Your plan gets a new snapshot every meta.freshness_sec seconds, and polling faster returns the same snapshot with the same meta.updated_at. Without the If-None-Match header such a response is a 200 and a used call. With it the server answers 304 with no body: the quota is untouched, but a slot in the per-second limit is taken.
An ETag does not come with every response. Full data sets return it, that is, requests without filters, such as /funding/spread in the example below. A filtered response (coin, min_spread and others) has no ETag, and every poll costs a call: filters save traffic, ETag saves quota. Retries and compression are covered in how to poll an API efficiently and in the guide to responses and errors.
import os
import time
import requests
URL = "https://api.genesisarbitrage.com/v1/funding/spread"
KEY = os.environ["GENESIS_API_KEY"]
etag, pause = None, 30
while True:
headers = {"X-API-Key": KEY}
if etag:
headers["If-None-Match"] = etag
r = requests.get(URL, headers=headers, timeout=15)
if r.status_code in (429, 500, 503):
wait = int(r.headers.get("Retry-After", "5"))
if wait > 600: # the quota is used up, stop here
raise SystemExit(f"Quota used up, resets in {wait} s")
time.sleep(wait)
continue
r.raise_for_status() # a retry will not fix 401 or 403
left = r.headers.get("X-Quota-Remaining") # may be absent
if left is not None and int(left) < 10_000:
print("Quota running low:", left)
if r.status_code == 200: # on 304 the data is unchanged
etag = r.headers.get("ETag")
body = r.json()
pause = body["meta"].get("freshness_sec", pause)
print(body["meta"]["count"], "coins in the response")
time.sleep(pause)
Changing and renewing a plan
- A new plan takes effect right after payment: new limits and freshness, the quota starts from zero, and the rest of the previous plan is forfeited. The site warns you before you pay.
- Renewing the same plan adds days to the term and does not reset the quota: the current 30-day period carries on.
- Your key stays the same when you change or renew a plan, so your programs need no update.
- The period discount applies to the monthly price: Pro for 6 months is $100 × 0.8 × 6 = $480 instead of $600, for 3 months $100 × 0.9 × 3 = $270.
How to get and store the key is covered in the guide to the Genesis API key.
Questions and answers
What happens if the quota runs out early?
The server returns 429 rate_limited with Retry-After until the quota resets, and nothing is charged. Wait for the new period or pay for a higher plan: it takes effect at once, with a fresh quota.
Do 304 responses and errors count against limits?
Not against the quota: only 200 uses it. They do count toward the requests-per-second limit: 304 responses and errors take slots in the per-second window.
How do I check the remaining quota without using a call?
Read X-Quota-Remaining in a data response or call /account/usage: that request does not use a call. The "Calls used" line in your profile shows the usage too.
Can I get around the limit with several keys?
No. Each account gets one key, the limits are counted per key, and changing your IP address does not change them. Opening several accounts to get around limits breaks the rules; if you need more, move to a higher plan.