> 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/authentication.md). # Autenticação Login com carteira EVM e gerenciamento de chaves de API, em quatro operações. Duas credenciais estão envolvidas, e elas não são intercambiáveis: 1. **Token de sessão.** Você o obtém assinando uma mensagem fixa com sua carteira EVM (EIP-191 `personal_sign`). É um token `Bearer`, dura **24 horas** e autentica **apenas** os endpoints `/keys`. Você não consegue negociar com ele. 2. **Chave de API.** Um par `key_id` + `secret` emitido com o token de sessão. Você assina cada requisição de negociação e de conta com o segredo, usando HMAC-SHA256. O segredo é retornado **uma vez** na criação e nunca é armazenado nem mostrado de novo. ``` POST /auth/login (wallet signature) → session Bearer token POST /keys (Bearer) → key_id + secret sign each request (HMAC over canonical str) → trade ``` Para assinatura delegada que evita expor sua carteira principal, veja [Agentes](/api-reference/pt-br/guides/agent-keys.md). URL base de todos os exemplos abaixo: `https://api.testnet.nexus.xyz/v1`, a base da testnet pública. *** ## `POST /auth/login` Entrar com carteira EVM. Envie uma assinatura EIP-191 `personal_sign` para receber um token de sessão. Use o token de sessão para criar e gerenciar chaves de API pelos endpoints `/keys`. Para negociar, use chaves de API HMAC. Os tokens de sessão expiram após 24 horas. **Autenticação:** nenhuma. A requisição se autentica com a assinatura da carteira que carrega. ### Corpo da requisição `LoginRequest`, `application/json`, obrigatório. | Campo | Tipo | Obrigatório | Descrição | | ----------- | ------ | ----------- | ----------------------------------------------------- | | `message` | string | Sim | Deve ser exatamente: `Sign in to Nexus Exchange` | | `signature` | string | Sim | Hex da EIP-191 `personal_sign` (prefixo 0x, 65 bytes) | A mensagem é uma string fixa, não um desafio com nonce, e não existe uma chamada separada para "solicitar um desafio". O servidor *recupera* o endereço da sua carteira a partir da assinatura, então você não o envia. ### Respostas #### `200` Sessão criada. `LoginResponse`. | Campo | Tipo | Descrição | | --------- | ------ | -------------------------------------------------------------------------------------- | | `token` | string | Token de sessão (hex de 64 caracteres). Use como token `Bearer` nos endpoints `/keys`. | | `address` | string | Endereço Ethereum recuperado (prefixo 0x) | #### `401` Falha na verificação da assinatura. ### Exemplo ```bash curl -X POST 'https://api.testnet.nexus.xyz/v1/auth/login' \ -H 'Content-Type: application/json' \ -d '{ "message": "Sign in to Nexus Exchange", "signature": "0x1234...abcd" }' ``` Resposta: ```json { "token": "a1b2c3d4e5f6...", "address": "0xAbCdEf0123456789..." } ``` *** ## `POST /keys` Criar uma chave de API. Cria uma nova chave de API HMAC para a carteira autenticada. Retorna o segredo uma vez. Ele nunca é armazenado nem mostrado de novo. Exige um token de sessão (Bearer) de `POST /auth/login`. **Autenticação:** `bearerAuth` (token de sessão). ### Corpo da requisição Opcional. [`CreateKeyRequest`](https://docs.nexus.xyz/api-reference/guides/schemas#createkeyrequest). Um corpo ausente ou vazio equivale a `{}`. | Campo | Tipo | Descrição | | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `label` | string | Rótulo fornecido por quem chama para esta chave, devolvido em `GET /keys`. | | `ttl_ms` | integer | Quanto tempo a chave deve durar, em milissegundos a partir da criação. Omita para uma chave que nunca expira. Deve ficar em `[24h, 90d]` (86400000–7776000000 ms), ou a requisição é recusada. | ### Respostas #### `200` Chave criada. [`CreateKeyResponse`](https://docs.nexus.xyz/api-reference/guides/schemas#createkeyresponse). | Campo | Tipo | Descrição | | --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `key_id` | string | O identificador da chave. Envie-o como `X-API-Key` nas requisições assinadas. | | `secret` | string | O segredo HMAC, em hex. **Retornado uma vez.** Guarde-o imediatamente. Não há como recuperá-lo. | | `expires_at_ms` | integer ou null | Unix ms a partir do qual esta chave deixa de autenticar, ou `null` se ela nunca expira. É o valor resolvido de `ttl_ms`. **Anulável, não opcional:** sempre presente. Hoje, apenas implantações com Postgres o aplicam. Uma chave criada em uma implantação sem Postgres aceita um `ttl_ms`, mas ainda não recusa uma chave expirada. | #### `400` Requisição inválida: | `code` | Significado | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ttl_ms_invalid` | `ttl_ms` está presente, mas não é um inteiro não negativo, ou o próprio corpo da requisição não pôde ser lido (acima do limite de 8KB, ou JSON inválido). | | `ttl_out_of_range` | Um `ttl_ms` bem formado fica fora de `[24h, 90d]`. | #### `401` Token de sessão válido necessário. ### Exemplo ```bash curl -X POST 'https://api.testnet.nexus.xyz/v1/keys' \ -H 'Authorization: Bearer a1b2c3d4e5f6...' \ -H 'Content-Type: application/json' \ -d '{"label": "my trading bot", "ttl_ms": 2592000000}' ``` Resposta: ```json { "key_id": "nx_a1b2c3d4e5f67890", "secret": "deadbeef...", "expires_at_ms": 1735689600000 } ``` Chaves novas recebem o nível **Pro** por padrão. Um operador atribui níveis com [`PUT /admin/tiers`](https://docs.nexus.xyz/api-reference/admin/set-tier), e toda resposta informa os tetos por nível nos cabeçalhos `X-RateLimit-*`. *** ## `GET /keys` Listar suas chaves de API. Retorna os IDs e os níveis de todas as chaves pertencentes à carteira autenticada. Os segredos não são incluídos. **Autenticação:** `bearerAuth` (token de sessão). ### Respostas #### `200` As chaves de API da sessão. Um array simples. O contrato dá um exemplo, mas nenhum schema nomeado. | Campo | Tipo | Descrição | | -------- | ------ | ---------------------------------------------------------------------------------------- | | `key_id` | string | O identificador da chave | | `tier` | string | Nível de limite de requisições atribuído a esta chave, por exemplo `Pro`, `Market Maker` | #### `401` Token de sessão válido necessário. ### Exemplo ```bash curl 'https://api.testnet.nexus.xyz/v1/keys' \ -H 'Authorization: Bearer a1b2c3d4e5f6...' ``` Resposta: ```json [ { "key_id": "nx_a1b2c3d4e5f67890", "tier": "Pro" } ] ``` *** ## `DELETE /keys/{key_id}` Excluir uma chave de API. Exclui uma chave que pertence a você. Não é possível excluir chaves de outras carteiras. **Autenticação:** `bearerAuth` (token de sessão). ### Parâmetros | Nome | Em | Tipo | Obrigatório | Descrição | | -------- | ---- | ------ | ----------- | ---------------------------------- | | `key_id` | path | string | Sim | O identificador da chave a excluir | ### Respostas #### `200` Chave excluída. #### `401` Token de sessão válido necessário. #### `404` Chave não encontrada ou não pertence a você. Falhas de propriedade retornam `404`, não `403`, então você não consegue sondar os IDs de chave de outras carteiras. ### Exemplo ```bash curl -X DELETE 'https://api.testnet.nexus.xyz/v1/keys/nx_a1b2c3d4e5f67890' \ -H 'Authorization: Bearer a1b2c3d4e5f6...' ``` *** ## Assinando uma requisição com a chave Depois que você tem um `key_id` e um `secret`, toda operação `hmacAuth` precisa de três cabeçalhos: | Cabeçalho | Valor | | ------------- | ---------------------------------------------------- | | `X-API-Key` | O ID da sua chave, por exemplo `nx_a1b2c3d4e5f67890` | | `X-Timestamp` | Hora atual em **milissegundos** Unix | | `X-Signature` | `hex(hmac_sha256(secret, canonical))` | A string canônica tem cinco campos separados por quebra de linha: ``` \n\n\n\n ``` * `path` é o caminho **como está escrito no contrato**, *não* o caminho completo da URL que você chamou. O prefixo de transporte `/v1` é removido antes de a requisição chegar ao serviço que verifica sua assinatura, portanto ele **não** deve ser assinado. Inclua o prefixo `/api/v1` ao chamar um caminho versionado, porque essa parte é repassada. | Você chama | Você assina | | ---------------------------------------------- | ----------------- | | `https://api.testnet.nexus.xyz/v1/markets` | `/markets` | | `https://api.testnet.nexus.xyz/api/v1/tickers` | `/api/v1/tickers` | Assinar o prefixo de transporte `/v1` é a segunda causa mais comum de um `401` opaco, depois do desvio de relógio. * `query` é a query string bruta, vazia quando não há nenhuma. * Para requisições sem corpo, calcule o hash da string vazia. * O timestamp deve estar a no máximo **30 segundos** da hora do servidor. Um relógio desajustado é a causa mais comum de um `401` opaco. Os cabeçalhos consultivos `X-Nexus-Api-Version` e `User-Agent` são **excluídos** da string canônica. ```bash TIMESTAMP=$(python3 -c 'import time; print(int(time.time()*1000))') BODY_HASH=$(printf '' | shasum -a 256 | cut -d' ' -f1) CANONICAL="$TIMESTAMP\nGET\n/markets\n\n$BODY_HASH" SIGNATURE=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -mac HMAC \ -macopt "hexkey:$NEXUS_API_SECRET" -hex | awk '{print $NF}') curl 'https://api.testnet.nexus.xyz/v1/markets' \ -H "X-API-Key: nx_a1b2c3d4e5f67890" \ -H "X-Timestamp: $TIMESTAMP" \ -H "X-Signature: $SIGNATURE" ``` Todas as respostas `401` retornam o mesmo corpo opaco, `{"code":"unauthorized"}`, então a resposta não diz se o problema foi a chave, a assinatura ou o relógio. Verifique primeiro o desvio de relógio, depois a string canônica e, por fim, a chave. > **Status:** prévia na testnet. Credenciais, sessões e o estado dos limites de requisições ainda não sobrevivem a reinicializações do gateway, então trate as chaves de API como recriáveis. --- # 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/authentication.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.