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:
200significa leer los datos,304que nada ha cambiado,401y403que hay que revisar la clave y el plan,429y503que hay que esperarRetry-Aftersegundos. - La respuesta de Genesis API es un envoltorio con
success,dataymeta. Los porcentajes llegan como números simples (0.01significa 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
| Parte | En el ejemplo | Qué significa |
|---|---|---|
| Método | GET | Leer datos; todos los endpoints de Genesis API son GET |
| URL base | https://api.genesisarbitrage.com/v1 | Servidor y versión de la API |
| Ruta | /funding/rates | El endpoint de tasas de financiación (funding) |
| Parámetros | ?coin=BTC | Filtro: solo BTC |
| Encabezado | X-API-Key | La 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ódigo | Qué significa | Qué hacer |
|---|---|---|
200 | Petición atendida, datos en el cuerpo | Leer data y meta |
304 | Datos sin cambios desde tu última respuesta | Reutilizar los datos anteriores |
401 | Clave ausente, no válida, revocada o suscripción vencida | Revisar el encabezado y la suscripción |
403 | Endpoint fuera de tu plan (plan_restricted) | Cambiar de plan o descartar la petición |
429 | Límite de peticiones, descargas o cuota superado | Esperar Retry-After segundos |
503 | Datos 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:
- el envoltorio:
successestrue, los datos están endatay los campos de servicio enmeta;meta.countes el número de elementos dedata, que paracoin=BTCes una moneda, con una matrizexchangesdentro; - los porcentajes llegan como números simples:
"funding_pct": 0.01significa 0,01 % por intervalo, no 1 %; en una posición de 10.000 $, un pago con esta tasa es 10.000 × 0,01 / 100 = 1 $; funding_8h_pctnormaliza la tasa a 8 horas para que las exchanges con intervalos distintos se comparen directamente: Hyper liquida cada hora, y 0.0013 × 8 = 0,0104 % por 8 horas;next_payoutes la hora del próximo pago en UTC como cadena "HH:MM", ynullsignifica sin datos, no cero;meta.updated_ates el tiempo unix en que se generó la instantánea: 1794675861 es el 14 de noviembre de 2026, 17:04:21 UTC; en Trial la instantánea se actualiza cada 60 segundos.
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
| Error | Qué devuelve el servidor | Có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ía | 401 con el mismo texto: curl descarta un encabezado vacío | Comprueba la longitud: echo ${#GENESIS_API_KEY} |
Errata en la ruta: /v1/funding/rate o sin /v1 | 404 | Comprueba la ruta con la documentación |
Errata en el nombre de un parámetro: coins=BTC | 200 y todas las monedas: un parámetro desconocido se ignora | Revisa meta.count: con coin=BTC es 1 |
Coma decimal: min_spread=0,5 | 200 sin filtro aplicado | Usa punto: 0.5 |
Par en lugar de ticker: coin=BTCUSDT | 200, data vacío, meta.count de 0 | Usa 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
Envía una petición sin clave
curl -i "https://api.genesisarbitrage.com/v1/account/usage"devuelve401coninvalid_keyy "Missing X-API-Key header." en el cuerpo. Buscax-request-identre los encabezados.Repítela con la clave
Define la variable con
read -sy envía la petición de la sección/account/usage. Obtienes un200y tu plan endata.plan.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.
Encuentra la tasa más alta
Añade el segundo bloque al script y encuentra la exchange con el
funding_8h_pctmás alto. Normaliza a mano sufunding_pcta 8 horas: tasa × 8 / intervalo en horas.Rompe la petición a propósito
Cambia
coinporcoinsy comparameta.count; luego quita lasde/funding/ratesy 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.