Compressão e Cache

Leituras públicas grandes como GET /markets somam megabytes de JSON. Peça compressão e deixe o header Cache-Control de cada resposta informar o quão recente ela é.

Compressão

Envie Accept-Encoding: gzip e a API retorna o corpo comprimido com gzip, com Content-Encoding: gzip. GET /markets cai de cerca de 4 MB para cerca de 0,6 MB.

• Navegadores e o fetch do Node.js enviam o header e descomprimem automaticamente.
• O hypercall-client em Rust ativa gzip no seu cliente HTTP, então toda chamada REST solicita compressão e a decodifica de forma transparente.
• Python: requests e httpx enviam o header e descomprimem por padrão. O urllib puro não faz nenhum dos dois, então você recebe o corpo sem compressão.
• curl precisa de --compressed.

Respostas com menos de cerca de 1 KB são enviadas sem compressão. Frames de WebSocket não são afetados; veja compressão no WebSocket.

Cache-Control

Toda leitura informa se um cache compartilhado pode armazená-la.

Header da resposta	Onde aparece	O que significa
public, max-age=N	Dados públicos de mercado: /markets, /instruments, /instrument-specs, /exchange-info, gregas, resumos de opções e de vencimentos, theos históricos, leituras de pools, /version	Qualquer cache pode reutilizar o corpo por até N segundos. A maioria fica entre 1 e 15 segundos; dados históricos podem ter prazo maior.
public, max-age=N, stale-while-revalidate=M	Algumas das leituras acima	Depois de N segundos, um cache pode continuar servindo o corpo antigo por até M segundos adicionais enquanto busca um novo em segundo plano.
no-store	Leituras autenticadas e vinculadas a uma carteira: portfólio, ordens abertas, fills, trades filtrados por carteira, configuração de MMP e similares	Nunca armazenadas por nenhum cache. Toda requisição chega à API.
nenhum	Todo o resto, incluindo /orderbook e todas as escritas	Não armazenado em cache.

Considere que uma leitura public pode ter até max-age (mais qualquer stale-while-revalidate) segundos de idade. Quando você precisar do estado mais recente para uma decisão de trading, leia pelos canais de WebSocket ou por uma leitura vinculada à carteira, que nunca são armazenados em cache.

Respostas de erro (4xx, 5xx) nunca levam public e nunca são armazenadas em cache. Um cache não continua servindo um corpo expirado enquanto a API está retornando erros; você recebe o erro.

Requisições que sempre chegam à API

Um corpo em cache nunca é retornado para uma requisição que contenha qualquer um destes itens, e nada que essa requisição receba é armazenado:

• Authorization ou Cookie
• X-Hypercall-Signature ou X-Hypercall-Expires-At-Ms (leituras assinadas, como a configuração de MMP)
• X-Hypercall-Fence ou X-Hypercall-Fence-Wait (consistência de leitura após escrita, veja Market Maker Protection)
• X-Hypercall-Gateway-Token ou X-Admin-Key
• qualquer método diferente de GET ou HEAD, e upgrades de WebSocket

Fences de leitura após escrita e cache nunca se misturam. Uma rota que respeita X-Hypercall-Fence é no-store, e uma rota public nunca espera por um fence.

X-Cache-Status

Respostas que passam pelo cache de borda da Hypercall trazem X-Cache-Status:

Valor	Significado
HIT	Servida pelo cache de borda, dentro do max-age.
MISS	Buscada na API. Se a resposta era public, agora está em cache.
BYPASS	A requisição continha um header da lista acima, então foi direto para a API e nada foi armazenado.
EXPIRED	A cópia em cache tinha passado do seu tempo de vida, então a API foi consultada novamente.
STALE ou UPDATING	Servida do cache dentro da janela de stale-while-revalidate enquanto uma cópia nova é buscada.

Escritas e outras requisições que não são GET não têm X-Cache-Status. O header é apenas informativo: não baseie lógica de trading nele. Nem todo ambiente tem o cache de borda ainda. Uma resposta sem o header veio direto da API.