Genesis Arbitrage

Genesis Arbitrage · · 19 min de lectura

Bot de arbitraje cripto en Python: de la API de diferenciales a las alertas de Telegram

En resumen

  • Un bot de arbitraje cripto tiene cuatro eslabones: datos de diferenciales, un filtro de pares ejecutables, una alerta y la decisión de una persona. El código resuelve los tres primeros; las operaciones las haces tú en los exchanges.
  • Ejecutar es lo difícil del arbitraje: mover la moneda, comisiones, deslizamiento y tiempo. Por eso el bot conserva solo los pares con retiros y depósitos abiertos y, en Pro y Max, recalcula además el diferencial con 1.000 $ del libro de órdenes.
  • El bot consulta Genesis API como máximo cada meta.freshness_sec, espera Retry-After en 429 y 503, y avisa de un par como mucho una vez cada 15 minutos. La versión básica funciona con el plan Trial de 20 $ al mes.

Un bot de arbitraje cripto es un programa que obtiene con regularidad los diferenciales entre exchanges (la diferencia de precio de una moneda, en porcentaje), conserva los pares que de verdad se pueden ejecutar y te avisa de ellos. La decisión y la operación las hace una persona. Un bot así para arbitraje spot entre exchanges ocupa unas 140 líneas de Python: los diferenciales vienen de Genesis API y los mensajes salen por la API de bots de Telegram.

De qué se compone un bot de arbitraje

Todo bot de arbitraje se construye con cuatro eslabones:

EslabónQué haceEn este bot
DatosObtiene precios y diferenciales entre exchangesGenesis API GET /arbitrage/spot-spot
FiltroConserva los pares ejecutablesEstado de depósito y retiro, Δ del libro de órdenes con 1.000 $
AlertaInforma del parMétodo sendMessage de la API de bots de Telegram
Decisión y operaciónComprueba el par y operaUna persona en los exchanges

Tu propio recolector de datos es el eslabón más lento de construir: cada exchange tiene su API, sus nombres de tickers y redes y sus estados de depósito y retiro, y todo hay que unificarlo en un solo formato. Genesis API devuelve pares ya listos de más de 20 exchanges CEX, entre ellos Binance, OKX, Bybit, Bitget, MEXC y Gate, con precios, diferencial, red, contrato, estado de depósito y retiro y volúmenes. Los campos de cada endpoint de arbitraje están en la guía Endpoints de arbitraje de Genesis API, y cómo elegir una fuente de datos se explica en API de criptomonedas: tipos y cómo elegir.

Por qué las operaciones las hace una persona

Encontrar un diferencial es la parte fácil del arbitraje. Ejecutarlo es lo difícil: entre una fila de la respuesta de la API y el dinero en tu cuenta hay cuatro obstáculos.

Ejemplo hipotético: el bot envía un par con un diferencial del 1,2 %, que son 12 $ sobre 1.000 $. Tras recorrer los libros de órdenes con 1.000 $ queda el 0,8 %, es decir, 8 $. Una comisión taker del 0,1 % en la compra y en la venta cuesta unos 2 $, y retirar la moneda cuesta 3 $.

Un código que compre y retire la moneda por sí solo convierte cada uno de estos fallos en una operación que nadie ha revisado. Por eso este bot envía una señal: comprueba por sí mismo retiros, depósitos y el diferencial tras los libros de órdenes, y una persona verifica el contrato, las comisiones y la ruta de transferencia antes de operar. De todos modos, Genesis API no puede operar: solo lee datos y no coloca órdenes. La comprobación manual paso a paso de un par está en Arbitraje de criptomonedas entre exchanges.

Qué necesitas

python3 --version   # se requiere Python 3.10 o superior
python3 -m pip install requests

export GENESIS_API_KEY="gns_live_XXXXXXXXXXXXXXXX"
export TG_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"

# tras /start en el chat del bot, busca "chat":{"id":...} en la respuesta
curl "https://api.telegram.org/bot$TG_BOT_TOKEN/getUpdates"

