代理密钥

代理密钥的注册与管理，共三个操作。

代理是一个基于以太坊派生的密钥对，可以代表您对交易请求签名，而无需暴露您的主钱包。您只需注册一次代理的地址，并由所属钱包的签名授权。此后由代理密钥承担交易权限，钱包密钥则保持离线。

本部分的任何操作都不需要会话令牌。请求体中的 EIP-712 签名以带内方式授权注册，因此注册完全不需要凭证。两个管理操作（GET /agents、DELETE /agents/{address}）使用您的 HMAC API 密钥进行身份验证。

操作	授权方式
POST /agents/register	请求体中的 EIP-712 签名。无需会话令牌，也无需 API 密钥。
GET /agents	hmacAuth
DELETE /agents/{address}	hmacAuth

以下所有示例的基础 URL：https://api.testnet.nexus.xyz/v1，即公共测试网基础 URL。

EIP-712 载荷

由将拥有该代理的钱包生成的类型化数据签名来授权注册。

Domain

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

Type

RegisterAgent {
  address agent
  uint64  expiresAt
  uint64  nonce
}

需要注意的细节：

• 签名覆盖三个字段：agent、expiresAt 和 nonce。所属的 wallet 不属于类型化数据。您在请求体中另外发送它，服务器会检查恢复出的签名者是否与之匹配。
• 类型化数据的字段名使用 camelCase（expiresAt），而 JSON 请求体使用 snake_case（expires_at）。签名时用 camelCase 名称，发送时用 snake_case 名称。
• 如果让 expires_at 由服务器端取默认值，您就没有可签名的值。请自行计算过期时间，对其签名，并显式发送。
• 契约将签名域（domain）的 chainId 写作占位符 <testnet chain id>，并未固定取值。链 ID 以部署本身为准：请从该网关自己的 GET /metadata 读取（参见网络）。签名前请确认目标网关期望的值，因为签名域不匹配只会返回 signer_mismatch，而不是说明性的错误。
• 签名域还带有一个 salt：keccak256(<network>)，其中 <network> 是您签名所针对网关的小写部署名称（"mainnet"、"testnet" 或 "local"）。这会将 RegisterAgent 签名限定在一个部署上。即使 chainId 恰好相同，同一签名在其他网络上也无效。请查询目标部署的 salt 值，而不要自行重新计算，因为错误的 salt 只会返回 signer_mismatch，没有其他提示。

---

POST /agents/register

注册代理密钥。

为您的钱包注册一个新的代理密钥。代理是一个基于以太坊派生的密钥对，可以代表您对交易请求签名，而无需暴露您的主钱包。由将拥有该代理的钱包生成的 EIP-712 签名来授权注册。无需会话令牌。

EIP-712 签名域：{ name: 'Nexus Exchange', version: '1', chainId: <testnet chain id>, salt: <network salt> }。类型化数据类型：RegisterAgent { address agent, uint64 expiresAt, uint64 nonce }。

身份验证：无。请求通过其携带的 EIP-712 签名自行授权。

请求体

AgentRegistrationRequest，application/json，必填。

字段	类型	必填	说明
wallet	string	是	所属钱包地址（0x 前缀，20字节）
agent	string	是	从代理密钥对派生的代理以太坊地址（0x 前缀，20字节）
expires_at	integer (int64)	否	过期时间，Unix 毫秒。可选，默认为当前时间+30天。必须在 [now+1d, now+90d] 范围内。
nonce	integer (int64)	是	单调递增的 nonce。可以用当前 Unix 毫秒时间戳作为安全的起始值。
signature	string	是	用钱包私钥对 RegisterAgent{agent, expiresAt, nonce} 生成的 EIP-712 签名（0x 前缀）
label	string	否	可选的代理可读标签（例如 my-bot）

响应

200

代理已注册。契约为此响应提供了示例，但没有命名的 Schema。

字段	类型	说明
agent_address	string	已注册的代理地址（0x 前缀）
expires_at	integer (int64)	实际生效的过期时间，Unix 毫秒。即您发送的值，若您省略则为服务器默认值

400

错误请求：bad_wallet、bad_agent、expiry_out_of_range（从当前起 [1 d, 90 d]）或 invalid_json。

401

signature_invalid 或 signer_mismatch。EIP-712 签名未能恢复为所声明的钱包。

409

duplicate_agent。该代理地址已注册到此钱包。

示例

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..."
  }'

响应：

{
  "agent_address": "0x1234567890AbCdEf1234567890AbCdEf12345678",
  "expires_at": 1782000000000
}

---

GET /agents

列出您的代理。

返回注册到已认证钱包下的所有未过期代理密钥。服务器会过滤掉已过期的代理，因此从该列表中消失的代理已到达其生命周期终点。这不是错误。

身份验证：hmacAuth（HMAC API 密钥）。

响应

200

代理记录数组。数组元素为 AgentInfo。

字段	类型	说明
address	string	代理地址（0x 前缀）
expiresAt	integer (int64)	过期时间，Unix 毫秒
registeredAt	integer (int64)	注册时间，Unix 毫秒
label	string | null	可选标签

这里的响应字段名使用 camelCase，与使用 snake_case 的注册请求体不同。

401

需要 HMAC 身份验证。

示例

curl 'https://api.testnet.nexus.xyz/v1/agents' \
  -H "X-API-Key: nx_a1b2c3d4e5f67890" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE"

响应：

[
  {
    "address": "0x1234567890AbCdEf1234567890AbCdEf12345678",
    "expiresAt": 1782000000000,
    "registeredAt": 1779000000000,
    "label": "my-bot"
  }
]

关于如何构造 X-Timestamp 和 X-Signature，请参见身份验证。

---

DELETE /agents/{address}

撤销代理。

立即撤销一个代理密钥。此调用返回后，服务器会拒绝由已撤销代理签名的任何在途请求。

身份验证：hmacAuth（HMAC API 密钥）。

参数

名称	位置	类型	必填	说明
address	path	string	是	要撤销的代理地址（0x 前缀）

响应

200

代理已撤销。

401

需要 HMAC 身份验证。

404

未找到代理，或该代理不归您所有。所有权校验失败返回 404 而非 403，因此您无法借此探查其他钱包的代理。

示例

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"

---

运维说明

• 有效期有上下限。代理必须在注册后1到90天之间过期，省略 expires_at 则为30天。截至规范0.9.90，没有续期操作，因此请在旧代理失效前重新注册一个新代理。
• nonce 按钱包单调递增。使用当前 Unix 毫秒时间戳作为 nonce，无需跟踪状态即可满足该顺序要求。
• 撤销立即生效，并且适用于在途请求。DELETE 返回后，服务器会拒绝由已撤销代理签名的请求。
• 注册在传输层不做身份验证。任何人都可以提交注册，但服务器只接受来自所声明钱包的有效 EIP-712 签名。请保管好钱包密钥，因为对 RegisterAgent 的签名会授予最长90天的交易权限。

状态：测试网预览版。代理注册目前还无法在网关重启后保留，因此请将其视为可重新创建的，与 API 密钥一样。