> 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/agent-keys.md). # Chaves de agente Registro e gerenciamento de chaves de agente, em três operações. Um **agente** é um par de chaves derivado de Ethereum que pode assinar requisições de negociação em seu nome sem expor sua carteira principal. Você registra o endereço do agente uma vez, autorizado por uma assinatura da carteira proprietária. A partir daí, a chave de agente carrega a autoridade de negociação, e a chave da carteira fica offline. **Nenhuma operação desta seção exige token de sessão.** Uma assinatura **EIP-712** no corpo da requisição autoriza o registro dentro da própria requisição, então ele não precisa de nenhuma credencial. As duas operações de gerenciamento (`GET /agents`, `DELETE /agents/{address}`) se autenticam com sua chave de API HMAC. | Operação | Autorização | | -------------------------- | --------------------------------------------------------------------------------- | | `POST /agents/register` | Assinatura EIP-712 no corpo da requisição. Sem token de sessão, sem chave de API. | | `GET /agents` | `hmacAuth` | | `DELETE /agents/{address}` | `hmacAuth` | URL base de todos os exemplos abaixo: `https://api.testnet.nexus.xyz/v1`, a base da testnet pública. ## O payload EIP-712 Uma assinatura de dados tipados da carteira que será proprietária do agente autoriza o registro. **Domínio** ```json { "name": "Nexus Exchange", "version": "1", "chainId": "", "salt": "" } ``` **Tipo** ``` RegisterAgent { address agent uint64 expiresAt uint64 nonce } ``` Detalhes que importam: * A assinatura cobre **três** campos: `agent`, `expiresAt` e `nonce`. A `wallet` proprietária **não** faz parte dos dados tipados. Você a envia junto no corpo da requisição, e o servidor verifica se o signatário recuperado corresponde a ela. * Os nomes de campo dos dados tipados são **camelCase** (`expiresAt`), enquanto o corpo JSON da requisição usa **snake\_case** (`expires_at`). Assine os nomes em camelCase; envie os em snake\_case. * Se você deixar `expires_at` ficar com o padrão do servidor, não terá nada para assinar. Calcule a expiração você mesmo, assine-a e envie-a explicitamente. * O contrato escreve o `chainId` do domínio como o placeholder `` e não fixa um valor. A implantação é a autoridade sobre seu ID da rede: leia-o do próprio `GET /metadata` daquele gateway (veja [Redes](/api-reference/pt-br/guides/networks.md#what-a-network-carries)). Confirme o valor que o gateway de destino espera antes de assinar, pois um domínio divergente produz `signer_mismatch`, não um erro descritivo. * O domínio também carrega um `salt`: `keccak256()`, em que `` é o nome da implantação em minúsculas (`"mainnet"`, `"testnet"` ou `"local"`) do gateway para o qual você está assinando. Isso restringe uma assinatura `RegisterAgent` a uma implantação. A mesma assinatura não é válida em outra rede, mesmo que o `chainId` coincida. Consulte o valor do salt para a implantação de destino em vez de recalculá-lo, pois um `salt` errado produz `signer_mismatch` sem nenhum outro sinal. *** ## `POST /agents/register` Registrar uma chave de agente. Registre uma nova chave de agente para sua carteira. Um agente é um par de chaves derivado de Ethereum que pode assinar requisições de negociação em seu nome sem expor sua carteira principal. Uma assinatura EIP-712 da carteira que será proprietária do agente autoriza o registro. Nenhum token de sessão é necessário. Domínio EIP-712: `{ name: 'Nexus Exchange', version: '1', chainId: , salt: }`. Tipo dos dados tipados: `RegisterAgent { address agent, uint64 expiresAt, uint64 nonce }`. **Autenticação:** nenhuma. A requisição se autoriza com a assinatura EIP-712 que carrega. ### Corpo da requisição `AgentRegistrationRequest`, `application/json`, obrigatório. | Campo | Tipo | Obrigatório | Descrição | | ------------ | --------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | | `wallet` | string | Sim | Endereço da carteira proprietária (prefixo 0x, 20 bytes) | | `agent` | string | Sim | Endereço Ethereum do agente (prefixo 0x, 20 bytes) derivado do par de chaves do agente | | `expires_at` | integer (int64) | Não | Expiração em Unix ms. Opcional, padrão agora+30 d. Deve estar em `[now+1d, now+90d]`. | | `nonce` | integer (int64) | Sim | Nonce monotônico. Use o timestamp Unix atual em ms como valor inicial seguro. | | `signature` | string | Sim | Assinatura EIP-712 sobre `RegisterAgent{agent, expiresAt, nonce}` feita com a chave privada da carteira (prefixo 0x) | | `label` | string | Não | Rótulo opcional legível por humanos para o agente (por exemplo, `my-bot`) | ### Respostas #### `200` Agente registrado. O contrato dá um exemplo para esta resposta, mas nenhum schema nomeado. | Campo | Tipo | Descrição | | --------------- | --------------- | --------------------------------------------------------------------------------------------- | | `agent_address` | string | O endereço do agente registrado (prefixo 0x) | | `expires_at` | integer (int64) | Expiração efetiva, Unix ms. O valor que você enviou, ou o padrão do servidor se você o omitiu | #### `400` Requisição inválida: `bad_wallet`, `bad_agent`, `expiry_out_of_range` (`[1 d, 90 d]` a partir de agora) ou `invalid_json`. #### `401` `signature_invalid` ou `signer_mismatch`. A assinatura EIP-712 não recuperou a carteira declarada. #### `409` `duplicate_agent`. O endereço do agente já está registrado para esta carteira. ### Exemplo ```bash curl -X POST 'https://api.testnet.nexus.xyz/v1/agents/register' \ -H 'Content-Type: application/json' \ -d '{ "wallet": "0xAbCdEf0123456789AbCdEf0123456789AbCdEf01", "agent": "0x1234567890AbCdEf1234567890AbCdEf12345678", "expires_at": 1782000000000, "nonce": 1, "signature": "0xdeadbeef..." }' ``` Resposta: ```json { "agent_address": "0x1234567890AbCdEf1234567890AbCdEf12345678", "expires_at": 1782000000000 } ``` *** ## `GET /agents` Listar seus agentes. Retorna todas as chaves de agente não expiradas registradas para a carteira autenticada. O servidor filtra os agentes expirados, então um agente que some desta lista chegou ao fim do seu ciclo de vida. Isso não é um erro. **Autenticação:** `hmacAuth` (chave de API HMAC). ### Respostas #### `200` Array de registros de agente. Os itens são `AgentInfo`. | Campo | Tipo | Descrição | | -------------- | --------------- | ------------------------------- | | `address` | string | Endereço do agente (prefixo 0x) | | `expiresAt` | integer (int64) | Expiração, Unix ms | | `registeredAt` | integer (int64) | Momento do registro, Unix ms | | `label` | string \| null | Rótulo opcional | Aqui os nomes de campo da resposta são **camelCase**, ao contrário do corpo da requisição de registro em snake\_case. #### `401` Autenticação HMAC necessária. ### Exemplo ```bash curl 'https://api.testnet.nexus.xyz/v1/agents' \ -H "X-API-Key: nx_a1b2c3d4e5f67890" \ -H "X-Timestamp: $TIMESTAMP" \ -H "X-Signature: $SIGNATURE" ``` Resposta: ```json [ { "address": "0x1234567890AbCdEf1234567890AbCdEf12345678", "expiresAt": 1782000000000, "registeredAt": 1779000000000, "label": "my-bot" } ] ``` Veja [Autenticação](/api-reference/pt-br/guides/authentication.md#signing-a-request-with-the-key) para saber como montar `X-Timestamp` e `X-Signature`. *** ## `DELETE /agents/{address}` Revogar um agente. Revoga imediatamente uma chave de agente. Depois que esta chamada retorna, o servidor rejeita qualquer requisição em andamento assinada pelo agente revogado. **Autenticação:** `hmacAuth` (chave de API HMAC). ### Parâmetros | Nome | Em | Tipo | Obrigatório | Descrição | | --------- | ---- | ------ | ----------- | ----------------------------------------- | | `address` | path | string | Sim | Endereço do agente a revogar (prefixo 0x) | ### Respostas #### `200` Agente revogado. #### `401` Autenticação HMAC necessária. #### `404` Agente não encontrado ou não pertence a você. Falhas de propriedade retornam `404`, não `403`, então você não consegue sondar os agentes de outras carteiras. ### Exemplo ```bash curl -X DELETE 'https://api.testnet.nexus.xyz/v1/agents/0x1234567890AbCdEf1234567890AbCdEf12345678' \ -H "X-API-Key: nx_a1b2c3d4e5f67890" \ -H "X-Timestamp: $TIMESTAMP" \ -H "X-Signature: $SIGNATURE" ``` *** ## Notas de operação * **A expiração é limitada.** Um agente precisa expirar entre 1 e 90 dias após o registro, e omitir `expires_at` dá 30 dias. Não existe operação de renovação até a spec 0.9.90, então registre um novo agente antes que o antigo expire. * **Os nonces são monotônicos por carteira.** Usar o timestamp Unix atual em milissegundos como nonce satisfaz essa ordem sem precisar guardar estado. * **A revogação é imediata** e se aplica a requisições em andamento. O servidor rejeita uma requisição assinada por um agente revogado assim que o `DELETE` retorna. * **O registro não é autenticado na camada de transporte.** Qualquer pessoa pode enviar um registro, mas o servidor só aceita uma assinatura EIP-712 válida da carteira declarada. Proteja a chave da carteira, porque uma assinatura sobre `RegisterAgent` concede autoridade de negociação por até 90 dias. > **Status:** prévia na testnet. Os registros de agente ainda não sobrevivem a reinicializações do gateway, então trate-os como recriáveis, assim como as chaves de API. --- # 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/agent-keys.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.