Referência da API

A interface programática da Nexus Exchange, com todos os endpoints, os guias que os explicam e os clientes oficiais.

Tudo o que um trader pode fazer na Nexus Exchange está disponível de forma programática. Esta seção tem uma página por endpoint, guias escritos à mão que os explicam e os clientes com suporte oficial.

Comece aqui	Primeiros passos · SDKs e ferramentas · Autenticação · Chaves de agente
Antes de construir	Tipos de ordem · Limites de requisições · Erros · Lacunas conhecidas
Referência	Uma página por endpoint, agrupadas por área na barra lateral
Schemas	Referência de schemas

URLs base

O contrato declara dois servidores públicos no nível do documento, nesta ordem:

Servidor	URL	Uso
Testnet pública (padrão)	https://api.testnet.nexus.xyz/v1	Fundos de teste. A base de transporte /v1, para os caminhos sem prefixo. É a primeira da lista, portanto é a base que um gerador escolhe por padrão.
Mainnet	https://api.nexus.xyz/v1	Fundos reais. Listada depois da testnet de propósito, para que nada que procure "o primeiro servidor https" caia no destino com fundos reais. Ainda não resolve. O DNS é uma mudança de infraestrutura separada (ENG-8155).

O contrato não nomeia uma rede padrão, então selecione uma explicitamente. "Padrão" na tabela acima significa apenas que a testnet é servers[0], a base que um gerador escolhe quando você não escolhe. A base do gateway legado https://exchange.nexus.xyz/api/exchange foi aposentada. Ela saiu do contrato e responde HTTP 410 com um corpo JSON que nomeia a substituta. Aponte os SDKs, a CLI e o servidor MCP para a base da testnet pública acima, que aplica limite de requisições e níveis.

Caminhos versionados (/api/v1) e sem prefixo

40 dos 116 caminhos são irmãos versionados /api/v1/… dos caminhos sem prefixo. São as mesmas operações, alcançadas por uma montagem versionada. As duas formas funcionam no host da testnet pública:

https://api.testnet.nexus.xyz/v1/tickers       → 200
https://api.testnet.nexus.xyz/api/v1/tickers   → 200

Prefira a forma sem prefixo na base /v1. É o que a entrada servers no nível do documento declara, e é o layout para o qual os clientes oficiais estão migrando. O contrato não marca nenhuma das variantes como deprecated. Os cinco caminhos /api/v1/bridge/… ainda não têm grafia sem prefixo no contrato, então chame esses na forma /api/v1 por enquanto.

Assine o caminho do contrato, não o caminho da URL. O prefixo de transporte que seleciona uma montagem (/v1 na base da testnet pública) é removido antes de a requisição chegar ao serviço que verifica sua assinatura, portanto não faz parte da string canônica do HMAC. O prefixo /api/v1 faz parte do caminho do contrato e é assinado. Chamar https://api.testnet.nexus.xyz/api/v1/tickers significa assinar /api/v1/tickers; chamar https://api.testnet.nexus.xyz/v1/tickers significa assinar /tickers. Veja Autenticação.

Os caminhos /api/v1 carregam uma substituição de servers, e os clientes devem respeitá-la. Todos os 40 declaram uma substituição no nível do caminho para a raiz do host da testnet pública, https://api.testnet.nexus.xyz. O caminho completo da operação é anexado a ela, então /api/v1/tickers resolve para https://api.testnet.nexus.xyz/api/v1/tickers. Esse é o "Declared server" que as páginas de Referência geradas mostram, e um cliente gerado que o respeita alcança a API.

