Referencia de la herramienta de libro de órdenes

Esta página es la referencia de la herramienta para recuperar capturas del libro de órdenes desde el MCP de Datos de Mercado de Cryptohopper. Para la guía conceptual, consulta una guía práctica sobre datos del libro de órdenes de criptomonedas.

Nombre de la herramienta

get_orderbook

Propósito

Devuelve una captura en un momento específico del libro de órdenes para un par especificado en un exchange especificado. Contiene las ofertas y demandas actuales en reposo con precio y tamaño por nivel.

Argumentos

Argumento	Tipo	Requerido	Descripción
exchange	string	Sí	Identificador del exchange (minúsculas).
pair	string	Sí	Par en formato BASE/QUOTE (ej. BTC/USDT).
depth	integer	No	Número máximo de niveles a devolver por lado. El predeterminado depende del exchange. El límite superior depende del upstream.

Esquema de respuesta

{
  "exchange": "binance",
  "pair": "BTC/USDT",
  "timestamp": "2026-04-24T14:03:00Z",
  "bids": [
    [80934.18, 5.32816],
    [80930.05, 1.10000],
    [80925.40, 3.40000]
  ],
  "asks": [
    [80936.22, 1.20000],
    [80940.00, 2.50000],
    [80945.75, 0.80000]
  ]
}

Campos

Campo	Tipo	Descripción
exchange	string	El identificador del exchange de donde provienen los datos.
pair	string	El par, en formato BASE/QUOTE.
timestamp	string (ISO-8601)	Hora de captura de la instantánea.
bids	array	Array de tuplas [precio, tamaño], ordenadas por precio descendente (oferta más alta primero).
asks	array	Array de tuplas [precio, tamaño], ordenadas por precio ascendente (demanda más baja primero).

Los precios y tamaños se devuelven como números JSON. Los clientes que requieren precisión exacta para cálculos relacionados con ejecución deben convertirlos a un tipo decimal inmediatamente después del análisis. Consulta el modelo de datos para las convenciones.

Ordenamiento

• las bids están ordenadas descendentemente por precio. La primera entrada es la mejor oferta (el precio más alto que un comprador está ofreciendo).
• las asks están ordenadas ascendentemente por precio. La primera entrada es la mejor demanda (el precio más bajo que un vendedor está ofreciendo).

El spread es la diferencia entre asks[0] y bids[0]. El punto medio es su promedio.

Profundidad

La profundidad del libro de órdenes varía según el exchange. El MCP devuelve lo que el exchange upstream expone a través de su API pública.

Profundidad típica (niveles por lado)	Exchanges
100	La mayoría de los exchanges principales por defecto
Hasta 500 o más	Algunos exchanges, cuando se solicita profundidad

Las solicitudes de más profundidad de la que soporta el upstream se limitan al máximo del upstream. El argumento depth es de mejor esfuerzo, no garantizado.

Actualización

Los libros de órdenes se capturan en el momento de la solicitud. El campo timestamp refleja cuándo se leyó la captura desde el exchange upstream.

Los libros de órdenes se vuelven obsoletos muy rápidamente — típicamente en segundos en pares líquidos. Los clientes no deben almacenar en caché las respuestas del libro de órdenes para usarlas en decisiones de ejecución.

Costo

Aspecto	Costo
Por invocación	1 unidad de llamada en todos los niveles
Variante histórica	No soportada — el historial del libro de órdenes no está disponible a través del MCP

Ejemplos de invocaciones

Instantánea básica

Solicitado en un cliente MCP:

Muéstrame el libro de órdenes actual para BTC/USDT en Binance.

El agente invoca get_orderbook(exchange="binance", pair="BTC/USDT") y devuelve una captura.

Profundidad personalizada

Obtén los 50 niveles superiores del libro de órdenes de ETH/USDT en Kraken.

El agente invoca get_orderbook(exchange="kraken", pair="ETH/USDT", depth=50).

Métricas derivadas

El MCP devuelve niveles sin procesar; las métricas derivadas (spread, profundidad dentro del X%, deslizamiento para un tamaño de orden dado) son calculadas por el modelo o por el código que realiza la llamada.

Errores

Código de error	Causa
UNAUTHORIZED	Clave api inválida o revocada.
EXCHANGE_NOT_SUPPORTED	Exchange no disponible en el nivel activo.
PAIR_NOT_FOUND	El par no existe en el exchange especificado.
INVALID_PARAMETER	El argumento falló la validación (ej. símbolo de par mal formado, profundidad negativa).
EXCHANGE_UNAVAILABLE	El exchange upstream no está respondiendo.
RATE_LIMIT_EXCEEDED	Límite de tasa de intervalo corto alcanzado.
QUOTA_EXCEEDED	Cuota semanal alcanzada.

Acceso por nivel

Las consultas del libro de órdenes están disponibles en todos los niveles (Pioneer, Explorer, Adventurer, Hero).

Se aplica la restricción de cobertura de exchanges: en Pioneer, las consultas del libro de órdenes están limitadas a Binance, Coinbase y Kraken. En Explorer y superiores, están disponibles más exchanges.