export TG_CHAT_ID="123456789"

Las variables definidas con export duran hasta que cierras el terminal. Según la documentación de Telegram, el token da control total del bot, y la clave da acceso a tu plan, así que ambos viven solo en variables de entorno: nunca van en el código ni en un repositorio.

Código del bot paso a paso

Los siete bloques siguientes forman el bot.py completo: guárdalos en un solo archivo y en este orden. Los umbrales de la configuración son valores de ejemplo; ajústalos a tus comisiones y al tamaño de tu operación.

1. Configuración

import os
import time

import requests

API = "https://api.genesisarbitrage.com/v1"
TG = "https://api.telegram.org/bot" + os.environ["TG_BOT_TOKEN"]
CHAT_ID = os.environ["TG_CHAT_ID"]

MIN_SPREAD = 1.0      # diferencial de la fila desde el 1 %
MIN_VOLUME = 50_000   # volumen 24 h en ambos exchanges desde 50 000 $
MIN_EXEC = 0.5        # diferencial tras libros de 1 000 $ desde el 0,5 %
TOP = 5               # pares por pasada, como máximo
REPEAT_SEC = 15 * 60  # un par, como mucho una vez cada 15 minutos
RECHECK_SEC = 5 * 60  # un par que el libro se comió espera 5 minutos

api = requests.Session()
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}       # petición -> (ETag, respuesta)
wait_until = {}  # par -> hora hasta la que se mantiene en silencio

La clave viaja en el encabezado X-API-Key de cada petición hecha con la sesión api y nunca va en la URL. MIN_VOLUME descarta los pares cuyo volumen de 24 h en alguno de los exchanges es inferior a 50.000 $. cache guarda los ETag de las respuestas y wait_until guarda la hora hasta la que el bot calla sobre un par.

2. Llamar a Genesis API: Retry-After y ETag

def get(path, params=None):
    """GET a Genesis API con reintentos por Retry-After y ETag."""
    key = (path, tuple(sorted((params or {}).items())))
    for _ in range(4):  # una petición y hasta tres reintentos
        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:  # la instantánea no ha cambiado
            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
        body = r.json()
        if "ETag" in r.headers:  # solo los conjuntos completos llevan ETag
            cache[key] = (r.headers["ETag"], body)
        return body
    raise RuntimeError("Genesis API ocupada, se reintenta luego")

429 se devuelve cuando superas el límite de peticiones por segundo o el volumen de descarga, y 503 mientras se reconstruyen los datos. Ambos llevan Retry-After, y get espera tantos segundos como pide el servidor. Una cuota agotada también devuelve 429, pero con Retry-After igual al momento del reinicio, a veces a días de distancia, así que el bot se detiene. 400, 401 y 403 no desaparecen al reintentar, por eso raise_for_status los lanza. Todos los límites están en la guía Límites de Genesis API.

3. Diferenciales y filtrado de pares

def candidates():
    """Pares Spot – Spot cuya moneda se puede mover de verdad."""
    body = get("/arbitrage/spot-spot",
               {"min_spread": MIN_SPREAD, "min_volume": MIN_VOLUME})
    # retiros abiertos en la compra, depósitos abiertos en la venta
    rows = [x for x in body["data"]
            if x["withdraw_enabled_buy"] and x["deposit_enabled_sell"]]
    rows.sort(key=lambda x: x["spread_pct"], reverse=True)
    return rows, body["meta"]["freshness_sec"]

min_spread y min_volume filtran las filas en el servidor. No hay parámetros para los indicadores de depósito y retiro, así que los comprueba el código: la moneda se puede mover si los retiros están abiertos en el exchange de compra (withdraw_enabled_buy) y los depósitos en el de venta (deposit_enabled_sell). Los campos que usa el bot, en una fila de la documentación de Spot — Spot:

