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, esperaRetry-Afteren429y503, 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ón | Qué hace | En este bot |
|---|---|---|
| Datos | Obtiene precios y diferenciales entre exchanges | Genesis API GET /arbitrage/spot-spot |
| Filtro | Conserva los pares ejecutables | Estado de depósito y retiro, Δ del libro de órdenes con 1.000 $ |
| Alerta | Informa del par | Método sendMessage de la API de bots de Telegram |
| Decisión y operación | Comprueba el par y opera | Una 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.
- Mover la moneda: el retiro y el depósito tardan desde minutos hasta horas, y un exchange puede suspender depósitos o retiros en cualquier momento.
- Comisiones: ambos exchanges cobran comisión de trading, y la comisión de retiro suele ser un número fijo de monedas que se come el diferencial en una operación pequeña.
- Deslizamiento: el diferencial se calcula con las últimas operaciones, pero una orden de mercado recorre el libro de órdenes, así que una compra se ejecuta por encima del mejor ask y una venta por debajo del mejor bid.
- Tiempo: los datos llegan con el retraso de tu plan, hasta 60 segundos en Trial, y otros traders ven la misma diferencia y la cierran.
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
- Python 3.10 o superior y la biblioteca
requests. - Una clave de Genesis API de cualquier plan: pulsa «Obtener clave» en tu perfil y guarda la clave
gns_live_…, que se muestra una sola vez. Cómo guardarla y reemitirla se explica en la guía Clave de Genesis API. - Un token de bot de Telegram: envía
/newbota @BotFather, elige un nombre y un nombre de usuario, y BotFather responde con un token del tipo123456:ABC-DEF…. chat_id, el ID de tu chat con el bot. Un bot no puede escribirte primero (documentación de Telegram): envíale/starty luego llama agetUpdates; el número de"chat":{"id":…}es tuchat_id. Las actualizaciones se conservan como máximo 24 horas.
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
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_SPREADyMIN_VOLUMEdurante un rato: así verás que la cadena de la API a Telegram funciona.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.
Comprueba la deduplicación
El mismo par no debe llegar otra vez en menos de 15 minutos.
Vigila el uso de llamadas
Mira el campo
calls_usedde/account/usageo 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.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.
| Plan | Consulta | Comprobación del libro con 1.000 $ | Llamadas en 30 días |
|---|---|---|---|
| Trial, 20 $/mes | Cada 60 s | No | 43.200 de 500.000 |
| Start, 50 $/mes | Cada 30 s | No | 86.400 de 2 millones |
| Pro, 100 $/mes | Cada 10 s | Sí | Hasta 1.555.200 de 5 millones |
| Max, 200 $/mes | Cada 5 s | Sí | 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
- Precios desfasados: la instantánea se actualiza cada
freshness_secy los libros van entre 5 y 20 segundos por detrás del exchange, así que comprueba los precios en el terminal del exchange antes de operar. - Redes cerradas: los indicadores de depósito y retiro valen en el momento de la instantánea, y un exchange puede cerrar los retiros mientras compras. Un mismo ticker puede ser tokens distintos en exchanges distintos, así que contrasta
contractynetwork. - Comisiones y retiros:
spread_pctno los incluye, y una comisión de retiro fija se come todo el diferencial en un importe pequeño. - Falsos diferenciales en libros finos: un diferencial amplio de última operación en una moneda poco negociada desaparece con la primera orden.
min_volumey la comprobación con 1.000 $ filtran algunos de estos pares, pero no todos. - Chocar con los límites: las peticiones de más dentro de un segundo reciben
429conRetry-After: 1, y una cuota agotada detiene el bot hasta el reinicio. Usar varias claves o cuentas para esquivar los límites infringe las reglas; para cargas mayores existen planes superiores. Telegram también responde429bajo su control de flood.
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.