Genesis Arbitrage

Genesis Arbitrage · · 10 min de lectura

Límites de Genesis API: cuota de llamadas, peticiones por segundo, frescura de datos y errores 429

En resumen

  • Tu plan fija la cuota de llamadas por 30 días (de 500.000 en Trial a 10 millones en Max), el límite de peticiones por segundo (de 1 a 15) y la frescura de los datos (de 60 a 5 segundos).
  • Solo una respuesta 200 consume cuota. Las respuestas 304 y los errores no cuestan nada, pero ocupan un hueco en el límite de peticiones por segundo; al superar un límite el servidor devuelve 429 y no cobra nada.
  • Consultar más rápido que meta.freshness_sec no aporta datos nuevos: tu plan recibe una instantánea nueva una vez por ese intervalo, y If-None-Match convierte las consultas sobrantes en respuestas 304 gratuitas.

Los límites de Genesis API son cuatro topes por clave: la cuota de llamadas para un periodo de 30 días, el rate limit en peticiones por segundo, la frescura de los datos y el volumen de descarga. Tu plan fija los tres primeros; el volumen de descarga es igual para todos: 60 MB de datos comprimidos cada 10 segundos. Al superar cualquier límite, el servidor devuelve un error 429 y no cobra nada.

Límites por plan

PlanLlamadas por 30 díasPeticiones por segundoFrescura
Trial, $20/mes500.000160 s
Start, $50/mes2.000.000230 s
Pro, $100/mes5.000.000510 s
Max, $200/mes10.000.000155 s

La frescura de los datos es el intervalo con el que tu plan recibe una instantánea nueva: cada 60 segundos en Trial, cada 5 en Max. Las respuestas la incluyen en el campo meta.freshness_sec. Pagar 3 meses ahorra un 10 %, y 6 meses, un 20 %. La comparativa de planes está en la página de precios de Genesis API, y las reglas, en la sección Planes y límites de la documentación.

Qué consume la cuota

Una llamada es una respuesta 200. Las respuestas 304 (datos sin cambios) y los errores 4xx y 5xx no consumen cuota, pero cuentan para el límite de peticiones por segundo. Una petición a /account/usage no consume ninguna llamada.

La cuota cubre un periodo de 30 días, no un mes natural. La hora del reinicio aparece en la cabecera X-Quota-Reset, en el campo period_resets_at y en la línea «resets …» de tu perfil. Cuando la cuota se agota, el servidor responde 429 rate_limited, y Retry-After indica los segundos que faltan hasta el reinicio, que pueden ser días.

Cabeceras de rate limit

La respuesta de un endpoint de datos incluye el estado de tus límites (valores ilustrativos):

CabeceraEjemploQué muestra
X-RateLimit-Limit5Límite de peticiones por segundo de tu plan
X-RateLimit-Remaining4Peticiones restantes en la ventana actual
X-RateLimit-Reset1785200001Hora Unix en que se reinicia la ventana
X-Quota-Limit5000000Cuota de llamadas del periodo de 30 días
X-Quota-Remaining4815799Llamadas restantes en el periodo
X-Quota-Reset1786492800Hora Unix en que se reinicia la cuota
Retry-After1Segundos de espera antes de reintentar, en 429 y 503

La ventana de peticiones por segundo dura un segundo, así que en una respuesta normal X-RateLimit-Reset apunta al inicio del segundo siguiente. La cuota restante del ejemplo: 5.000.000 − 184.201 = 4.815.799 llamadas, las mismas cifras que devuelve /account/usage.

El endpoint /account/usage

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": { … }
}
CampoTipoSignificado
planstringPlan: trial, start, pro o max
calls_usedintLlamadas usadas en el periodo actual
calls_limitintCuota de llamadas por periodo
rps_limitintLímite de peticiones por segundo
freshness_secintRetraso de los datos, en segundos
period_resets_atintHora Unix en que se reinicia la cuota

El endpoint está disponible en todos los planes y se describe en la sección Uso. Llámalo al iniciar un bot, para comprobar el plan y la cuota restante antes de empezar a consultar.

Errores 429: rate_limited y download_limited

RespuestaCuándo apareceQué hacer
429 rate_limitedMás peticiones por segundo de las que permite tu planEsperar el tiempo de Retry-After y espaciar las peticiones
429 rate_limitedLa cuota del periodo está agotadaEsperar al reinicio o cambiar de plan
429 rate_limitedDescarga completa de analítica de funding antes de lo permitidoPedir una porción con coin o enviar If-None-Match
429 download_limitedMás de 60 MB de datos comprimidos en 10 segundosEsperar el tiempo de Retry-After y acotar la petición con filtros

El código de estado 429 Too Many Requests está definido en la RFC 6585, donde Retry-After es opcional. Genesis API lo envía con cada 429, siempre en segundos.

Las respuestas de menos de 64 KB no cuentan para el volumen de descarga, y consultar todos los conjuntos de datos con la frescura de tu plan cabe en el límite con holgura. Las descargas completas de analítica de funding sin coin tienen su propio límite: /funding/analytics/summary y /funding/analytics/recent una vez cada 60 segundos, /funding/analytics/daily una vez cada 300 segundos por clave. Las peticiones con coin y las respuestas 304 no tienen límite; los detalles están en la sección Analítica de funding.