{
  "coin": "FUEL",
  "exchange_buy": "ByBit",
  "exchange_sell": "Gate",
  "spread_pct": 0.11,
  "network": "ETH",
  "contract": "0x675B68AA4d9c2d3BB3F0397048e62E6B7192079c",
  "withdraw_enabled_buy": true,
  "deposit_enabled_sell": true,
  "volume_24h_buy": 17652.64,
  "volume_24h_sell": 12512.51,
  "trade_url_buy": "https://www.bybit.com/trade/spot/FUEL/USDT",
  "trade_url_sell": "https://www.gate.io/trade/FUEL_USDT",
  …
}

Esta fila no pasaría los filtros del bot: un diferencial del 0,11 % y volúmenes inferiores a 50.000 $. El bot incluye la red y el contrato en el mensaje para que los compares con las páginas de retiro y depósito de ambos exchanges.

4. La comprobación del libro con 1.000 $

def exec_spread(row):
    """Diferencial tras libros de 1 000 $. Solo Pro y Max."""
    body = get("/orderbooks/spreads/spot-spot",
               {"coin": row["coin"], "volume": 1000})
    for x in body["data"]:
        od = x["order_delta"]
        if (x["exchange_buy"] == row["exchange_buy"]
                and x["exchange_sell"] == row["exchange_sell"]
                and od["status"] == "ok"):
            return od["spread_pct"]
    return None  # no_book, exhausted o el par ya no existe

El endpoint devuelve las filas de la moneda del conjunto Spot – Spot con un objeto order_delta: Δ del libro de órdenes, el diferencial tras recorrer los libros, comprando contra los asks del exchange de compra y vendiendo contra los bids del exchange de venta. La función toma la fila con los mismos exchanges y su order_delta.spread_pct cuando status es ok; no_book significa que no hay libro y exhausted que el libro se agotó antes de llegar a 1.000 $. Los libros van entre 5 y 20 segundos por detrás del exchange; los campos se describen en la documentación de Δ del libro de órdenes y en la guía de endpoints de libros de órdenes.

Este paso existe solo en Pro y Max; en Trial y Start el endpoint devuelve 403 plan_restricted. El bot lee tu plan al arrancar y se salta la comprobación en esos planes: el mensaje indica que no se comprobó el libro, y la profundidad la miras tú en el terminal del exchange.

5. El mensaje de Telegram

def message(row, ex):
    buy, sell = row["exchange_buy"], row["exchange_sell"]
    if ex is None:
        book = "libro no comprobado (Trial o Start)"
    else:
        book = f"tras libros de 1.000 $: {ex:.2f} %"
    return "\n".join([
        f'{row["coin"]}: {buy} → {sell}',
        f'Diferencial {row["spread_pct"]} %, {book}',
        f'Red {row["network"]}, contrato {row["contract"] or "—"}',
        f'Compra: {row["trade_url_buy"]}',
        f'Venta: {row["trade_url_sell"]}',
    ])


def send(text):
    """sendMessage de la API de Telegram; con 429 espera retry_after."""
    for _ in range(3):
        r = requests.post(TG + "/sendMessage", timeout=15, json={
            "chat_id": CHAT_ID, "text": text,
            "link_preview_options": {"is_disabled": True}})
        if r.status_code != 429:
            r.raise_for_status()  # 400 o 401: chat o token incorrectos
            return
        wait = r.json().get("parameters", {}).get("retry_after", 5)
        time.sleep(wait)  # control de flood de Telegram
    raise RuntimeError("Telegram no aceptó el mensaje")

sendMessage acepta chat_id y text de 1 a 4096 caracteres, y la petición va a https://api.telegram.org/bot<token>/sendMessage (documentación de la API de bots de Telegram). link_preview_options con is_disabled desactiva las vistas previas de enlaces. Bajo el control de flood, Telegram devuelve 429 y pone la espera, en segundos, en parameters.retry_after. En un mismo chat, Telegram pide a los bots que no envíen más de un mensaje por segundo (FAQ para desarrolladores de bots).

