Autenticação

Duas credenciais estão envolvidas, e elas não são intercambiáveis:

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

URL base de todos os exemplos abaixo: https://api.testnet.nexus.xyz/v1, a base da testnet pública.

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

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:

{
  "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. 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.

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

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:

{
  "key_id": "nx_a1b2c3d4e5f67890",
  "secret": "deadbeef...",
  "expires_at_ms": 1735689600000
}

Chaves novas recebem o nível Pro por padrão. Um operador da Nexus atribui os demais níveis, 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

curl 'https://api.testnet.nexus.xyz/v1/keys' \
  -H 'Authorization: Bearer a1b2c3d4e5f6...'

Resposta:

[
  {
    "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

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

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:

<timestamp>\n<METHOD>\n<path>\n<query>\n<sha256_hex(body)>

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.

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.

AnteriorSDKs e ferramentas

PróximoChaves de agente

Atualizado há 3 dias