Genesis Arbitrage

Genesis Arbitrage · · 12 min de lectura

Tu primera petición a la API: HTTP, encabezados y JSON

En resumen

  • Una petición HTTP a una API consta de un método, una dirección formada por la URL base, la ruta y los parámetros, y encabezados. La clave de Genesis API va solo en el encabezado X-API-Key.
  • El código de estado indica el siguiente paso: 200 significa leer los datos, 304 que nada ha cambiado, 401 y 403 que hay que revisar la clave y el plan, 429 y 503 que hay que esperar Retry-After segundos.
  • La respuesta de Genesis API es un envoltorio con success, data y meta. Los porcentajes llegan como números simples (0.01 significa 0,01 %) y la hora llega en segundos unix.
  • Los errores habituales de un principiante son la clave en la URL, una variable de entorno vacía y una errata en la ruta o en el nombre de un parámetro. Una errata en un parámetro no lanza ningún error: recibes el conjunto completo de datos en lugar del filtrado.

Para llamar a una API, tu programa envía una petición HTTP formada por un método, una dirección y encabezados, y el servidor devuelve un código de estado, sus propios encabezados y un cuerpo, que en Genesis API es JSON. Puedes enviar la petición desde una terminal con curl o desde código en cualquier lenguaje que tenga un cliente HTTP. La primera petición de abajo comprueba la clave con /account/usage, y la segunda obtiene las tasas de financiación (funding) de BTC desde /funding/rates. Qué es una API y qué se puede automatizar con ella se explica en la lección 1.

Anatomía de una petición

Esta es la petición de tasas de financiación (funding) de BTC que curl envía al servidor, tal como la muestra la opción -v en las líneas que empiezan por > (la clave se sustituye por un marcador):

> 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
ParteEn el ejemploQué significa
MétodoGETLeer datos; todos los endpoints de Genesis API son GET
URL basehttps://api.genesisarbitrage.com/v1Servidor y versión de la API
Ruta/funding/ratesEl endpoint de tasas de financiación (funding)
Parámetros?coin=BTCFiltro: solo BTC
EncabezadoX-API-KeyLa clave con la que el servidor identifica tu cuenta y tu plan

Los parámetros van después de ? como pares nombre=valor unidos por &: ?coin=BTC&exchange=Binance,OKX. Los filtros de Genesis API son opcionales, así que sin coin el mismo endpoint devuelve todas las monedas. Los decimales llevan punto, nunca coma: min_spread=0.5.

Los encabezados son líneas nombre: valor que viajan junto con la dirección. Los nombres de los encabezados no distinguen mayúsculas de minúsculas (RFC 9110, sección 5.1): X-API-Key y x-api-key son el mismo encabezado, y un x-request-id en minúsculas en la salida de curl es el mismo X-Request-Id. Genesis API acepta la clave solo en X-API-Key.

Códigos de estado

La primera línea de la respuesta lleva el código de estado, y tu programa decide qué hacer a continuación según ese código:

CódigoQué significaQué hacer
200Petición atendida, datos en el cuerpoLeer data y meta
304Datos sin cambios desde tu última respuestaReutilizar los datos anteriores
401Clave ausente, no válida, revocada o suscripción vencidaRevisar el encabezado y la suscripción
403Endpoint fuera de tu plan (plan_restricted)Cambiar de plan o descartar la petición
429Límite de peticiones, descargas o cuota superadoEsperar Retry-After segundos
503Datos en reconstrucción (snapshot_not_ready)Reintentar tras Retry-After segundos

Solo un 200 consume tu cuota: un 304 y los errores son gratuitos, pero cuentan para el límite de peticiones por segundo. Un 304 solo se devuelve a una petición con el encabezado If-None-Match; ese encabezado y los códigos 400, 404, 410 y 500 se explican en Respuestas y errores de Genesis API. Por qué un reintento tras un 429 necesita una pausa se explica en la entrada del glosario HTTP 429 Too Many Requests.

Primera petición: /account/usage

/account/usage muestra el estado de tu clave: plan, cuota usada y límites. Está disponible en todos los planes y no consume ninguna llamada, así que tu primera petición va allí. Primero guarda la clave en una variable de entorno y luego envía la petición:

# pega la clave y pulsa Enter: no se mostrará en pantalla
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"

La opción -i imprime la línea de estado y los encabezados antes del cuerpo. El cuerpo de la respuesta, un ejemplo ilustrativo para el plan Trial:

{
  "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 es tu plan, y calls_used sobre calls_limit es el uso de la cuota del período de 30 días. El ejemplo muestra 0 porque aún no se ha hecho ninguna otra petición, y /account/usage en sí no consume una llamada. rps_limit son las peticiones por segundo, freshness_sec es cada cuánto se actualizan los datos de tu plan y period_resets_at es el momento en que se reinicia la cuota. Los campos se describen en la sección Uso de la documentación.

Entre los encabezados, busca X-Request-Id, el identificador de la petición que envías al soporte en lugar de tu clave, y X-RateLimit-Remaining, el número de peticiones que quedan en la ventana actual del límite.

La misma petición en Python

Un script para Python 3.10+ con la biblioteca requests lee la clave de la misma variable de entorno:

import os
from datetime import datetime, timezone

import requests

BASE = "https://api.genesisarbitrage.com/v1"
key = os.environ["GENESIS_API_KEY"]  # KeyError si no está definida

r = requests.get(
    BASE + "/account/usage",
    headers={"X-API-Key": key},
    timeout=10,  # sin timeout, requests puede esperar para siempre
)
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("llamadas:", usage["calls_used"], "de", usage["calls_limit"])
print("la cuota se reinicia:", resets.strftime("%Y-%m-%d %H:%M UTC"))
print("X-Request-Id:", r.headers.get("X-Request-Id"))

os.environ["GENESIS_API_KEY"] detiene el script si la variable no está definida, lo cual es mejor que enviar una petición sin clave y recibir un 401. r.headers no distingue mayúsculas de minúsculas, así que X-Request-Id se encuentra incluso cuando el servidor envía x-request-id.

period_resets_at es tiempo unix: el número de segundos transcurridos desde el 1 de enero de 1970, 00:00 UTC. datetime.fromtimestamp(ts, timezone.utc) lo convierte en una fecha: 1796463000 es el 5 de diciembre de 2026, 09:30 UTC.

Segunda petición: tasas de financiación (funding) de BTC

El funding es un pago periódico entre largos y cortos en un contrato de futuros perpetuos, y las exchanges lo liquidan cada 8, 4 o 1 hora. /funding/rates devuelve las tasas de todas las exchanges, y el parámetro coin las limita a una moneda. La respuesta a GET /funding/rates?coin=BTC, un ejemplo ilustrativo con dos exchanges de la lista:

{
  "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"
  }
}