Un mensaje tiene este aspecto, como ejemplo hipotético:

XYZ: MEXC → Gate
Diferencial 1,4 %, tras libros de 1.000 $: 0,62 %
Red ETH, contrato 0x…
Compra: https://…
Venta: https://…

6. Deduplicación: un par cada 15 minutos

def scan(books):
    """Una pasada: diferenciales, libros, mensajes."""
    rows, pause = candidates()
    done = 0
    for row in rows:
        key = (row["coin"], row["exchange_buy"], row["exchange_sell"])
        if time.time() < wait_until.get(key, 0):
            continue  # ya avisado, o el libro se comió el diferencial
        if done == TOP:
            break
        done += 1
        ex = exec_spread(row) if books else None
        ok = not books or (ex is not None and ex >= MIN_EXEC)
        if ok:
            send(message(row, ex))
        # en silencio 15 minutos tras un aviso, 5 si el libro es fino
        hold = REPEAT_SEC if ok else RECHECK_SEC
        wait_until[key] = time.time() + hold
        time.sleep(1)  # como máximo una petición y un mensaje por segundo
    return pause

Un par es la terna de moneda, exchange de compra y exchange de venta. Tras un aviso, el bot calla sobre ese par durante 15 minutos, aunque el diferencial se mantenga. Si el libro se comió el diferencial, el bot vuelve al par a los 5 minutos, así que la comprobación del libro no gasta una llamada en cada pasada. Cada pasada toma como máximo los cinco pares con mayor diferencial y espera un segundo tras cada uno: así el bot se mantiene dentro de lo que aconseja Telegram y dentro del límite por segundo de cualquier plan. El diccionario vive en memoria, así que tras un reinicio los pares recientes pueden repetirse.

7. El bucle: pausa de al menos freshness_sec

def main():
    usage = get("/account/usage")["data"]  # no consume cuota
    books = usage["plan"] in ("pro", "max")
    pause = usage["freshness_sec"]
    print("Plan", usage["plan"], "| consulta cada", pause, "s",
          "| libros:", "sí" if books else "no")
    while True:
        try:
            pause = scan(books)
        except requests.HTTPError as e:
            if e.response.status_code < 500:
                raise  # clave, plan o token: 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)  # no más a menudo que meta.freshness_sec


if __name__ == "__main__":
    main()

Al arrancar, el bot llama a /account/usage: la petición no consume cuota y devuelve tu plan y freshness_sec. Esa es la frescura de los datos, el intervalo con el que tu plan recibe una instantánea nueva: 60 segundos en Trial, 30 en Start, 10 en Pro y 5 en Max. Después, la pausa sale de meta.freshness_sec, porque consultar más rápido devuelve la misma instantánea. Los fallos de red y los errores 5xx esperan a la siguiente pasada, mientras que el resto de errores 4xx (una clave incorrecta, una suscripción caducada, un plan sin el endpoint, un token o chat_id incorrectos) detienen el bot. Los códigos de error están en Respuestas y errores de Genesis API, y un monitor de diferenciales sin Telegram se construye en la lección Monitor de diferenciales y funding en Python.

Cómo ejecutarlo y comprobarlo

python3 bot.py
# Plan trial | consulta cada 60 s | libros: no
  1. Espera la primera pasada

    Los mensajes llegan cuando el mercado tiene pares por encima de tus umbrales. Si en unos minutos no llega ninguno, baja MIN_SPREAD y MIN_VOLUME durante un rato: así verás que la cadena de la API a Telegram funciona.

  2. Compara un par con la tabla

    Abre Spot – Spot en el sitio: la misma moneda y el mismo par de exchanges están en la tabla. Los números pueden diferir un poco, porque la API sirve la instantánea con el retraso de tu plan.

  3. Comprueba la deduplicación

    El mismo par no debe llegar otra vez en menos de 15 minutos.

  4. Vigila el uso de llamadas

    Mira el campo calls_used de /account/usage o la línea «Llamadas usadas» de tu perfil: en Trial, sin comprobación del libro, el bot usa unas 1.440 llamadas al día.

  5. Deja el bot en marcha

    nohup python3 bot.py >> bot.log 2>&1 & ejecuta el bot en segundo plano; define las variables de entorno en la misma sesión del terminal.

