Convenções da API

Regras que valem para todos os endpoints: estrutura das URLs, envelope de resposta, símbolos, unidades, timestamps, paginação e cache.

URL base e versionamento

Todos os endpoints ficam sob uma única URL base e são chamados com GET por HTTPS. Os caminhos atuais são a versão v1. Dentro da v1, as mudanças são aditivas: campos e endpoints podem ser adicionados, e os campos existentes mantêm nome, tipo e significado. Uma mudança incompatível seria publicada em um novo caminho e anunciada antes no registro de alterações.

URL basehttps://www.coinboss.com/api

Envelope de resposta

Toda resposta JSON tem um indicador success no nível superior. Os endpoints da camada de dados de coleta própria (caminhos em /api/sd) compartilham os mesmos blocos adicionais:

Campo	Descrição
success	true quando a chamada funcionou. Verifique sempre.
schema	Identificador e versão principal do formato da resposta.
now	Horário do servidor em que a resposta foi montada, em milissegundos.
coverage	Quais corretoras estão incluídas, quais estão indisponíveis e por quê, e quais foram excluídas por estarem desatualizadas.
method	A fórmula ou regra por trás de cada agregado da resposta.
meta	Fontes, timestamps, janela, classificação de qualidade, indicador de desatualização, tempo de vida do cache e o comportamento de fallback.

Endpoints mais antigos retornam success e um campo data, e podem não incluir coverage, method nem meta. Suas páginas de referência documentam os campos exatos.

Moedas, contratos e corretoras

Os parâmetros coin recebem o símbolo base em maiúsculas, por exemplo BTC ou PEPE.
Contratos com multiplicador, como 1000PEPE ou kPEPE, são consolidados na moeda base, com as quantidades convertidas.
Os identificadores de corretora são em minúsculas, por exemplo binance, okx, bybit, hyperliquid.
Os símbolos de contrato são retornados como a corretora os nomeia. Contratos com margem em USDT, USDC e cripto e futuros com vencimento são diferenciados por um campo de tipo de contrato nos endpoints que os misturam.
Perpétuos de ações tokenizadas e de commodities que compartilham o ticker com um criptoativo são excluídos dos agregados cripto.

Unidades

Campos terminados em _usd são valor nocional em dólares americanos.
As taxas de financiamento são frações, não percentuais: 0.0001 significa 0.01%. Campos terminados em _8h são normalizados para um intervalo de 8 horas; o intervalo original é retornado junto com a taxa bruta.
Campos terminados em _pct são percentuais: 1.5 significa 1.5%.
Os contratos em aberto são valor nocional unilateral em USD, salvo indicação em contrário na descrição do campo. As corretoras que publicam números bilaterais são indicadas no bloco method.
Alguns endpoints legados retornam decimais como strings para preservar a precisão. A tabela de campos mostra o tipo como string(decimal).

Timestamps

Os timestamps são milissegundos da época Unix em UTC, salvo indicação em contrário na descrição do campo.
observed_at é o timestamp da própria corretora para o registro mais recente incluído, ou null quando a corretora não o fornece.
received_at é quando o coletor da CoinBoss armazenou esse registro.
fetched_at é quando a resposta foi montada. Em uma resposta em cache, ele é anterior ao horário da sua chamada em até o TTL do cache.
As séries diárias usam os limites de dia em UTC.

Janelas e intervalos

Os parâmetros de janela usam tokens curtos: 1h, 4h, 12h, 24h e, em alguns endpoints, 3d, 7d, 30d, 90d. A página de referência lista os valores aceitos por cada endpoint.
Um valor de janela desconhecido é rejeitado com INVALID_PARAM ou substituído pelo padrão documentado, conforme indicado em cada parâmetro.
O tamanho do bucket das séries temporais depende da janela e é indicado na página de referência.

Paginação e ordenação

Os endpoints de lista usam limit e offset, ou page e size, conforme documentado em cada endpoint. Os limites têm teto; um valor maior é reduzido ao teto.
Quando uma resposta inclui total, ele é o número de linhas antes da paginação.
A ordenação é fixa, a menos que o endpoint documente um parâmetro sort.

Null, zero e ausente

null significa que o valor é desconhecido ou está indisponível. 0 significa um zero medido.
Os gráficos devem mostrar uma lacuna para null. Não interpole.
Um campo marcado como “pode estar ausente” em uma tabela de campos pode faltar por completo no objeto; trate-o como null.

Cache

Cada endpoint tem um TTL de cache do servidor, indicado na sua página de referência e em meta.cache_ttl_s. O cabeçalho X-Cache informa HIT, STALE ou MISS.
Um cache de borda de curta duração, de cerca de dez segundos, fica à frente da maioria dos endpoints GET.
Consultar com frequência maior que o TTL retorna dados idênticos e só consome o seu limite de requisições.

WebSocket

WebSocketwss://www.coinboss.com/ws

O fluxo é JSON somente de envio pelo servidor. Cada mensagem tem um campo type.
Após uma desconexão, reconecte após um intervalo e preencha a lacuna com o endpoint HTTP correspondente.

Documentação legível por máquina

O catálogo, os parâmetros e a tabela de campos de cada endpoint, o status e a matriz de qualidade estão disponíveis em JSON em /api/meta, e o catálogo completo como um documento OpenAPI 3.