Estatísticas da plataforma

Esta página cobre o que as páginas de Referência geradas não conseguem. Cada uma das três operações tem sua própria página renderizada a partir do contrato. Esta página cobre o que elas compartilham: por que são públicas, o que os números significam e três lugares em que uma leitura plausível está errada.

Telemetria agregada da plataforma: volume negociado acumulado, contratos em aberto e a distribuição dos saldos das contas. Três operações, todas públicas. Elas declaram security: [], então nenhuma chave de API é necessária.

Estes são os números de toda a plataforma. O estado por conta fica nas páginas Account da barra lateral da Referência e nas páginas Positions.

Agregados por construção

Todo schema desta página é documentado como não carregando nenhum dado por conta: "Aggregate only — it carries no account id, address, or per-account volume by construction." Essa é a redação do próprio contrato, e é por isso que estes endpoints são públicos enquanto tudo em Account não é.

Se você está construindo um painel público, uma página de dados de mercado ou um agente que precisa de contexto da plataforma, estes são os endpoints a usar. Não derive agregados da plataforma distribuindo chamadas por leituras por conta.

Nesta página

Operação	Caminho	O que retorna
Volume acumulado	GET /stats/volume	Valor nocional negociado acumulado, total da plataforma e por mercado
Contratos em aberto	GET /stats/open-interest	Contratos em aberto, com long e short informados separadamente
Distribuição de saldos	GET /stats/balance-distribution	Contas por faixa de saldo

Outras duas operações /stats estão documentadas em outro lugar. GET /stats (snapshot da plataforma) e GET /stats/history (amostras de throughput) têm a tag Markets no contrato e são cobertas em GET /stats. As cinco são públicas.

Nenhuma das três operações daqui tem um gêmeo /api/v1. São apenas caminhos do gateway.

Os dados da testnet são ilustrativos, e o contrato diz isso na própria resposta

As três respostas carregam dois campos que você deve exibir em vez de descartar:

Campo	Significado
testnet	boolean, sempre true hoje. Os dados são ilustrativos.
note	um aviso legível por humanos, incluindo o alerta de unilateral versus bruto sobre contratos em aberto

Os números recomeçam quando o serviço recomeça, porque são projeções locais do indexador, não um registro contábil de todo o histórico. coverage_start_ms na resposta de volume diz até onde um total alcança no passado.

Decimais são strings

Todo valor nocional é um decimal sem perda serializado como string (o schema Decimal). Faça o parse com um tipo decimal, nunca com float. account_count e count são inteiros JSON, e os timestamps são milissegundos da época Unix (TimestampMs).

Os dois lados nunca vêm somados, e a nomenclatura é deliberada

Leia isto antes de rotular qualquer número deste endpoint.

• long_oi_quote (ou short_oi_quote) é o número a exibir. Em um livro casado, os dois são iguais por construção. Uma diferença persistente significa que a projeção perdeu a sincronia com o motor.
• gross_oi_two_sided_quote é long + short, o dobro do número unilateral. Ele se chama gross e two_sided para que ninguém consiga apresentá-lo como o total unilateral.
• Os números da plataforma são apenas em moeda de cotação. Não existe um total da plataforma em unidades base, de propósito. Unidades base não se somam entre mercados, então o contrato não publica um número sem uma unidade coerente.

Relacionados

• GET /stats: GET /stats e GET /stats/history, além de resumos por mercado e parâmetros de risco.
• As páginas Tickers da barra lateral da Referência: estatísticas de preço e volume em janela móvel de 24 horas por mercado.
• Schemas: referência dos schemas de componentes.

Questões em aberto

Lacunas no contrato, sinalizadas em vez de preenchidas:

• Nenhum schema é declarado para os tipos de limite dos subobjetos. BalanceBucket.min e max têm descrições, mas nenhum tipo declarado no contrato. Esta página os documenta como strings decimais, com base em "in USDX collateral" e na convenção de decimais da página.
• testnet é tipado como boolean, mas documentado como "always true". Não há comportamento definido para uma implantação em que ele seria false, e nenhuma operação expõe com qual implantação você está falando.
• A retenção não é informada. As três são descritas como recomeçando com o serviço, mas o contrato não dá janela de retenção, tamanho de buffer nem cadência de checkpoint. Portanto, o contrato não diz até onde no passado coverage_start_ms pode alcançar.
• Os valores de quote_error não são enumerados. O texto descreve três causas (nenhum preço de marca espelhado, preço de marca desatualizado, overflow), mas não especifica as strings, então você não pode ramificar com base nelas com segurança.