Qué plan de Genesis API necesita el bot

Una pasada es una llamada a /arbitrage/spot-spot, más hasta cinco llamadas a /orderbooks/spreads/spot-spot en Pro y Max; solo las respuestas 200 consumen cuota. Límite superior para 30 días: (1 + comprobaciones por pasada) × 86.400 / pausa × 30.

PlanConsultaComprobación del libro con 1.000 $Llamadas en 30 días
Trial, 20 $/mesCada 60 sNo43.200 de 500.000
Start, 50 $/mesCada 30 sNo86.400 de 2 millones
Pro, 100 $/mesCada 10 sSíHasta 1.555.200 de 5 millones
Max, 200 $/mesCada 5 sSíHasta 3.110.400 de 10 millones

En Trial son 86.400 / 60 × 30 = 43.200 llamadas, el 8,64 % de la cuota. En Pro, en el peor caso en que cada pasada comprueba cinco libros, salen 6 × 86.400 / 10 × 30 = 1.555.200 llamadas, el 31,1 % de la cuota. Las reglas de la cuota están en la sección Planes y límites de la documentación.

Riesgos de un bot de arbitraje

Sin código: alertas de Genesis Arbitrage en Telegram

Si prefieres no escribir ni ejecutar tu propio bot, las Alertas de Telegram de Genesis Arbitrage envían los pares por ti. Creas un bot en @BotFather, pegas su token en el sitio y eliges categorías como Spot - Spot, DEX - Futuros, Crosschain y Arbitraje de Funding. Los filtros fijan el diferencial mínimo, los exchanges y las redes, el Estado de depósito/retiro y el Spread por órdenes, y el Tiempo de repetición (min) limita la frecuencia con la que vuelve un mismo par. El bot personal funciona con el plan Pro del sitio, aparte de los planes de Genesis API; la configuración está en la guía de notificaciones de Telegram.

Preguntas y respuestas

¿Puede el bot operar por sí solo?

No a través de Genesis API: la API solo sirve datos y no coloca órdenes. Operar se añade mediante las API propias de los exchanges con claves de trading, que es otro código y tu propio riesgo: un diferencial desfasado o un retiro cerrado se convierte en una operación que nadie ha revisado.

¿Cuánto cuesta un bot así?

El código es gratis, y también lo son los mensajes del bot a los usuarios de Telegram. Se paga por los datos: Genesis API empieza en 20 $ al mes con Trial, y la comprobación del libro empieza con Pro, a 100 $. Además necesitas un ordenador o un servidor que funcione las 24 horas.

¿Qué plan de Genesis API necesito?

Para el bot básico basta Trial: /arbitrage/spot-spot está en todos los planes, con una instantánea nueva cada 60 segundos. Start actualiza los datos cada 30 segundos. La comprobación de Δ del libro de órdenes con 1.000 $ solo funciona en Pro y Max.

¿Por qué el bot envió un par sin diferencial en el exchange?

Los datos llegan con el retraso de tu plan, y otros traders también cierran la diferencia. Además, el diferencial de la fila se calcula con las últimas operaciones, mientras que solo puedes comprar al ask y vender al bid. Comprueba los precios y el libro de órdenes en el terminal del exchange antes de operar.

¿Puedo subir el bot a GitHub?

Sí: las condiciones permiten crear tus propios bots sobre Genesis API, y la única restricción es revender los datos en bruto tal cual. Mantén la clave y el token fuera del repositorio. Si la clave acaba en código público, pulsa «Reemitir» en tu perfil, y el comando /token en @BotFather sustituye el token del bot.