API de libro de órdenes cripto: profundidad, precio de ejecución y slippage entre exchanges
En resumen
- Una API de libro de órdenes devuelve los niveles de compra y de venta —el precio y el tamaño de cada uno— como un snapshot REST o un stream WebSocket de cambios. El mejor bid y el mejor ask solo describen los primeros dólares de una operación.
- La profundidad fija el precio de una orden grande. En un ejemplo hipotético, una compra de 10 000 $ recorre cinco niveles, su precio medio queda 25 puntos básicos por encima del punto medio del libro y el spread entre exchanges baja del 1,20 % al 0,70 %.
- En los planes Pro y Max, Genesis API devuelve precios de ejecución ya calculados para 500–10 000 $, el Δ del libro de órdenes para las filas de arbitraje, la edad y la profundidad del libro, el historial de slippage y una escalera de slippage en DEX. Solo REST; los libros van entre 5 y 20 segundos por detrás del exchange.
Una API de libro de órdenes cripto devuelve las órdenes de compra y de venta vigentes de un par, agrupadas por nivel de precio: cada nivel lleva un precio y el tamaño que hay en él. Con esos niveles se calcula el precio de ejecución de una orden de un tamaño dado, su slippage y la profundidad de mercado, y con los libros de dos exchanges, cuánto spread sobrevive a una operación real.
Un exchange sirve su propio libro como snapshot REST o como stream WebSocket, mientras que Genesis API, en los planes Pro y Max, sirve precios de ejecución, profundidad y Δ del libro de órdenes ya calculados para muchos exchanges a la vez.
Qué devuelve una API de libro de órdenes
Un libro de órdenes es la lista de órdenes límite vigentes de un par. Las órdenes de compra (bids) se ordenan del precio más alto hacia abajo; las de venta (asks), del más bajo hacia arriba. Un nivel es un precio y el tamaño total que hay en él; la distancia entre el mejor ask y el mejor bid es el spread del libro.
Un snapshot REST es la respuesta a una sola petición: los niveles de ese momento. El endpoint del libro de órdenes de Binance es público y no necesita clave API; aquí tienes una petición de los cinco mejores niveles de BTC/USDT y una respuesta (los números son hipotéticos):
curl "https://api.binance.com/api/v3/depth?symbol=BTCUSDT&limit=5"
{
"lastUpdateId": 81273645120,
"bids": [["96015.90000000", "1.25000000"], …],
"asks": [["96016.00000000", "0.84100000"], …]
}
Cada nivel llega como un par de cadenas [precio, cantidad], con la cantidad en monedas: el mejor bid contiene 1,25 × 96 015,9 = 120 019,88 $. El parámetro limit es 100 por defecto y llega hasta 5000 niveles por lado (documentación de Binance).
Un stream WebSocket lo envía el exchange por una conexión persistente. Binance tiene dos tipos de streams de libro: btcusdt@depth5, btcusdt@depth10 y btcusdt@depth20 envían los 5, 10 o 20 mejores niveles, mientras que btcusdt@depth envía solo los cambios. Ambos se actualizan cada 1000 ms, o cada 100 ms con el sufijo @100ms (streams WebSocket de Binance).
Un libro local completo se construye con un snapshot más el stream de diferencias, comparando el lastUpdateId del snapshot con los ID de actualización de los eventos; si se pierde un evento, el libro se reconstruye desde cero.
| Método | Qué obtienes | Para qué usarlo |
|---|---|---|
| Snapshot REST | Niveles en el momento de la petición, hasta 5000 por lado en Binance | Comprobaciones puntuales, consultas poco frecuentes |
| Stream WebSocket | Mejores niveles o cambios cada 100–1000 ms | Un libro local en memoria, un bot de trading |
| Genesis API por REST | Niveles como [price, importe en USD], precio de ejecución, profundidad y edad del libro | Comparar exchanges, comprobar una operación |
Por qué el mejor bid y ask engañan con tamaño
El mejor ask es el precio del primer nivel solamente. Una compra a mercado mayor que ese nivel toma los siguientes, más caros, y el precio medio de ejecución sube: eso es el slippage.
Un ejemplo hipotético: el token ABC en el exchange A, mejor bid 0,9996, mejor ask 1,0004, punto medio del libro 1,0000. Una compra a mercado de 10 000 $ recorre cinco niveles de ask:
| Precio ask | En el libro, $ | Tomado, $ | Monedas |
|---|---|---|---|
| 1,0004 | 1100 | 1100 | 1099,56 |
| 1,0010 | 1400 | 1400 | 1398,60 |
| 1,0018 | 2600 | 2600 | 2595,33 |
| 1,0030 | 3000 | 3000 | 2991,03 |
| 1,0050 | 6000 | 1900 | 1890,55 |
La orden compra 9975,07 monedas en total. El precio medio de ejecución es el VWAP, el precio medio ponderado por volumen: 10 000 / 9975,07 ≈ 1,0025.
Slippage respecto al mejor ask: (1,0025 − 1,0004) / 1,0004 × 100 ≈ 0,21 %. Respecto al punto medio del libro: (1,0025 − 1,0000) / 1,0000 × 10 000 = 25 puntos básicos. Cuatro de ellos son la mitad del spread del libro, que paga toda compra a mercado; los otros 21 vienen de la profundidad.
Profundidad de mercado dentro de ±X % y muros
La profundidad de mercado es el tamaño total de las órdenes dentro de una distancia dada del mejor precio. En el ejemplo, los asks dentro del +0,2 % del mejor, hasta 1,0024, suman 1100 + 1400 + 2600 = 5100 $, y dentro del +0,5 %, hasta 1,0054, 14 100 $.
Lee la profundidad como capacidad: una orden mayor que la profundidad dentro del +0,2 % se ejecutará en niveles más allá de ese límite. En el exchange A una compra de 5000 $ cabe dentro de él, y una de 10 000 $ no.
Un muro es una orden grande en un solo nivel, notablemente mayor que sus vecinas: 6000 $ en 1,0050 en el ejemplo. Mientras el muro se mantiene, sostiene el precio, pero puede retirarse un segundo antes de que tu orden lo alcance, y entonces la compra se ejecuta en los niveles que quedan detrás.
En Genesis API la profundidad sale de /orderbooks/book, el libro de un mercado, y de /orderbooks/coin/{coin}, los libros de una moneda en todos los exchanges y mercados a la vez (Libro de órdenes del mercado, Libros de órdenes de la moneda). La respuesta incluye los 10 mejores bids y asks como [price, importe en USD], los muros más grandes en walls_bid y walls_ask, y la profundidad de todo el lado dentro de ±50 % del mejor precio en depth_bid_usd y depth_ask_usd. Un corredor de ±50 % es amplio, así que para un tamaño concreto mira los niveles o el precio de ejecución ya calculado.
Edad del libro: libros obsoletos y profundidad limitada
Cada snapshot de un libro tiene una edad. Si el libro de un exchange es 15 segundos más viejo que el del otro, parte del spread entre ellos puede ser un desfase temporal: el precio del libro más viejo ya se ha movido.
En Genesis API los libros van entre 5 y 20 segundos por detrás del exchange, y cada uno lleva su edad. El comienzo de una respuesta de /orderbooks/book de la documentación:
{
"exchange": "Binance",
"market": "spot",
"coin": "BTC",
"book_ts": 1794675858,
"age_sec": 6,
"stale": false,
"source": "ws",
"depth_limited": false,
"levels_bid": 500,
"levels_ask": 500,
…
}
book_ts es la hora del libro en segundos unix, age_sec su edad en segundos, y stale: true marca un libro de más de 30 segundos. source indica cómo se tomó el libro del exchange: por WebSocket (ws) o con peticiones REST (rest).
depth_limited: true significa que el exchange publica una profundidad limitada: los totales son parciales y una orden grande puede no ejecutarse. Cuando las órdenes se agotan, /orderbooks/exec devuelve null en lugar de un precio, y el Δ del libro de órdenes devuelve el estado exhausted.
Spread ejecutable entre exchanges: Δ del libro de órdenes
Volvamos al ejemplo hipotético. En el exchange B la última operación se cerró a 1,0120, el mejor bid es 1,0116 y el ask 1,0124. Los bids de B contienen 1100 $ en 1,0116, 1300 $ en 1,0110, 2800 $ en 1,0102, 2900 $ en 1,0090 y 5000 $ en 1,0070.
Vender 10 000 $ contra esos bids da un VWAP de 1,0095 con la misma fórmula. Eso es (1,0120 − 1,0095) / 1,0120 × 10 000 ≈ 24,7 puntos básicos por debajo del punto medio del libro de B.
| Cómo se calcula el spread | Comprar en A → vender en B | Spread |
|---|---|---|
| Últimas operaciones, como en una fila de la tabla | 1,0000 → 1,0120 | 1,20 % |
| Mejores precios del libro | 1,0004 → 1,0116 | 1,12 % |
| Tras ejecutar 10 000 $ | 1,0025 → 1,0095 | 0,70 % |
Spread de la fila: (1,0120 − 1,0000) / 1,0000 × 100 = 1,20 %. Tras la ejecución: (1,0095 − 1,0025) / 1,0025 × 100 ≈ 0,70 %. La fila promete 120 $ sobre 10 000 $, y tras los libros quedan unos 70 $: 10 000 × 0,006983 ≈ 69,83.
De los 50 puntos básicos perdidos, 8 se fueron en la distancia entre la última operación y las mejores órdenes, y los otros 42 en la profundidad de los dos libros.
El Δ del libro de órdenes es como Genesis Arbitrage llama al spread de una fila recalculado con los libros de órdenes para un tamaño dado; en el sitio es la columna «Δ por órdenes» de las tablas de arbitraje, por ejemplo Spot – Futuros. En la API sale de /orderbooks/spreads/{dataset}: cada fila de una moneda en el conjunto de datos spot-spot, spot-futures, futures-futures, dex-spot o dex-futures recibe un objeto order_delta (Δ del libro de órdenes).
order_delta lleva buy_price y sell_price para el tamaño elegido, el spread_pct posterior a la ejecución y un status: ok, no_book (sin libro) o exhausted (el libro no se llenó). El volume es 0 (mejores precios del libro) o 500, 1000, 2500, 5000, 10000, y el resultado nunca supera el spread de la fila. Las filas DEX llevan side y cex_price en lugar de un par de precios: el lado CEX y su precio de ejecución.
Los precios de ejecución, para todos los mercados a la vez, salen de /orderbooks/exec: un par [precio de compra, precio de venta] bajo una clave como Binance|spot|BTC, con null donde el libro es demasiado fino (Precios de ejecución).
La operación completa, con la transferencia de la moneda y las comprobaciones de red, se explica en Arbitraje de criptomonedas entre exchanges.
Ejemplo en Python: spread de la fila frente al spread tras la ejecución
El script toma las operaciones Spot – Spot con un spread de al menos el 0,5 %, pide el Δ del libro de órdenes a 5000 $ para las diez monedas con los spreads más amplios e imprime cuántos puntos básicos se llevaron los libros. La clave sale de la variable de entorno GENESIS_API_KEY. Ante 429 y 503 el script espera Retry-After segundos, y si la espera supera un minuto —la cuota mensual está agotada— se detiene.
import os
import time
import requests
BASE = "https://api.genesisarbitrage.com/v1"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
VOLUME = 5000 # dólares por pierna
MIN_SPREAD = 0.5 # spread de la fila, %
def get(path, params):
for _ in range(3):
r = requests.get(BASE + path, headers=HEADERS,
params=params, timeout=15)
if r.status_code in (429, 503):
wait = int(r.headers.get("Retry-After", "5"))
if wait > 60: # la cuota mensual está agotada
break
time.sleep(wait)
continue
r.raise_for_status()
return r.json()["data"]
raise RuntimeError("La API no respondió, inténtalo más tarde")
rows = get("/arbitrage/spot-spot", {"min_spread": MIN_SPREAD})
rows.sort(key=lambda x: x["spread_pct"], reverse=True)
coins = list(dict.fromkeys(x["coin"] for x in rows))[:10]
for coin in coins:
data = get("/orderbooks/spreads/spot-spot",
{"coin": coin, "volume": VOLUME})
for row in data:
od = row["order_delta"]
if row["spread_pct"] < MIN_SPREAD or od["status"] != "ok":
continue # no_book o exhausted: el tamaño no se ejecutará
lost = (row["spread_pct"] - od["spread_pct"]) * 100
print(f'{coin} {row["exchange_buy"]}→{row["exchange_sell"]}'
f' {row["spread_pct"]:.2f}% → {od["spread_pct"]:.2f}%,'
f' los libros se llevaron {lost:.0f} pb')
time.sleep(0.25) # hasta 4 peticiones por segundo: Pro permite 5
El script hace hasta 11 llamadas con una pausa de 0,25 s entre monedas. Ejecútalo en bucle no más a menudo que meta.freshness_sec: 10 s en Pro y 5 s en Max (límites de Genesis API). Para añadirle notificaciones, consulta Bot de arbitraje cripto en Python.
Historial del costo de ejecución
Un único snapshot no dice si el slippage actual es normal para el mercado o si el libro está más fino de lo habitual. /orderbooks/exec-history devuelve el historial de Genesis Charts: cuántos puntos básicos respecto al punto medio del libro cuesta ejecutar 500, 1000, 2500, 5000 y 10 000 $, por separado para compras y ventas (Historial de ejecución).
Cada intervalo tiene 360 puntos: 1m cubre 6 horas, 15m 3,75 días, 1h 15 días y 1d cerca de un año, con datos desde el 6 de septiembre de 2026. Una petición admite hasta 8 mercados en el parámetro keys. Los valores de compra son positivos y los de venta negativos; null significa que no hay datos o que el libro no se llenó. Genesis API no sirve snapshots pasados del propio libro.
import os
import statistics
import requests
KEY = "Binance|spot|BTC"
r = requests.get(
"https://api.genesisarbitrage.com/v1/orderbooks/exec-history",
headers={"X-API-Key": os.environ["GENESIS_API_KEY"]},
params={"keys": KEY, "interval": "1h"}, # 360 horas, 15 días
timeout=15,
)
r.raise_for_status()
data = r.json()["data"]
series = data["series"][KEY]
if series is None:
raise SystemExit("mercado no encontrado: " + KEY)
i = data["volumes_usd"].index(10000) # la serie de compra de 10 000 $
buy = series["buy"][i]
known = [x for x in buy if x is not None]
if not known:
raise SystemExit("sin datos para el periodo")
print("mediana de 15 días, pb:", statistics.median(known))
print("último punto, pb:", buy[-1])
Hipotéticamente, si la mediana de 15 días es de 12 puntos básicos y el último punto es 25, ejecutar ahora cuesta el doble de lo habitual, y tiene sentido subir el umbral de spread para esta moneda.
DEX: escalera de slippage, impuestos de tokens y honeypots
Un pool de un DEX no tiene libro de órdenes: el precio del swap sale de la fórmula del pool, y cuanto mayor es la operación respecto a la liquidez, más se mueve el precio. Por eso una pierna DEX se evalúa con una escalera: el slippage a una serie de tamaños.
/orderbooks/dex-slippage devuelve, por contrato, el slippage de compra y de venta a 100, 500, 1000, 2500, 5000, 10 000, 20 000, 50 000 y 100 000 $, los impuestos del token y el flag de honeypot, igual que las columnas de la tabla DEX del sitio (Slippage en DEX). En la respuesta de ejemplo de la documentación, el slippage de compra es 0,86 % a 10 000 $, 3,12 % a 50 000 $ y 6,05 % a 100 000 $.
Eso marca el límite de una operación: un spread DEX – CEX del 2 % sobrevive al slippage del pool a 10 000 $, pero no a 50 000 $, incluso antes de comisiones. null en la escalera significa que el pool no tiene liquidez para ese tamaño, y el gas de la red no está en la respuesta, así que cuéntalo aparte.
tax_buy_pct y tax_sell_pct son el impuesto de compra y de venta del token en %; null significa que no hay fuente y no debe leerse como cero. honeypot: no — sin señales, suspect — las fuentes no coinciden, yes — puede ser imposible vender el token.
Para comprobar un token a mano, consulta Cómo comprobar un token antes de comprarlo; para los precios y la liquidez de DEX junto a CEX, consulta API de DEX.
Libros de órdenes en Genesis API: endpoints y planes
| Tarea | Endpoint |
|---|---|
| Precio de ejecución para 500–10 000 $ en cada mercado | /orderbooks/exec |
| El spread de una fila tras la ejecución | /orderbooks/spreads/{dataset} |
| 10 niveles, muros, profundidad y edad del libro | /orderbooks/book |
| Los libros de una moneda en cada exchange | /orderbooks/coin/{coin} |
| Historial del costo de ejecución | /orderbooks/exec-history |
| Slippage en DEX, impuestos y el flag honeypot | /orderbooks/dex-slippage |
Los seis forman parte de los planes de API Pro y Max. Pro cuesta 100 $ al mes: 5 M de llamadas, 5 peticiones por segundo, frescura de 10 s. Max cuesta 200 $: 10 M de llamadas, 15 peticiones por segundo, 5 s; en Trial y Start los endpoints de libros de órdenes devuelven 403 plan_restricted.
Los parámetros y ejemplos de respuesta están en la guía de endpoints de libros de órdenes; para una visión general de los datos de la API, consulta API de criptomonedas y la lección Datos de API para arbitraje.
Preguntas y respuestas
¿Por qué el spread de la tabla es mayor que el que obtengo en una operación?
El spread de la fila sale de las últimas operaciones, mientras que una orden a mercado se ejecuta contra el libro, y cuanto mayor es el tamaño, más se aleja su precio medio del mejor. Las comisiones y el movimiento del precio durante la transferencia se suman después. El Δ del libro de órdenes muestra cuánto spread queda con tu tamaño.
¿Con qué frecuencia se actualizan los libros de órdenes?
Un libro cambia con cada orden nueva y cada cancelación; el stream de Binance envía cambios cada 100 o 1000 ms. En Genesis API los libros van entre 5 y 20 segundos por detrás del exchange (la edad está en age_sec), y las respuestas se actualizan cada 10 segundos en Pro y cada 5 segundos en Max.
¿Tiene Genesis API un WebSocket para libros de órdenes?
No. Genesis API es solo REST: una petición HTTP GET y una respuesta JSON. Los streams de libros en tiempo real vienen de los WebSocket de los propios exchanges, y eso es lo que necesita un bot que coloca órdenes a través de la API de trading de un exchange.
¿Hay una API de libro de órdenes gratuita?
Los exchanges tienen endpoints públicos: el libro de Binance en /api/v3/depth responde sin clave, pero cubre un solo exchange y el precio de ejecución lo calculas tú. Genesis API no tiene plan gratuito; los libros de órdenes están incluidos en Pro, a 100 $ al mes, y en Max, a 200 $.