> 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/api-reference/pt-br/guides/networks.md). # Redes Como cada interface da Nexus Exchange seleciona uma rede, seja testnet, mainnet, local ou um destino personalizado que você mesmo descreve. Cada interface da Nexus Exchange se comunica com exatamente uma **rede**, escolhida quando você constrói o cliente. Uma rede não é um canal de release. Ela decide de quem é o dinheiro em jogo. A **testnet** opera com fundos sintéticos de teste, a **mainnet** operará com fundos reais e a **local** é para desenvolvimento. Selecionar uma delas agrupa tudo o que difere entre elas: os destinos REST e WebSocket, se existe um faucet e o domínio de assinatura ao qual suas requisições ficam restritas. Você escolhe uma rede em vez de montar uma URL. Para as URLs base atuais, consulte [APIs e limites](https://docs.nexus.xyz/exchange/apis-and-rates). Essas três são as redes publicadas. Uma implantação que você mesmo executa é uma [rede `Custom`](#the-custom-network). Ela carrega o mesmo pacote, mas você a descreve em vez de o cliente resolvê-la. ### As três redes publicadas | Rede | Fundos | Faucet | Disponibilidade | | --------- | --------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------- | | `testnet` | USDX sintético sem valor no mundo real | Sim | No ar hoje. O padrão em todas as interfaces. | | `mainnet` | Fundos reais, como USDX transferido pela ponte a partir da Ethereum Mainnet | Não | Será lançada com a Exchange de fundos reais. Ainda não está acessível; veja abaixo. | | `local` | Sintéticos, contra um indexador que você mesmo executa | Sim | Para desenvolvimento local. Não é uma rede pública. | A testnet é o padrão em todos os lugares de propósito, porque usar fundos reais como padrão seria inseguro. **A mainnet ainda não está acessível.** Seu host público não está no ar, então nenhuma interface resolve um destino de mainnet em seu nome. Em vez de enviar suas requisições para algum lugar plausível, mas errado, cada uma falha de forma fechada (fail closed). Os clientes Python e TypeScript lançam um erro na construção, e o servidor MCP se recusa a iniciar. O cliente Rust (e, portanto, a CLI) é construído normalmente, mas rejeita localmente toda requisição, antes que qualquer byte saia do processo. A única forma de passar é você mesmo nomear o destino. Python, TypeScript e o servidor MCP aceitam `mainnet` quando acompanhada de uma URL base explícita (consulte [Apontar para um host sem descrevê-lo](#pointing-at-a-host-without-describing-it)), que é como você alcança uma implantação de fundos reais antes de o host definitivo estar no ar. Em Rust, a substituição é um construtor separado que não carrega rede nenhuma, então ele aponta para uma URL em vez da mainnet. Nenhuma interface adivinha um destino de fundos reais por você, porque essa falha não pode ser ensaiada. Quando a mainnet for lançada, esta página e as notas de release de cada interface vão informar. ### Selecionar uma rede | Interface | Selecionar uma rede | Padrão | | ------------ | ---------------------------------------------------------------- | --------- | | Python | `Client(network=Network.TESTNET)` | `testnet` | | TypeScript | `new Client({ network: Network.Testnet })` | `testnet` | | Rust | `Config::new(Network::Testnet)` | `testnet` | | CLI | `--network `, ou `NEXUS_NETWORK` | `testnet` | | Servidor MCP | `NEXUS_EXCHANGE_NETWORK` | `testnet` | O `--network` da CLI também aceita o rótulo de um destino personalizado declarado no arquivo de configuração dela, e o servidor MCP aceita `NEXUS_EXCHANGE_NETWORK=custom` junto com um pacote descrito. Consulte [Descrever um destino personalizado](#describing-a-custom-target). Um nome de rede não reconhecido é sempre um erro. Nenhuma interface recorre a um padrão, e nenhuma recorre a `local`. As interfaces tratam um identificador desconhecido como fundos reais até prova em contrário, então você precisa corrigi-lo. Nomes de canais de release descontinuados são rejeitados com uma indicação de seu substituto. `stable` nomeava um host que serve a testnet, então `testnet` é seu equivalente direto. ### Exemplo ```python from nexus_exchange import Client, Network client = Client(network=Network.TESTNET, api_key=..., api_secret=...) ``` ```typescript import { Client, Network } from "@nexus-xyz/exchange-ts"; const client = new Client({ network: Network.Testnet, apiKey: "…", apiSecret: "…" }); ``` ```rust use nexus_exchange::{Config, Network}; let config = Config::new(Network::Testnet); ``` ```bash nexus --network local markets ``` ### A rede `Custom` As três redes acima são as publicadas. Uma implantação que você mesmo executa, como um stage privado, um ambiente de preview ou um indexador na sua própria infraestrutura, é uma **rede `Custom`**. Ela é um quarto tipo de destino que você descreve, e não uma URL anexada a uma das três. Ela é uma rede, e não um endereço, porque uma implantação privada ainda precisa de tudo o que uma rede nomeada agrupa, e uma URL não fornece nada disso. `Custom` carrega o mesmo pacote, fornecido por você: | Parte do pacote | Quem fornece | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Base REST** | Você. Obrigatória. | | **Base direta `/api/v1`** | Você, quando a implantação a separa da base REST. O padrão é a base REST, que é onde uma implantação de host único a serve. | | **Origem WebSocket** | Você, nas interfaces que permitem que uma implantação a separe. O SDK Rust e a CLI nunca derivam uma, porque derivá-la associaria um token de stream a uma origem que não o emitiu. Consulte [a nota sobre os conjuntos de campos](#the-two-field-sets-differ-deliberately). | | **Fundos** | Você. Obrigatório, sem padrão. Veja abaixo. | | **Faucet** | Você. Presumido **ausente** até ser declarado, para que uma chamada para abastecer a conta não possa ser roteada para um faucet que não existe. | | **Domínio de assinatura** | Lido do `GET /metadata` desta implantação, ou fornecido por você. Nunca adivinhado. | | **Rótulo** | Você. Obrigatório, porque é o namespace das credenciais. | #### Fundos é um campo obrigatório de três estados `funds` é `real`, `play` ou `unknown`, e **não tem padrão**. Nenhuma das respostas booleanas é segura de presumir. Uma implantação de staging da Exchange de fundos reais se comporta como fundos reais, e um ambiente de preview com dados de produção por trás não é dinheiro de teste só porque não é o host publicado. Só o operador sabe. `unknown` **falha de forma fechada**. É uma resposta legítima, já que você pode não saber, e dizer isso é melhor do que adivinhar. As interfaces então recusam as operações protegidas por fundos reais em vez de deixá-las passar. Se um comando ou ferramenta que movimenta valor for recusado em um destino personalizado, um `funds` não declarado é a primeira coisa a verificar. #### O rótulo é obrigatório e é um namespace de credenciais Todo destino `Custom` carrega um rótulo escolhido pelo chamador, restrito a `[A-Za-z0-9._-]` com no máximo 64 caracteres. `.` e `..` são rejeitados de imediato. O mesmo vale para os nomes aos quais as redes integradas já respondem (`mainnet`, `testnet`, `local` e o próprio `custom`), que são válidos nesse conjunto de caracteres, mas endereçariam as credenciais de outro destino ao nomeá-lo. O rótulo é a chave sob a qual suas credenciais armazenadas ficam em namespace, então ele chega ao sistema de arquivos nos clientes que persistem configuração. Um rótulo não validado contendo `/` ou `..` é um path traversal, e a credencial que ele endereçaria pertence a um destino diferente. O conjunto de caracteres e o limite de comprimento valem em todas as interfaces, e cada uma os aplica por conta própria em vez de herdá-los. O servidor MCP não é construído sobre o SDK Rust e carrega sua própria cópia da regra. Os nomes reservados são a única parte que ainda não é uniforme. O SDK Rust e a CLI recusam o nome de uma rede integrada, e o servidor MCP não. Escolha um rótulo que não colida com nenhum deles em vez de contar com a recusa para pegá-lo. Você escolhe os rótulos na sua própria configuração. `dev`, `preview` e `example` servem. #### O domínio de assinatura nunca é adivinhado Um destino `Custom` não herda um domínio de assinatura de lugar nenhum. O cliente lê o ID da rede EIP-712 do próprio `GET /metadata` da implantação, ou usa um que você fornece. Se não tiver nenhum dos dois, ele **se recusa a assinar** em vez de reutilizar um valor de outra rede. Entenda essa regra antes de esbarrar nela, porque a falha oposta é silenciosa. Uma assinatura feita sob o domínio errado pode ser *válida em outra rede*. Recusar é a única resposta segura. ### Apontar para um host sem descrevê-lo Toda interface ainda aceita uma URL base simples: | Interface | URL base simples | | ------------ | ----------------------------------------------------------- | | Python | `base_url=`, mais `direct_base_url=` para a base direta | | TypeScript | `baseUrl` | | Rust | `Config::with_base_url(…)`, mais `.with_direct_base_url(…)` | | CLI | `--base-url `, ou `NEXUS_BASE_URL` | | Servidor MCP | `NEXUS_EXCHANGE_API_URL` | Este é o atalho, não o caminho documentado. No servidor MCP ele está formalmente descontinuado. Ele continua funcionando sem mudanças, mas exibe um aviso que aponta para o pacote. Uma URL simples constrói um destino `Custom` com **fundos não declarados** e **sem domínio de assinatura**, então as operações protegidas por fundos reais são recusadas e o cliente não assina. Isso basta para uma consulta somente leitura a um host e, de propósito, não basta para negociar contra ele. Para fazer mais do que ler, descreva o destino em vez de nomear um endereço. ### Descrever um destino personalizado Duas interfaces recebem um pacote completo a partir da configuração, em vez de argumentos do construtor. **Servidor MCP.** Defina `NEXUS_EXCHANGE_NETWORK=custom` e depois: | Variável | Significado | | ------------------------------ | ------------------------------------------------------------------------------------------------------- | | `NEXUS_EXCHANGE_API_URL` | Base REST. Obrigatória. | | `NEXUS_EXCHANGE_NETWORK_LABEL` | O rótulo. Obrigatório. | | `NEXUS_EXCHANGE_FUNDS` | `real`, `play` ou `unknown`. Obrigatório. | | `NEXUS_EXCHANGE_FAUCET` | Se existe um faucet aqui. Ausente significa não. | | `NEXUS_EXCHANGE_GATEWAY_PATH` | Onde o caminho do gateway fica sob a origem: `/api/exchange` (padrão) ou `/` para um indexador simples. | Definir qualquer uma delas **sem** `NEXUS_EXCHANGE_NETWORK=custom` é um erro, e não um no-op silencioso. Meio pacote aplicado silenciosamente faria você acreditar que configurou uma propriedade de segurança que não está em vigor. **CLI.** Declare o destino em `custom_networks` no arquivo de configuração dela (`$XDG_CONFIG_HOME/nexus/config.json`, com fallback para `~/.config/nexus/config.json`) e selecione-o pelo rótulo: ```json { "custom_networks": { "dev": { "base_url": "https://exchange.example.com/api/exchange", "direct_base_url": "https://api.example.com", "funds": "play", "ws_url": "wss://stream.example.com", "faucet": true } } } ``` ```bash nexus --network dev markets ``` Um `chain_id` também pertence a essa entrada, depois que você o ler do próprio `GET /metadata` desta implantação. O exemplo o omite de propósito em vez de mostrar um valor de exemplo. Não existe sentinela que signifique *desconhecido*. A CLI usa qualquer número que você escrever como o domínio EIP-712, então um número inventado produz uma assinatura sob o domínio errado, enquanto omiti-lo produz uma recusa. Um rótulo não declarado é um erro. A CLI valida um rótulo declarado quando você o seleciona, não quando lê o arquivo, então um erro em um stage que você não está usando não quebra todos os outros comandos. #### Os dois conjuntos de campos diferem, deliberadamente Nenhuma lista é subconjunto da outra. Há três diferenças: * **`chain_id` é exclusivo da CLI.** O servidor MCP nunca produz uma assinatura EIP-712 (ele se autentica com HMAC), então não tem uso para um domínio de assinatura, e carregar um seria um segundo lugar para ele ficar desatualizado. * **`gateway_path` é exclusivo do MCP.** É a mesma configuração que o `direct_base_url` da CLI, abordada pelo outro lado. O servidor MCP recebe o caminho e deriva a base direta, e a CLI recebe a base direta e não precisa de caminho. * **`ws_url` é exclusivo da CLI.** O servidor MCP deriva sua origem WebSocket da base do gateway, o que o contrato da API suporta porque os caminhos de stream não carregam um host separado. A CLI aceita uma explícita porque uma implantação pode colocar seu stream em um host diferente. Assim, você pode descrever um destino personalizado com uma origem WebSocket separada para a CLI, mas ainda não para o servidor MCP. ### O que uma rede carrega Selecionar uma rede resolve tudo o que segue em conjunto, e é por isso que é uma escolha só em vez de várias: * **Base REST** para os endpoints de negociação e de conta. * **Bases WebSocket** para dados públicos de mercado e para o stream autenticado, quando a interface faz streaming. O SDK Python não inclui cliente WebSocket. O SDK Rust se recusa a conectar na testnet até que o host de stream publicado esteja no ar, em vez de associar um token de stream a uma origem que não o emitiu, então forneça uma URL WebSocket explícita nele. * **Se existe um faucet.** Entre as redes publicadas, o abastecimento sintético de contas é exclusivo da testnet e da local, e a mainnet não tem nenhum. Um destino personalizado declara o seu próprio, e presume-se que não tenha nenhum até declarar. * **Se os saldos são dinheiro real.** Uma única flag para decidir antes de qualquer coisa irreversível, em vez de fazer pattern matching em um hostname. * **O domínio de assinatura EIP-712**, que restringe o registro de agentes a esta rede. O servidor é a autoridade sobre seu ID da rede, então leia-o de `GET /metadata` para a rede à qual você está conectado. Um cliente que não consegue obter um se recusa a assinar em vez de reutilizar um valor de outro lugar. ### Credenciais e isolamento de rede Tokens de sessão, chaves de API HMAC e registros de agentes são emitidos **por rede** e são inválidos em todas as outras. Uma chave configurada para uma rede não se autentica em outra, então uma credencial exposta na testnet não pode assinar por fundos reais. Um cliente fica vinculado à sua rede durante toda a sua vida útil, e não existe setter. Trocar de rede significa construir um novo cliente com as credenciais próprias daquela rede, e nunca levar uma assinatura, nonce ou registro de agente de uma para outra. A CLI armazena credenciais **por rede**, indexadas pelo nome da rede. Para um destino personalizado, ela as indexa pelo rótulo em vez da URL, então dois stages no mesmo host mantêm credenciais separadas. Portanto, `--network` seleciona o destino *e* o conjunto de credenciais em conjunto. Ele não consegue emitir uma credencial. Trocar para uma rede que você ainda não configurou deixa você sem chave armazenada para ela, então execute `nexus setup` para essa rede, ou passe as credenciais dela junto com `--network` na linha de comando. #### O que vincula uma chave a uma rede **O host contra o qual você a emite.** A criação de chave não tem parâmetro de rede. `POST /keys` registra a rede da instância que atendeu a requisição, e a partir daí a chave é válida só ali. Então a URL base para a qual você aponta quando cria uma chave *é* a decisão de vínculo. Não há nada a definir e nada a confirmar. Planeje em torno de duas consequências: * Criar uma chave apontando para uma rede e depois negociar contra outra não tem como funcionar, independentemente de como o cliente for configurado depois. * Você precisa de uma chave separada por rede que pretende usar, emitida separadamente contra cada uma. #### Como é uma chave da rede errada Ela é exatamente igual a uma chave que não existe: **HTTP 401 Unauthorized** com este corpo: ```json { "code": "unauthorized" } ``` Essa resposta é **indistinguível, de propósito,** de uma assinatura inválida, um ID de chave desconhecido ou um cabeçalho ausente. Uma chave rejeitada não pode ser identificável como "real, mas registrada em outro lugar", porque isso permitiria que alguém confirmasse que um ID de chave adivinhado está ativo em outra rede. Por isso, a API não diz nada além de "esta requisição não está autenticada". **Uma falha de autenticação depois que você muda a rede de destino tem muito mais chance de ser a rede do que uma chave revogada.** Verifique qual host emitiu a chave antes de presumir que ela foi excluída ou que o segredo foi perdido. Nada na resposta vai apontar você para lá. #### Chaves emitidas antes do vínculo por rede Chaves criadas antes de existir o vínculo por rede não carregam uma rede própria. Elas continuam funcionando na testnet e na local, que adotam essas chaves como suas e registram a rede nelas. A mainnet **não** vai aceitá-las quando for lançada, porque uma chave sem marcação não prova nada sobre sua origem. Emita uma chave nova contra a mainnet em vez de esperar que uma existente seja aproveitada. Para o passo a passo completo de autenticação, do login com a carteira até uma requisição assinada, consulte o [Guia rápido](https://docs.nexus.xyz/exchange/trading/quickstart). ### Relacionados * [APIs e limites](https://docs.nexus.xyz/exchange/apis-and-rates): URLs base atuais e limites de requisições * [Visão geral das interfaces](/api-reference/pt-br/readme.md) * [Portfólio e estado da conta](/api-reference/pt-br/guides/portfolio.md) * [Guia rápido](https://docs.nexus.xyz/exchange/trading/quickstart) > **Status:** prévia de desenvolvimento na testnet. A mainnet não foi lançada e ainda não está acessível. O seletor de rede substituiu o seletor anterior de canais de release `{stable, beta, local}`. Fixe uma versão lançada em produção e verifique as notas de release de cada interface antes de atualizar. Credenciais e saldos da testnet não têm valor no mundo real. --- # 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/api-reference/pt-br/guides/networks.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.