Genesis Arbitrage

Genesis Arbitrage · · 14 min de lectura

Un monitor de spreads y funding en Python

En resumen

  • El monitor es un programa de consola: cada meta.freshness_sec segundos descarga los conjuntos completos /arbitrage/spot-spot y /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 con If-None-Match antes del siguiente snapshot devuelve 304 sin consumir cuota. Ante 429 y 503 el cliente espera Retry-After segundos.
  • 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ónQué devuelveCuándo
/account/usagePlan, freshness_sec, rps_limitAl inicio, no consume cuota
/arbitrage/spot-spotPares Spot – SpotEn cada pasada, conjunto completo
/funding/spreadMejores pares de exchanges por fundingEn 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 cuotaPausaPeticiones por pasadaLlamadas por 30 días
Trial, 500K60 s286.400
Start, 2M30 s2172.800
Pro, 5M10 s51.296.000
Max, 10M5 s52.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

  1. 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.

  2. Mueve el umbral

    Pon MIN_SPREAD = 0.5 y mira cuántas de las filas nuevas mantienen la columna -comis. por encima de cero.

  3. Añade un conjunto de datos

    Copia spot_rows para /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.

  4. Comprueba el consumo

    Pasada una hora, llama a /account/usage y compara calls_used con la estimación: en Trial son hasta 2 × 60 = 120 llamadas por hora.

  5. Busca pares duraderos

    Abre monitor.csv en 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.