Cómo leer esta respuesta:

Todos los campos están en la sección Tasas de funding de la documentación. El siguiente bloque continúa el script: BASE, key y las importaciones ya están definidos.

r = requests.get(
    BASE + "/funding/rates",
    headers={"X-API-Key": key},
    params={"coin": "BTC"},  # requests construye ?coin=BTC
    timeout=10,
)
r.raise_for_status()  # lanza excepción en 4xx y 5xx
body = r.json()
if not body["data"]:
    raise SystemExit("la moneda no está en los datos: revisa el ticker")

ts = body["meta"]["updated_at"]
snap = datetime.fromtimestamp(ts, timezone.utc)
print("instantánea de", 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'por {e["interval"] or "?"}, '
          f'{e["funding_8h_pct"]:>7}% por 8h')

Para la respuesta de ejemplo, el script imprime:

instantánea de 2026-11-14 17:04:21 UTC
Hyper     0.0013% por 1h,  0.0104% por 8h
Bitget      0.01% por 8h,    0.01% por 8h

Hyper queda por encima de Bitget aunque su tasa por intervalo sea 0,01 / 0,0013 ≈ 7,7 veces menor. Sin normalizar a 8 horas, esta comparación sale mal.

Errores habituales de un principiante

ErrorQué devuelve el servidorCómo corregirlo
Clave en la URL: ?api_key=…401 y "Missing X-API-Key header."Envía la clave solo en el encabezado X-API-Key
Variable de clave vacía401 con el mismo texto: curl descarta un encabezado vacíoComprueba la longitud: echo ${#GENESIS_API_KEY}
Errata en la ruta: /v1/funding/rate o sin /v1404Comprueba la ruta con la documentación
Errata en el nombre de un parámetro: coins=BTC200 y todas las monedas: un parámetro desconocido se ignoraRevisa meta.count: con coin=BTC es 1
Coma decimal: min_spread=0,5200 sin filtro aplicadoUsa punto: 0.5
Par en lugar de ticker: coin=BTCUSDT200, data vacío, meta.count de 0Usa el ticker de la moneda: BTC

La errata en un parámetro es la más traicionera: no hay error, pero el script recibe el conjunto completo de datos en lugar de una moneda y gasta una llamada en ello. Después de añadir un filtro nuevo, compara meta.count con lo que esperas.

Pruébalo tú mismo

  1. Envía una petición sin clave

    curl -i "https://api.genesisarbitrage.com/v1/account/usage" devuelve 401 con invalid_key y "Missing X-API-Key header." en el cuerpo. Busca x-request-id entre los encabezados.

  2. Repítela con la clave

    Define la variable con read -s y envía la petición de la sección /account/usage. Obtienes un 200 y tu plan en data.plan.

  3. Comprueba la fecha de reinicio

    Ejecuta el script de Python y compara la fecha de reinicio de la cuota con la línea "se reinicia …" del bloque "Genesis API" de tu perfil. Cómo obtener una clave paso a paso se explica en el inicio rápido de Genesis API.

  4. Encuentra la tasa más alta

    Añade el segundo bloque al script y encuentra la exchange con el funding_8h_pct más alto. Normaliza a mano su funding_pct a 8 horas: tasa × 8 / intervalo en horas.

  5. Rompe la petición a propósito

    Cambia coin por coins y compara meta.count; luego quita la s de /funding/rates y mira el código de estado.

Qué endpoints sirven para decidir sobre spreads, libros de órdenes y funding es el tema de la lección 3.

Preguntas y respuestas

¿Puedo llamar a la API desde un navegador?

Solo a direcciones que no necesitan clave: https://api.genesisarbitrage.com/health se abre en un navegador y muestra {"ok":true}. La barra de direcciones no puede añadir un encabezado X-API-Key, así que las peticiones con clave se hacen con curl, un script o el formulario "Probar" de la documentación. Nunca incluyas la clave en el código de un sitio web o de una extensión: cualquiera que abra el código fuente de la página la verá.

¿En qué se diferencia la opción -i de -v en curl?

-i imprime la línea de estado y los encabezados de la respuesta antes del cuerpo. -v muestra además la propia petición: las líneas con > son lo que se envió al servidor y las líneas con < son lo que volvió.

¿Cómo convierto el tiempo unix en una fecha sin Python?

En macOS, ejecuta date -u -r 1796463000; en Linux, date -u -d @1796463000. Para este número, ambos muestran el 5 de diciembre de 2026, 09:30 UTC.