A substituição existe porque essa base difere da base no nível do documento. A entrada de testnet do documento carrega /v1 e espera um caminho sem prefixo (https://api.testnet.nexus.xyz/v1/tickers), enquanto os caminhos com prefixo precisam da raiz do host. Combinar as duas metades à mão produz https://api.testnet.nexus.xyz/v1/api/v1/…, que não é a URL que o contrato declara para esses caminhos. O contrato observa que o chart da testnet pública também a aceita: o chart remove apenas o /v1 externo, e a requisição continua assinando /api/v1/….

Como ler esta seção

As páginas de Referência são geradas a partir do contrato. Cada uma informa o que openapi.json declara para aquela operação e nada mais: parâmetros, corpo da requisição, respostas, esquema de autenticação e classe de limite de requisições. A CI as renderiza de novo e compara, então elas não podem divergir do contrato.

Os Guias são escritos à mão. Eles cobrem o que uma página por endpoint não consegue: a matriz de requisitos por tipo de ordem em todas as operações que enviam ordens, as convenções de sinal, o modelo de erros e a lista do que o contrato deixa sem dizer.

Esta seção não informa quantos endpoints ou schemas existem. Uma contagem mantida à mão divergiu da última vez. A versão anterior desta seção publicou uma versão da spec dezoito releases minor desatualizada, com contagens de operações e schemas no mesmo estado. A barra lateral é gerada a partir do contrato, e o contrato é servido em /openapi.json. Ambos são a fonte oficial, então nenhum dos dois precisa de um número repetido em texto.

A especificação OpenAPI

A API é contract-first. O schema legível por máquina, com todas as rotas, corpos de requisição/resposta e o mapeamento de métodos CCXT, é publicado em nexus-xyz/nexus-exchange-api e servido ao vivo em /openapi.json. As releases são acompanhadas no GitHub Releases. Os SDKs, a CLI e o servidor MCP abaixo são, cada um, gerados a partir de uma versão publicada desta spec ou fixados nela, então correspondem ao gateway.

SDKs e ferramentas

Os SDKs em Rust, TypeScript, Python e Go, a CLI nexus, um servidor MCP e skills para agentes chamam esta API. SDKs e ferramentas lista cada um com seu repositório e linha de instalação.

Portfólio e estado da conta cobre os endpoints de conta e portfólio das quatro interfaces juntas: estado consolidado da conta, o saldo disponível para saque, a tabela de taxas, os campos enriquecidos de risco da posição e as séries temporais de patrimônio/PnL/volume.

O mesmo orçamento vale para qualquer coisa que você construir. As requisições são cobradas por peso por segundo, não contadas, e leituras, escritas de ordens e o plano de controle do WebSocket consomem três pools independentes. Leia Limites de requisições antes de escrever um limitador no lado do cliente. Um cliente que controla o ritmo pela contagem de requisições é recusado enquanto o próprio contador ainda parece saudável.

Escolhendo uma rede

A Exchange roda hoje na testnet como uma prévia de desenvolvimento, com uma mainnet pública a seguir. Cada interface aponta para uma rede por vez (testnet, mainnet ou local), selecionada quando você constrói o cliente. O cliente reúne os destinos REST e WebSocket dessa rede, a disponibilidade do faucet e o domínio de assinatura. Os SDKs, a CLI e o servidor MCP usam a testnet quando você não passa uma rede, e a mainnet ainda não está acessível. As credenciais ficam restritas à rede em que foram criadas.

Veja Redes para saber como cada interface seleciona uma, como substituir o destino e o que vincula uma chave de API a uma rede; APIs e limites para a URL base atual; e o Guia rápido para o fluxo de conexão de ponta a ponta.

Autenticação

A autenticação é idêntica em todas as interfaces. Você assina uma mensagem fixa com sua carteira (EIP-191) para obter um token de sessão de curta duração, usa esse token uma vez para emitir uma chave de API HMAC e depois assina cada requisição de negociação com essa chave. Os SDKs e a CLI assinam as requisições por você. O passo a passo completo, com exemplos executáveis, está no Guia rápido.

Status: prévia de desenvolvimento na testnet. As interfaces acompanham a spec OpenAPI release a release; em produção, fixe uma versão da spec e consulte as notas de release de cada repositório antes de atualizar. Credenciais e saldos da testnet não têm valor no mundo real.