Genesis Arbitrage

Genesis Arbitrage · · 9 min read

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 200 response uses the quota. 304 responses and errors are free but still take a slot in the requests-per-second limit; over a limit the server returns 429 and charges nothing.
  • Polling faster than meta.freshness_sec brings no new data: your plan gets a fresh snapshot once per that interval, and If-None-Match turns extra polls into free 304 responses.

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

PlanCalls per 30 daysRequests per secondFreshness
Trial, $20/month500,000160 s
Start, $50/month2,000,000230 s
Pro, $100/month5,000,000510 s
Max, $200/month10,000,000155 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):

HeaderExampleWhat it shows
X-RateLimit-Limit5Requests-per-second limit of your plan
X-RateLimit-Remaining4Requests left in the current window
X-RateLimit-Reset1785200001Unix time the window resets
X-Quota-Limit5000000Call quota for the 30-day period
X-Quota-Remaining4815799Calls left in the period
X-Quota-Reset1786492800Unix time the quota resets
Retry-After1Seconds 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": { … }
}
FieldTypeMeaning
planstringPlan: trial, start, pro or max
calls_usedintCalls used in the current period
calls_limitintCall quota per period
rps_limitintRequests-per-second limit
freshness_secintData delay, seconds
period_resets_atintUnix 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

ResponseWhen it comesWhat to do
429 rate_limitedMore requests per second than your plan allowsWait for Retry-After and space requests out
429 rate_limitedThe period's quota is used upWait for the reset or change plans
429 rate_limitedA full funding analytics download sooner than allowedTake a slice with coin or send If-None-Match
429 download_limitedOver 60 MB of compressed data in 10 secondsWait 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

PlanWhat is open
TrialCEX 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
StartEverything in Trial, plus stocks /arbitrage/stocks, on-chain sections /onchain/{section}, prediction arbitrage in the exact and dutch modes, platform status
Pro and MaxEvery 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.

The same bot polling at each plan's freshness:

Freshness and pollingCalls per 30 daysPlanShare of quota
Every 60 s129,600Trial26%
Every 30 s259,200Start13%
Every 10 s777,600Pro16%
Every 5 s1,555,200Max16%

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

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.