> 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/es-419/guides/agent-keys.md). # Claves de agente Registro y administración de claves de agente, en tres operaciones. Un **agente** es un par de claves derivado de Ethereum que puede firmar solicitudes de trading en tu nombre sin exponer tu billetera principal. Registras la dirección del agente una vez, con la autorización de una firma de la billetera propietaria. A partir de ahí, la clave de agente tiene la autoridad para operar, y la clave de la billetera queda fuera de línea. **Ninguna operación de esta sección requiere token de sesión.** Una firma **EIP-712** en el cuerpo de la solicitud autoriza el registro dentro de la propia solicitud, así que no necesita ninguna credencial. Las dos operaciones de administración (`GET /agents`, `DELETE /agents/{address}`) se autentican con tu clave de API HMAC. | Operación | Autorización | | -------------------------- | -------------------------------------------------------------------------------- | | `POST /agents/register` | Firma EIP-712 en el cuerpo de la solicitud. Sin token de sesión ni clave de API. | | `GET /agents` | `hmacAuth` | | `DELETE /agents/{address}` | `hmacAuth` | URL base de todos los ejemplos de abajo: `https://api.testnet.nexus.xyz/v1`, la base pública de testnet. ## El payload EIP-712 Una firma de datos tipados de la billetera que será propietaria del agente autoriza el registro. **Dominio** ```json { "name": "Nexus Exchange", "version": "1", "chainId": "", "salt": "" } ``` **Tipo** ``` RegisterAgent { address agent uint64 expiresAt uint64 nonce } ``` Detalles que importan: * La firma cubre **tres** campos: `agent`, `expiresAt` y `nonce`. La `wallet` propietaria **no** forma parte de los datos tipados. La envías aparte en el cuerpo de la solicitud, y el servidor verifica que el firmante recuperado coincida con ella. * Los nombres de los campos de los datos tipados están en **camelCase** (`expiresAt`), mientras que el cuerpo JSON de la solicitud usa **snake\_case** (`expires_at`). Firma los nombres en camelCase; envía los de snake\_case. * Si dejas que el servidor asigne el valor predeterminado de `expires_at`, no tienes nada que firmar. Calcula tú mismo el vencimiento, fírmalo y envíalo de forma explícita. * El contrato escribe el `chainId` del dominio como el marcador `` y no fija un valor. El despliegue es la fuente de referencia de su chain id: léelo del propio `GET /metadata` de ese gateway (consulta [Redes](/api-reference/es-419/guides/networks.md#what-a-network-carries)). Confirma el valor que espera tu gateway de destino antes de firmar, ya que un dominio que no coincide produce `signer_mismatch`, no un error descriptivo. * El dominio también lleva un `salt`: `keccak256()`, donde `` es el nombre del despliegue en minúsculas (`"mainnet"`, `"testnet"` o `"local"`) del gateway para el que firmas. Esto limita una firma `RegisterAgent` a un solo despliegue. La misma firma no es válida en otra red aunque el `chainId` coincidiera. Consulta el valor del salt para tu despliegue de destino en lugar de recalcularlo, ya que un `salt` incorrecto produce `signer_mismatch` sin ninguna otra señal. *** ## `POST /agents/register` Registrar una clave de agente. Registra una nueva clave de agente para tu billetera. Un agente es un par de claves derivado de Ethereum que puede firmar solicitudes de trading en tu nombre sin exponer tu billetera principal. Una firma EIP-712 de la billetera que será propietaria del agente autoriza el registro. No se requiere token de sesión. Dominio EIP-712: `{ name: 'Nexus Exchange', version: '1', chainId: , salt: }`. Tipo de los datos tipados: `RegisterAgent { address agent, uint64 expiresAt, uint64 nonce }`. **Autenticación:** ninguna. La solicitud se autoriza a sí misma con la firma EIP-712 que lleva. ### Cuerpo de la solicitud `AgentRegistrationRequest`, `application/json`, obligatorio. | Campo | Tipo | Obligatorio | Descripción | | ------------ | --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | | `wallet` | string | Sí | Dirección de la billetera propietaria (con prefijo 0x, 20 bytes) | | `agent` | string | Sí | Dirección de Ethereum del agente (con prefijo 0x, 20 bytes) derivada del par de claves del agente | | `expires_at` | integer (int64) | No | Vencimiento en ms Unix. Opcional, el valor predeterminado es ahora+30 d. Debe estar en `[now+1d, now+90d]`. | | `nonce` | integer (int64) | Sí | Nonce monotónico. Usa la marca de tiempo Unix actual en ms como valor inicial seguro. | | `signature` | string | Sí | Firma EIP-712 sobre `RegisterAgent{agent, expiresAt, nonce}` con la clave privada de la billetera (con prefijo 0x) | | `label` | string | No | Etiqueta opcional legible por humanos para el agente (p. ej. `my-bot`) | ### Respuestas #### `200` Agente registrado. El contrato da un ejemplo para esta respuesta, pero ningún esquema con nombre. | Campo | Tipo | Descripción | | --------------- | --------------- | -------------------------------------------------------------------------------------------------------- | | `agent_address` | string | La dirección del agente registrado (con prefijo 0x) | | `expires_at` | integer (int64) | Vencimiento efectivo, en ms Unix. El valor que enviaste, o el predeterminado del servidor si lo omitiste | #### `400` Solicitud incorrecta: `bad_wallet`, `bad_agent`, `expiry_out_of_range` (`[1 d, 90 d]` desde ahora) o `invalid_json`. #### `401` `signature_invalid` o `signer_mismatch`. El firmante recuperado de la firma EIP-712 no corresponde a la billetera indicada. #### `409` `duplicate_agent`. La dirección del agente ya está registrada para esta billetera. ### Ejemplo ```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..." }' ``` Respuesta: ```json { "agent_address": "0x1234567890AbCdEf1234567890AbCdEf12345678", "expires_at": 1782000000000 } ``` *** ## `GET /agents` Listar tus agentes. Devuelve todas las claves de agente no vencidas registradas para la billetera autenticada. El servidor filtra los agentes vencidos, así que un agente que desaparece de esta lista llegó al final de su ciclo de vida. No es un error. **Autenticación:** `hmacAuth` (clave de API HMAC). ### Respuestas #### `200` Arreglo de registros de agentes. Los elementos son `AgentInfo`. | Campo | Tipo | Descripción | | -------------- | --------------- | ------------------------------------- | | `address` | string | Dirección del agente (con prefijo 0x) | | `expiresAt` | integer (int64) | Vencimiento, en ms Unix | | `registeredAt` | integer (int64) | Hora de registro, en ms Unix | | `label` | string \| null | Etiqueta opcional | Aquí los nombres de los campos de la respuesta están en **camelCase**, a diferencia del cuerpo de la solicitud de registro en snake\_case. #### `401` Se requiere autenticación HMAC. ### Ejemplo ```bash curl 'https://api.testnet.nexus.xyz/v1/agents' \ -H "X-API-Key: nx_a1b2c3d4e5f67890" \ -H "X-Timestamp: $TIMESTAMP" \ -H "X-Signature: $SIGNATURE" ``` Respuesta: ```json [ { "address": "0x1234567890AbCdEf1234567890AbCdEf12345678", "expiresAt": 1782000000000, "registeredAt": 1779000000000, "label": "my-bot" } ] ``` Consulta [Autenticación](/api-reference/es-419/guides/authentication.md#signing-a-request-with-the-key) para ver cómo construir `X-Timestamp` y `X-Signature`. *** ## `DELETE /agents/{address}` Revocar un agente. Revoca de inmediato una clave de agente. Una vez que esta llamada responde, el servidor rechaza cualquier solicitud en curso firmada por el agente revocado. **Autenticación:** `hmacAuth` (clave de API HMAC). ### Parámetros | Nombre | En | Tipo | Obligatorio | Descripción | | --------- | ---- | ------ | ----------- | ----------------------------------------------------- | | `address` | path | string | Sí | Dirección del agente que se revocará (con prefijo 0x) | ### Respuestas #### `200` Agente revocado. #### `401` Se requiere autenticación HMAC. #### `404` Agente no encontrado o que no te pertenece. Las fallas de propiedad devuelven `404`, no `403`, para que no puedas sondear los agentes de otras billeteras. ### Ejemplo ```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 operativas * **El vencimiento está acotado.** Un agente debe vencer entre 1 y 90 días después del registro, y omitir `expires_at` te da 30 días. No hay una operación de renovación a la fecha de la especificación 0.9.90, así que vuelve a registrar un agente nuevo antes de que venza el anterior. * **Los nonces son monotónicos por billetera.** Usar como nonce la marca de tiempo Unix actual en milisegundos cumple ese orden sin tener que llevar un estado. * **La revocación es inmediata**, y se aplica a las solicitudes en curso. El servidor rechaza una solicitud firmada por un agente revocado una vez que el `DELETE` responde. * **El registro no está autenticado en la capa de transporte.** Cualquiera puede enviar un registro, pero el servidor solo acepta una firma EIP-712 válida de la billetera indicada. Protege la clave de la billetera, porque una firma sobre `RegisterAgent` otorga autoridad para operar durante hasta 90 días. > **Estado:** versión preliminar de testnet. Los registros de agentes todavía no sobreviven a los reinicios del gateway, así que trátalos como recreables, igual que las claves 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/es-419/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.