Acceso por plan y 403 plan_restricted

PlanQué incluye
TrialArbitraje CEX (Spot – Spot, Spot – Futuros, Futuros – Futuros), tasas de financiación (funding) y spread de funding, Fair – Last, CEX Pumps – Dumps, open interest, señales de IA, búsqueda de monedas, /account/usage
StartTodo lo de Trial, más acciones /arbitrage/stocks, secciones on-chain /onchain/{section}, arbitraje de mercados de predicción en los modos exact y dutch, estado de las plataformas
Pro y MaxTodos los endpoints: DEX – Spot, DEX – Futuros, Crosschain, DEX Dumps, libros de órdenes, analítica de funding, analítica de mercados de predicción, smart money, operaciones, traders, los modos llm y sport, swaps DEX, analítica OnChain y moneda

Un endpoint fuera de tu plan devuelve 403, y lo mismo ocurre con una petición mode=sport a /predictions/arbitrage en Start:

{
  "success": false,
  "error": {
    "code": "plan_restricted",
    "message": "This endpoint is not included in your plan."
  }
}

Un 403 no consume cuota. Reintentarlo no sirve de nada: solo un plan superior abre el acceso.

Cómo dimensionar el plan según tu carga

Ejemplo ilustrativo: un bot consulta tres endpoints, /arbitrage/spot-spot, /funding/spread y /market/open-interest, cada 10 segundos las 24 horas.

El mismo bot consultando con la frescura de cada plan:

Frescura y consultaLlamadas por 30 díasPlanParte de la cuota
Cada 60 s129.600Trial26 %
Cada 30 s259.200Start13 %
Cada 10 s777.600Pro16 %
Cada 5 s1.555.200Max16 %

Consultar cada 10 segundos tiene sentido desde Pro: 777.600 / 5.000.000 = 15,552 % de la cuota, y el límite de 5 peticiones por segundo permite enviar las tres a la vez. Si el bot admite datos con 30 segundos de antigüedad, Start con consulta cada 30 segundos cuesta 259.200 / 2.000.000 = 12,96 % de la cuota.

Consultar sin llamadas desperdiciadas: ETag y Retry-After

Tu plan recibe una instantánea nueva cada meta.freshness_sec segundos, y consultar más rápido devuelve la misma instantánea con el mismo meta.updated_at. Sin la cabecera If-None-Match, esa respuesta es un 200 y una llamada gastada. Con ella, el servidor responde 304 sin cuerpo: la cuota queda intacta, pero se ocupa un hueco del límite por segundo.

Un ETag no viene en todas las respuestas. Lo devuelven los conjuntos de datos completos, es decir, las peticiones sin filtros, como /funding/spread en el ejemplo siguiente. Una respuesta filtrada (coin, min_spread y otros) no lleva ETag, y cada consulta cuesta una llamada: los filtros ahorran tráfico, el ETag ahorra cuota. Los reintentos y la compresión se explican en cómo consultar una API de forma eficiente y en la guía de respuestas y errores.

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:  # la cuota está agotada, paramos aquí
            raise SystemExit(f"Cuota agotada, se reinicia en {wait} s")
        time.sleep(wait)
        continue
    r.raise_for_status()  # un reintento no arregla 401 ni 403
    left = r.headers.get("X-Quota-Remaining")  # puede faltar
    if left is not None and int(left) < 10_000:
        print("Queda poca cuota:", left)
    if r.status_code == 200:  # con 304 los datos no han cambiado
        etag = r.headers.get("ETag")
        body = r.json()
        pause = body["meta"].get("freshness_sec", pause)
        print(body["meta"]["count"], "monedas en la respuesta")
    time.sleep(pause)

Cambiar y renovar el plan

Cómo obtener y guardar la clave se explica en la guía de la clave de Genesis API.

Preguntas y respuestas

¿Qué pasa si la cuota se agota antes de tiempo?

El servidor devuelve 429 rate_limited con Retry-After hasta que la cuota se reinicia, y no se cobra nada. Espera al nuevo periodo o paga un plan superior: se activa al instante, con cuota nueva.

¿Las respuestas 304 y los errores cuentan para los límites?

No para la cuota: solo 200 la consume. Sí cuentan para el límite de peticiones por segundo: las respuestas 304 y los errores ocupan huecos en la ventana por segundo.

¿Cómo compruebo la cuota restante sin gastar una llamada?

Lee X-Quota-Remaining en una respuesta de datos o llama a /account/usage: esa petición no consume llamada. La línea de llamadas usadas de tu perfil también muestra el consumo.

¿Puedo esquivar el límite con varias claves?

No. Cada cuenta recibe una clave, los límites se cuentan por clave y cambiar de dirección IP no los modifica. Abrir varias cuentas para esquivar límites incumple las reglas; si necesitas más, pasa a un plan superior.