> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/exchange/pt-br/apis-and-rates/apis-and-rates/exchange-websocket.md). # WebSocket da Exchange Streams em tempo real de livro de ofertas, negociações e conta: assinaturas, tokens e reconexão. A API WebSocket entrega em tempo real atualizações do livro de ofertas, negociações, candles, status do motor e eventos da conta (ordens, execuções, posições, saldos, liquidações). É o caminho recomendado para qualquer integração sensível à latência. ### Conectando Há dois endpoints WebSocket, e apenas um deles recebe um token. **`/stream`: dados de mercado públicos, sem token.** Abra o socket sem credenciais e envie uma mensagem listando os canais, como `{"subscribe": ["book:BTC-USDX-PERP"]}`. Apenas essa primeira mensagem é lida, então reconecte para mudar de canais. Os frames são identificados por `type` (`BookUpdate`, `Trade`, `MarketHalted`, `MarketResumed` e `gap` quando a conexão fica para trás). As apurações de desalavancagem automática não são publicadas em `/stream`, porque identificam as contas envolvidas. Todo frame do livro é um snapshot completo do top 20, e não um delta, então uma reconexão não precisa de replay. O servidor não envia heartbeat, e os hosts públicos fecham a conexão cerca de 30 segundos depois de ela ser aberta, então reconecte e assine novamente. Os limites e canais abaixo não se aplicam a `/stream`. **`/ws`: canais da conta e públicos, token obrigatório.** Navegadores não conseguem anexar cabeçalhos de autenticação personalizados a um upgrade de WebSocket, então este endpoint usa um token de curta duração em vez de um cabeçalho: 1. Chame `POST /ws/token`, assinado com sua chave HMAC ou com uma chave de agente registrada (uma requisição REST assinada normal). Isso emite um token opaco **de 60 segundos e de uso único**. Seu segredo nunca atravessa a fronteira do WebSocket. 2. Abra um WebSocket para `/ws?token=…` e assine com mensagens `{"op": "subscribe", "channel": "…", "market": "…"}`. Os tokens são de uso único e descartados após 60 segundos, e só são válidos na rede que os emitiu. Emita um novo para cada conexão. O legado `POST /ws-tokens` ainda emite tokens, mas nada na API atual precisa deles: `/stream` não recebe nenhum e `/ws` recebe um de `POST /ws/token`. ### Limites de conexão (`/ws`) * Máximo de **5 conexões ativas por IP**, aplicado no momento do upgrade em todos os níveis. Uma 6ª conexão é rejeitada com `HTTP 429` no upgrade. Nada é removido, e o token de uso único é consumido, então emita um novo antes de tentar novamente. * Um limite de conexões por conta se aplica além disso: **5** no nível Pro, **100** no MarketMaker. * As assinaturas são limitadas por conexão *e* por conta ao mesmo número (Pro 50, MarketMaker 1.000), então mais sockets não compram mais assinaturas. * Os frames recebidos do cliente são limitados por conexão (Pro 10/s, MarketMaker 50/s) com um burst de 2×; uma inundação sustentada fecha a conexão com o código `1008`. * **Esses tetos são um orçamento próprio.** Eles são independentes do orçamento de requisições REST e do orçamento de ações de negociação. Consulte [Limites de requisições](https://docs.nexus.xyz/interfaces/rate-limits). ### Canais (`/ws`) As assinaturas são por mercado onde indicado. Canais disponíveis: | Canal | Escopo | Payload | | -------------- | ----------- | ------------------------------------------------ | | `book` | por mercado | Atualizações de profundidade do livro de ofertas | | `trades` | por mercado | Negociações executadas | | `candles` | por mercado | Candles OHLCV | | `engine` | global | Throughput e status do motor | | `orders` | conta | Atualizações do ciclo de vida das ordens | | `fills` | conta | Suas execuções | | `positions` | conta | Mudanças de posição | | `balances` | conta | Mudanças de saldo | | `liquidations` | conta | Eventos de liquidação | Canais com escopo de conta (`orders`, `fills`, `positions`, `balances`, `liquidations`) exigem uma assinatura autenticada vinculada ao seu token. ### Metas de entrega O sistema tem como meta um fan-out de baixa latência; as metas de latência publicadas ficam mais rígidas ao longo das etapas de lançamento (entrega do livro de ofertas e das execuções medida do evento de matching até o recebimento pelo cliente). O comportamento atual da testnet é adequado para desenvolvimento e testes de integração. > **Status:** prévia na testnet. O formato exato das mensagens de assinatura e os schemas de cada canal são definidos na especificação OpenAPI em `/openapi.json` e nas páginas de WebSocket da [Referência da API](https://docs.nexus.xyz/api-reference); use-os como a fonte oficial para o formato das mensagens. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.nexus.xyz/exchange/pt-br/apis-and-rates/apis-and-rates/exchange-websocket.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.