> 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/readme.md).

# 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](/api-reference/pt-br/guides/get-started.md) · [Autenticação](/api-reference/pt-br/guides/authentication.md) · [Chaves de agente](/api-reference/pt-br/guides/agent-keys.md)                                                         |
| **Antes de construir** | [Tipos de ordem](/api-reference/pt-br/guides/order-types.md) · [Limites de requisições](/api-reference/pt-br/guides/rate-limits.md) · [Erros](/api-reference/pt-br/guides/errors.md) · [Lacunas conhecidas](/api-reference/pt-br/guides/known-gaps.md) |
| **Referência**         | Uma página por endpoint, agrupadas por área na barra lateral                                                                                                                                                                                           |
| **Schemas**            | [Referência de schemas](https://docs.nexus.xyz/api-reference/guides/schemas)                                                                                                                                                                           |

## URLs base

O contrato declara três servidores 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). |
| Desenvolvimento local    | `http://localhost:9090`            | Um indexador rodando na sua própria máquina.                                                                                                                                                                                      |

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 110 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](/api-reference/pt-br/guides/authentication.md).

{% hint style="info" %}
**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`, ou `http://localhost:9090` para desenvolvimento local. 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/…`.
{% endhint %}

### 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`](https://github.com/nexus-xyz/nexus-exchange-api) e servido ao vivo em `/openapi.json`. As releases são acompanhadas no [GitHub Releases](https://github.com/nexus-xyz/nexus-exchange-api/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

| Linguagem  | Repositório                                                           | Use para                                              |
| ---------- | --------------------------------------------------------------------- | ----------------------------------------------------- |
| Rust       | [`nexus-exchange-rs`](https://github.com/nexus-xyz/nexus-exchange-rs) | Clientes sensíveis à latência e bots de market making |
| TypeScript | [`nexus-exchange-ts`](https://github.com/nexus-xyz/nexus-exchange-ts) | Aplicações web, Node e edge                           |
| Python     | [`nexus-exchange-py`](https://github.com/nexus-xyz/nexus-exchange-py) | Pesquisa, backtesting e scripts                       |

Cada SDK cuida da assinatura das requisições (HMAC ou chave de agente), da paginação e do ciclo de vida das assinaturas WebSocket, para que você não precise reimplementá-los. Para saber quanto custa assinar em cada SDK, e se ele acompanha o seu nível, veja [custo de assinatura por SDK](/api-reference/pt-br/guides/rate-limits.md#can-your-signer-keep-up). O suporte a versões e a política de mudanças incompatíveis estão documentados no README de cada repositório.

[Portfólio e estado da conta](/api-reference/pt-br/guides/portfolio.md) 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](/api-reference/pt-br/guides/rate-limits.md) 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.

### Linha de comando

A [`nexus-exchange-cli`](https://github.com/nexus-xyz/nexus-exchange-cli) envolve a mesma API para uso interativo e scripts de shell. Ela gerencia chaves, envia e cancela ordens e consulta o estado da conta sem que você escreva código. `nexus --version` informa as versões da spec da API e do SDK com que ela foi construída.

### Servidor MCP

O servidor [`nexus-exchange-mcp`](https://github.com/nexus-xyz/nexus-exchange-mcp) expõe a Exchange como ferramentas do [Model Context Protocol](https://modelcontextprotocol.io), para que um assistente ou agente de IA possa negociar e ler o estado da conta pela mesma API autenticada que um cliente humano usa. Ele é publicado como [`@nexus-xyz/exchange-mcp`](https://www.npmjs.com/package/@nexus-xyz/exchange-mcp):

```bash
claude mcp add nexus-exchange -- npx -y @nexus-xyz/exchange-mcp
```

Ele roda sobre stdio, então as credenciais ficam na máquina que o adiciona, e suas ferramentas públicas de dados de mercado funcionam sem nenhuma chave.

### Escolhendo uma rede

A Exchange roda hoje na **Nexus 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](/api-reference/pt-br/guides/networks.md) 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](https://docs.nexus.xyz/exchange/apis-and-rates) para a URL base atual; e o [Guia rápido](https://docs.nexus.xyz/exchange/trading/quickstart) 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](https://docs.nexus.xyz/exchange/trading/quickstart).

> **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.


---

# 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/readme.md?ask=<question>&goal=<endgoal>
```

`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.