Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

{
  "name": "Nexus Exchange",
  "version": "1",
  "chainId": "<testnet chain id>",
  "salt": "<network salt, see below>"
}

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 <testnet chain id> 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). 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(<network>), donde <network> 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: <testnet chain id>, salt: <network 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

Respuesta:

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

Respuesta:

Consulta Autenticación 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

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.

AnteriorAutenticación
SiguienteLímites de solicitudes

Última actualización