Modelo de Dados

Esta página descreve o modelo de dados comum compartilhado pelas ferramentas de dados de mercado do MCP da Cryptohopper. Os três tipos principais de dados — ticker, livro de ofertas e vela — cada um tem sua própria página de referência com o esquema de resposta exato:

• Referência da ferramenta de ticker
• Referência da ferramenta de livro de ofertas
• Referência da ferramenta de velas

Esta página documenta as convenções comuns a todos os três.

Convenções

Formato de símbolo

Todos os símbolos de pares usam o formato BASE/COTAÇÃO:

Exemplo	Base	Cotação
BTC/USDT	BTC	USDT
ETH/USD	ETH	USD
SOL/USDC	SOL	USDC

O formato é normalizado no lado do servidor. As corretoras upstream usam uma variedade de notações (por exemplo, BTCUSDT, BTC-USDT, tBTCUSDT); o MCP apresenta um formato BASE/COTAÇÃO uniforme, independentemente da convenção upstream.

Veja corretoras suportadas para a lista de corretoras que o MCP pode consultar.

Identificadores de corretoras

Os nomes das corretoras nas requisições e respostas usam identificadores em minúsculas:

Identificador	Corretora
binance	Binance
coinbase	Coinbase
kraken	Kraken
bybit	Bybit
okx	OKX

A lista completa é retornada pela ferramenta list-exchanges e documentada em corretoras suportadas.

Timestamps

Todos os timestamps nas respostas estão em UTC e formatados em ISO-8601: 2026-04-24T14:03:00Z

Timestamps numéricos, quando expostos (por exemplo, dentro de registros de velas), são timestamps Unix em milissegundos.

Codificação decimal

Os valores de preço e tamanho são retornados como números JSON (floats). Exemplos de cada ferramenta:

// Ticker
{
  "last": 80934.19,
  "baseVolume": 11744.6152
}

// Orderbook level
[80934.18, 5.32816]

// Candle record
[1778540400000, 81833.92, 81833.92, 81720.40, 81812.55, 142.8731, 318]

Como os números JSON são analisados como ponto flutuante IEEE-754 na maioria das linguagens, os clientes que requerem precisão exata (por exemplo, ao calcular tamanhos de pedidos) devem converter esses valores para um tipo decimal imediatamente após a análise — por exemplo, Decimal do Python, BigNumber.js do JavaScript ou equivalente.

Campos opcionais

Alguns campos são opcionais e podem estar ausentes das respostas quando a corretora upstream não os fornece. Os clientes devem tratar campos ausentes como nulos em vez de um erro.

Campos comuns

Três campos aparecem na maioria das respostas:

Campo	Tipo	Descrição
exchange	string	O identificador da corretora de onde os dados vieram.
pair	string	O par no formato BASE/COTAÇÃO.
timestamp	string (ISO-8601)	O momento em que os dados foram capturados.

Os campos restantes dependem da ferramenta. Os esquemas completos seguem abaixo.

Esquema de ticker (resumo)

Uma resposta de ticker é um único objeto descrevendo o estado atual de um mercado. Os nomes dos campos seguem as convenções CCXT.

Os campos incluem:

• last — último preço negociado
• bid — melhor preço de oferta de compra
• ask — melhor preço de oferta de venda
• bidVolume — tamanho na melhor oferta de compra
• askVolume — tamanho na melhor oferta de venda
• high — máxima de 24 horas
• low — mínima de 24 horas
• open — preço de abertura para a janela de 24 horas
• close — preço de fechamento para a janela de 24 horas (tipicamente igual ao last)
• previousClose — preço de fechamento da janela anterior de 24 horas
• average — média de abertura e fechamento
• vwap — preço médio ponderado por volume de 24 horas
• baseVolume — volume de 24 horas no ativo de base
• quoteVolume — volume de 24 horas no ativo de cotação
• change — variação absoluta de preço de 24 horas
• percentage — variação percentual de 24 horas

Veja referência da ferramenta de ticker para o esquema completo e tipos de campos.

Esquema de livro de ofertas (resumo)

Uma resposta de livro de ofertas contém dois arrays — bids e asks — cada elemento sendo uma tupla [preço, tamanho]:

• bids — array de pares [preço, tamanho], ordenados por preço decrescente (maior oferta de compra primeiro)
• asks — array de pares [preço, tamanho], ordenados por preço crescente (menor oferta de venda primeiro)

A profundidade de cada lado depende da corretora upstream. Veja referência da ferramenta de livro de ofertas para detalhes.

Esquema de vela (resumo)

Uma resposta de vela é um array de registros OHLCV, ordenados cronologicamente (mais antigo primeiro por padrão). Cada registro é em si um array com sete posições:

Índice	Campo	Descrição
0	timestamp	Tempo de abertura da barra (timestamp Unix em milissegundos)
1	open	Preço de abertura
2	high	Preço mais alto na barra
3	low	Preço mais baixo na barra
4	close	Preço de fechamento
5	volume	Volume do ativo de base negociado na barra
6	count	Número de operações na barra

Exemplo:

[1778540400000, 81833.92, 81833.92, 81720.40, 81812.55, 142.8731, 318]

Veja referência da ferramenta de velas para o esquema completo, períodos de tempo suportados e semântica de lookback.

Respostas de erro

Quando uma invocação de ferramenta falha, a resposta segue o envelope de erro do MCP:

{
  "code": "QUOTA_EXCEEDED",
  "message": "Weekly call limit reached",
  "details": {
    "reset_at": "2026-04-25T00:00:00Z"
  }
}