Un monitor de spreads y funding en Python
En resumen
- El monitor es un programa de consola: cada
meta.freshness_secsegundos descarga los conjuntos completos/arbitrage/spot-spoty/funding/spread, filtra las filas por umbrales, imprime tablas y las añade a un archivo CSV. - Ambos conjuntos se piden sin filtros, así que traen
ETag: una repetición conIf-None-Matchantes del siguiente snapshot devuelve304sin consumir cuota. Ante429y503el cliente esperaRetry-Aftersegundos. - Lo que queda tras una comisión taker supuesta del 0,1 % por pata es el spread menos 0,2 puntos porcentuales. En Pro y Max el monitor vuelve a comprobar los tres mejores pares con 1000 $ de libro de órdenes.
- El máximo es de 86.400 llamadas por 30 días en Trial, el 17,28 % de la cuota, y de 1.296.000 en Pro con comprobaciones de libro, el 25,92 %.
Un monitor de spreads y funding es un programa que consulta en bucle los spreads entre exchanges y los spreads de funding, se queda con las filas por encima de tus umbrales y las muestra como tabla en la consola. El monitor de esta lección tiene unas 170 líneas de Python: sus datos vienen de Genesis API, su historial va a un archivo CSV y no abre operaciones. Tampoco envía alertas; el bot con mensajes de Telegram se explica en Bot de arbitraje cripto en Python.
Plan de sondeo: endpoints, frecuencia y consumo de llamadas
| Petición | Qué devuelve | Cuándo |
|---|---|---|
/account/usage | Plan, freshness_sec, rps_limit | Al inicio, no consume cuota |
/arbitrage/spot-spot | Pares Spot – Spot | En cada pasada, conjunto completo |
/funding/spread | Mejores pares de exchanges por funding | En cada pasada, conjunto completo |
/orderbooks/spreads/spot-spot | Δ del libro de órdenes para 1000 $ | Pro y Max, tres pares por pasada |
meta.freshness_sec marca la frecuencia: tu plan recibe un snapshot nuevo cada 60 segundos en Trial, 30 en Start, 10 en Pro y 5 en Max. El sondeo (polling) más rápido devuelve el mismo snapshot con el mismo meta.updated_at. Los campos de ambos conjuntos están en la documentación de Spot — Spot y de Spread de funding.
| Plan y cuota | Pausa | Peticiones por pasada | Llamadas por 30 días |
|---|---|---|---|
| Trial, 500K | 60 s | 2 | 86.400 |
| Start, 2M | 30 s | 2 | 172.800 |
| Pro, 5M | 10 s | 5 | 1.296.000 |
| Max, 10M | 5 s | 5 | 2.592.000 |
En Trial: 2 × 86.400 / 60 × 30 = 86.400 llamadas, el 17,28 % de la cuota. En Pro, a los dos conjuntos se suman tres comprobaciones de libro: 5 × 86.400 / 10 × 30 = 1.296.000 llamadas, el 25,92 % de 5M. Las reglas de la cuota están en la guía de límites de Genesis API.
El monitor respeta el límite de peticiones por segundo con una pausa de 1,1 / rps_limit segundos entre peticiones: 1,1 segundos en Trial y 0,22 en Pro. Una pasada de cinco peticiones en Pro dura aproximadamente un segundo.
Ajustes y un cliente con ETag y Retry-After
Los siete bloques de código de esta lección forman el archivo monitor.py completo: guárdalos uno tras otro en un solo archivo. Los umbrales de los ajustes son orientativos; adáptalos a tus comisiones y tamaños.
import csv
import os
import time
from datetime import datetime, timezone
import requests
API = "https://api.genesisarbitrage.com/v1"
MIN_SPREAD = 1.0 # spread de la fila desde 1 %
MIN_VOLUME = 50_000 # volumen 24 h en ambos exchanges desde 50 000 $
MIN_FUNDING = 0.05 # spread de funding desde 0,05 %
FEE = 0.1 # comisión taker supuesta por pata, %
TOP = 10 # filas en cada tabla
BOOK_TOP = 3 # pares que se contrastan con libros por pasada, Pro/Max
BOOK_USD = 1000 # tamaño de la comprobación del libro, USD
CSV_FILE = "monitor.csv"
api = requests.Session()
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {} # petición -> (ETag, cuerpo de la respuesta)
stats = {200: 0, 304: 0} # cuántas respuestas 200 y 304 han llegado
pace = {"gap": 1.1, "last": 0.0} # pausa entre peticiones, s
La clave sale de la variable de entorno GENESIS_API_KEY y va en el encabezado X-API-Key de cada petición, nunca en la URL. cache guarda el ETag y el cuerpo de la última respuesta a cada petición, stats cuenta las respuestas 200 y 304, y pace recuerda cuándo salió la última petición.
def get(path, params=None):
"""GET a Genesis API: ritmo, ETag y reintentos por Retry-After."""
key = (path, tuple(sorted((params or {}).items())))
for _ in range(4): # una petición y hasta tres reintentos
wait = pace["last"] + pace["gap"] - time.monotonic()
if wait > 0:
time.sleep(wait) # como máximo rps_limit peticiones por segundo
pace["last"] = time.monotonic()
hdr = {"If-None-Match": cache[key][0]} if key in cache else {}
r = api.get(API + path, params=params, headers=hdr,
timeout=15)
if r.status_code == 304: # el snapshot no ha cambiado
stats[304] += 1
return cache[key][1]
if r.status_code in (429, 503):
wait = int(r.headers.get("Retry-After", "5"))
if wait > 60: # así se ve una cuota agotada
raise SystemExit(f"Cuota agotada: espera {wait} s")
time.sleep(wait)
continue
r.raise_for_status() # 400, 401, 403: reintentar no ayuda
stats[200] += 1
body = r.json()
if "ETag" in r.headers: # solo lo llevan los conjuntos completos
cache[key] = (r.headers["ETag"], body)
return body
raise RuntimeError("API ocupada, se reintenta en la siguiente pasada")
Un ETag es una etiqueta de versión del snapshot. get la devuelve en el encabezado If-None-Match y, mientras el snapshot no cambie, el servidor responde 304 sin cuerpo: no se consume cuota y la función devuelve el cuerpo anterior. Ante 429 y 503 espera Retry-After segundos y reintenta; una pausa de más de un minuto significa que la cuota del periodo se ha agotado, así que el monitor se detiene. Los códigos de error y las reglas de reintento están en la guía de respuestas y errores de Genesis API.
Spreads y funding: carga, umbrales y orden
def spot_rows():
"""Pares Spot – Spot por encima de los umbrales, con la moneda transferible."""
body = get("/arbitrage/spot-spot") # sin filtros: lleva ETag
rows = []
for x in body["data"]:
vol = min(x["volume_24h_buy"] or 0, x["volume_24h_sell"] or 0)
if (x["spread_pct"] >= MIN_SPREAD and vol >= MIN_VOLUME
and x["withdraw_enabled_buy"]
and x["deposit_enabled_sell"]):
rows.append({**x, "net": net(x["spread_pct"])})
rows.sort(key=lambda x: x["spread_pct"], reverse=True)
return rows[:TOP], body["meta"]
def funding_rows():
"""Monedas con el mayor spread de funding."""
body = get("/funding/spread") # sin filtros: lleva ETag
rows = [x for x in body["data"] if x["spread_pct"] >= MIN_FUNDING]
rows.sort(key=lambda x: x["spread_pct"], reverse=True)
return rows[:TOP], body["meta"]
Ambos conjuntos se piden sin parámetros: la respuesta a una petición con min_spread, coin u otro filtro se construye para esa petición y llega sin ETag. El monitor aplica los umbrales por su cuenta: un spread de al menos MIN_SPREAD, un volumen de 24 h de al menos MIN_VOLUME en ambos exchanges, retiros abiertos en el exchange de compra y depósitos abiertos en el de venta. Un volumen null cuenta como cero, así que esa fila no pasa.
Las filas se ordenan por spread_pct de mayor a menor y las primeras TOP entran en la tabla. En /funding/spread, el umbral MIN_FUNDING se compara con el spread_pct del mejor par.
Qué queda tras las comisiones y la comprobación del libro de órdenes
def net(spread_pct):
"""Lo que queda tras dos comisiones taker, aproximadamente, %."""
return round(spread_pct - 2 * FEE, 4)
def book_net(row):
"""Lo que queda tras BOOK_USD de libro y comisiones. Pro y Max."""
body = get("/orderbooks/spreads/spot-spot",
{"coin": row["coin"], "volume": BOOK_USD})
pair = (row["exchange_buy"], row["exchange_sell"])
for x in body["data"]:
if (x["exchange_buy"], x["exchange_sell"]) != pair:
continue
od = x["order_delta"]
if od["status"] != "ok":
return od["status"] # no_book o exhausted
return net(od["spread_pct"])
return "gone" # el par ha salido del conjunto de datos
Las comisiones taker supuestas del 0,1 % en la compra y del 0,1 % en la venta reducen el spread en unos 0,2 puntos porcentuales: un par al 1,62 % deja 1,62 − 2 × 0,1 = 1,42 %. Pon en FEE las comisiones de tus exchanges (maker y taker). Las comisiones de retiro no están en las respuestas de la API y el monitor no las tiene en cuenta.
En Pro y Max, book_net vuelve a comprobar los tres mejores pares con los libros de órdenes: /orderbooks/spreads/spot-spot con la moneda del par y volume=1000 devuelve las filas de esa moneda con un objeto order_delta, y la función toma la fila con el mismo par de exchanges (Δ del libro de órdenes). Si no hay libro o se agotó, en lugar de un número recibes el estado no_book o exhausted. Una petición con coin no lleva ETag y siempre cuesta una llamada, por eso una pasada hace solo tres, fijadas por BOOK_TOP.
La tabla de la consola
def show(spot, s_meta, fund, f_meta):
now = time.time()
s_age = now - s_meta["updated_at"]
f_age = now - f_meta["updated_at"]
print(f"\nSpot – Spot, antigüedad del snapshot {s_age:.0f} s")
print(f"{'Moneda':<8}{'Compra → venta':<20}"
f"{'Spread':>7}{'-comis.':>9}{'Libro':>11}")
for x in spot:
pair = f'{x["exchange_buy"]} → {x["exchange_sell"]}'
book = x.get("book", "—")
if isinstance(book, float):
book = f"{book:.2f}"
print(f'{x["coin"]:<8}{pair:<20}{x["spread_pct"]:>7.2f}'
f'{x["net"]:>9.2f}{book:>11}')
print(f"\nFunding, antigüedad del snapshot {f_age:.0f} s")
for x in fund:
b = x["best"]
legs = (f'{b["exchange_1"]} {b["interval_1"] or "?"} / '
f'{b["exchange_2"]} {b["interval_2"] or "?"}')
print(f'{x["coin"]:<8}{legs:<27}{x["spread_pct"]:>8.4f} %')
print(f"Respuestas 200: {stats[200]}, 304: {stats[304]}")
La primera tabla muestra la moneda, el par de exchanges, spread_pct, lo que queda tras las comisiones y lo que queda tras el libro; un guion significa que el libro no se comprobó. La segunda muestra el mejor par de exchanges por funding, con los intervalos de funding y spread_pct. Encima de las tablas va la antigüedad del snapshot, la hora actual menos meta.updated_at, y debajo, el número de respuestas 200 y 304 desde el inicio.
Historial en CSV
def save(spot, fund):
"""Añade la pasada al CSV: hora, conjunto, par, spreads."""
new = not os.path.exists(CSV_FILE)
ts = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
with open(CSV_FILE, "a", newline="", encoding="utf-8") as f:
w = csv.writer(f)
if new:
w.writerow(["time_utc", "dataset", "coin", "leg_1",
"leg_2", "spread_pct", "net_pct", "book"])
for x in spot:
w.writerow([ts, "spot-spot", x["coin"], x["exchange_buy"],
x["exchange_sell"], x["spread_pct"], x["net"],
x.get("book")]) # None pasa a ser una celda vacía
for x in fund:
b = x["best"]
w.writerow([ts, "funding", x["coin"], b["exchange_1"],
b["exchange_2"], x["spread_pct"], None, None])
La tabla de la consola dura hasta la siguiente pasada, mientras que monitor.csv conserva cada pasada: muestra cuánto dura un par y a qué horas aparece. El módulo csv forma parte de la biblioteca estándar de Python. Abre el archivo con newline="", como exige la documentación del módulo; de lo contrario, en los sistemas que usan saltos de línea \r\n, se cuela un \r de más en el archivo.
La columna book guarda lo que queda tras el libro, en porcentaje, o el estado exhausted o no_book. El módulo escribe None como celda vacía, así que la columna queda vacía en las filas de funding y en los pares sin comprobar. Las horas están en UTC.
El bucle principal
def main():
usage = get("/account/usage")["data"] # no consume cuota
books = usage["plan"] in ("pro", "max")
pace["gap"] = 1.1 / usage["rps_limit"]
print("Plan", usage["plan"], "| snapshot cada",
usage["freshness_sec"], "s | libros de órdenes:",
"sí" if books else "no")
pause = usage["freshness_sec"]
while True:
try:
spot, s_meta = spot_rows()
fund, f_meta = funding_rows()
if books:
for x in spot[:BOOK_TOP]:
x["book"] = book_net(x)
show(spot, s_meta, fund, f_meta)
save(spot, fund)
pause = s_meta.get("freshness_sec", pause)
except requests.HTTPError as e:
if e.response.status_code < 500:
raise # clave, plan o parámetros: reintentar no ayuda
print("Error del servidor, se reintenta:", e)
except (requests.RequestException, RuntimeError) as e:
print("Sin respuesta, se reintenta:", e)
time.sleep(pause) # más rápido que freshness_sec = el mismo snapshot
if __name__ == "__main__":
try:
main()
except KeyboardInterrupt:
print("\nMonitor detenido, el historial está en", CSV_FILE)
Al arrancar, el monitor llama a /account/usage: la petición no consume cuota y devuelve el plan, freshness_sec y rps_limit (Uso). El plan indica al monitor si debe comprobar los libros de órdenes, y rps_limit fija la pausa entre peticiones. El monitor aguanta los fallos de red y los errores 5xx hasta la siguiente pasada, mientras que los errores 4xx (una clave incorrecta, una suscripción caducada, un plan sin el endpoint) lo detienen.
Cómo ejecutarlo y leer la salida
python3 --version # se requiere Python 3.10 o superior
python3 -m pip install requests
export GENESIS_API_KEY="gns_live_XXXXXXXXXXXXXXXX"
python3 monitor.py
Salida en el plan Pro, un ejemplo ilustrativo:
Plan pro | snapshot cada 10 s | libros de órdenes: sí
Spot – Spot, antigüedad del snapshot 4 s
Moneda Compra → venta Spread -comis. Libro
KLM ByBit → Gate 1.62 1.42 0.86
XYZ MEXC → Gate 1.24 1.04 exhausted
ABC BingX → HTX 1.12 0.92 0.31
QRS Gate → OKX 1.05 0.85 —
Funding, antigüedad del snapshot 4 s
XYZ MEXC 4h / Bitget 8h 0.0600 %
ABC Hyper 1h / CoinEx 8h 0.0500 %
Respuestas 200: 6, 304: 0
KLM: el spread de la fila es del 1,62 %, del 1,42 % tras dos comisiones y del 0,86 % tras 1000 $ de libro de órdenes más comisiones. XYZ se quedó sin libro a 1000 $: para un par así reduces el tamaño o lo descartas. QRS es la cuarta fila, así que su libro no se pidió. La tabla de funding muestra con qué frecuencia liquida cada exchange: Hyper (el nombre de Hyperliquid en las respuestas) cada hora y CoinEx cada 8 horas. Pulsa Ctrl+C para detener el monitor.
De las cuatro comprobaciones de un par de la lección 3, el monitor hace por sí mismo la diferencia de precio y la transferencia, el libro de órdenes en Pro y Max, y muestra la frescura encima de la tabla. Tú verificas el contrato y la comisión de retiro.
Práctica
Inicia el monitor
La primera línea de la salida muestra el plan, el paso del snapshot y si se comprueban los libros; compáralos con tu perfil.
Mueve el umbral
Pon
MIN_SPREAD = 0.5y mira cuántas de las filas nuevas mantienen la columna -comis. por encima de cero.Añade un conjunto de datos
Copia
spot_rowspara/arbitrage/futures-futures: el formato de las filas es el mismo. Quita la comprobación de depósito y retiro en futuros, ya que allí no se mueve ninguna moneda entre exchanges.Comprueba el consumo
Pasada una hora, llama a
/account/usagey comparacalls_usedcon la estimación: en Trial son hasta 2 × 60 = 120 llamadas por hora.Busca pares duraderos
Abre
monitor.csven una hoja de cálculo y cuenta cuántas pasadas seguidas duró cada par de exchanges.
Los riesgos de la automatización, desde los datos desactualizados y los errores hasta las claves y los agentes de IA, se explican en la lección 5, y el sondeo económico con filtros, compresión y ETag, en el artículo sobre cómo consultar una API sin chocar con los límites.
Preguntas y respuestas
¿En qué se diferencia el monitor de un bot de arbitraje?
El monitor imprime una tabla y guarda el historial; un bot envía alertas sobre los pares nuevos y calla ante los repetidos. Comparten el código de la petición y del filtrado, y el bot de Telegram se explica en Bot de arbitraje cripto en Python.
¿Puedo consultar más rápido que freshness_sec?
No obtendrás datos nuevos: tu plan recibe un snapshot cada freshness_sec segundos. Una petición sin filtros antes del siguiente snapshot devuelve un 304 gratuito, mientras que una petición con filtros consume una llamada por los mismos datos.
¿Por qué la columna Libro muestra un guion?
La Δ del libro de órdenes solo está en Pro y Max, y el monitor la pide para los tres mejores pares (BOOK_TOP). En Trial y Start el endpoint devuelve 403 plan_restricted, por eso el monitor no lo llama.