Referência da ferramenta de livro de ofertas

Esta página é a referência da ferramenta para recuperar snapshots do livro de ofertas do Cryptohopper Market Data MCP. Para o guia conceitual, consulte um guia prático para dados de livro de ofertas de criptomoedas.

Nome da ferramenta

get_orderbook

Finalidade

Retorna um snapshot pontual do livro de ofertas para um par especificado em uma corretora especificada. Contém as ofertas de compra e venda atuais em repouso com preço e tamanho por nível.

Argumentos

Argumento	Tipo	Obrigatório	Descrição
exchange	string	Sim	Identificador da corretora (minúsculas).
pair	string	Sim	Par no formato BASE/QUOTE (por exemplo, BTC/USDT).
depth	integer	Não	Número máximo de níveis a retornar por lado. O padrão depende da corretora. O limite superior depende da fonte.

Esquema de resposta

{
  "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	Descrição
exchange	string	O identificador da corretora de onde os dados vieram.
pair	string	O par, no formato BASE/QUOTE.
timestamp	string (ISO-8601)	Horário de captura do snapshot.
bids	array	Array de tuplas [preço, tamanho], ordenadas por preço decrescente (maior oferta de compra primeiro).
asks	array	Array de tuplas [preço, tamanho], ordenadas por preço crescente (menor oferta de venda primeiro).

Os preços e tamanhos são retornados como números JSON. Clientes que exigem precisão exata para cálculos relacionados à execução devem convertê-los para um tipo decimal imediatamente após a análise. Consulte modelo de dados para convenções.

Ordenação

• bids são ordenadas de forma decrescente por preço. A primeira entrada é a melhor oferta de compra (maior preço que um comprador está oferecendo).
• asks são ordenadas de forma crescente por preço. A primeira entrada é a melhor oferta de venda (menor preço que um vendedor está oferecendo).

O spread é a diferença entre asks[0] e bids[0]. O ponto médio é a média deles.

Profundidade

A profundidade do livro de ofertas varia por corretora. O MCP retorna o que a corretora upstream expõe por meio de sua API pública.

Profundidade típica (níveis por lado)	Corretoras
100	A maioria das principais corretoras no padrão
Até 500 ou mais	Algumas corretoras, quando a profundidade é solicitada

Solicitações de profundidade maior do que a corretora upstream suporta são limitadas ao máximo upstream. O argumento depth é de melhor esforço, não garantido.

Atualização

Os livros de ofertas são capturados no momento da solicitação. O campo timestamp reflete quando o snapshot foi lido da corretora upstream.

Os livros de ofertas ficam desatualizados muito rapidamente — normalmente em segundos em pares líquidos. Os clientes não devem armazenar em cache respostas do livro de ofertas para uso em decisões de execução.

Custo

Aspecto	Custo
Por invocação	1 unidade de chamada em todos os planos
Variante histórica	Não suportada — o histórico do livro de ofertas não está disponível através do MCP

Exemplos de invocações

Snapshot básico

Solicitado em um cliente MCP:

Mostre-me o livro de ofertas atual para BTC/USDT na Binance.

O agente invoca get_orderbook(exchange="binance", pair="BTC/USDT") e retorna um snapshot.

Profundidade personalizada

Busque os 50 principais níveis do livro de ofertas ETH/USDT na Kraken.

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

Métricas derivadas

O MCP retorna níveis brutos; métricas derivadas (spread, profundidade dentro de X%, derrapagem para um determinado tamanho de pedido) são calculadas pelo modelo ou pelo código que faz a chamada.

Erros

Código de erro	Causa
UNAUTHORIZED	Chave de API inválida ou revogada.
EXCHANGE_NOT_SUPPORTED	Corretora não disponível no plano ativo.
PAIR_NOT_FOUND	O par não existe na corretora especificada.
INVALID_PARAMETER	O argumento falhou na validação (por exemplo, símbolo de par malformado, profundidade negativa).
EXCHANGE_UNAVAILABLE	Corretora upstream não está respondendo.
RATE_LIMIT_EXCEEDED	Limite de taxa de intervalo curto atingido.
QUOTA_EXCEEDED	Cota semanal atingida.

Acesso por plano

As consultas ao livro de ofertas estão disponíveis em todos os planos (Pioneer, Explorer, Adventurer, Hero).

A restrição de cobertura de corretoras se aplica: no Pioneer, as consultas ao livro de ofertas são limitadas a Binance, Coinbase e Kraken. No Explorer e acima, mais corretoras estão disponíveis.