> 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/zh-cn/guides/agent-keys.md).

# 代理密钥

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

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

**本部分的任何操作都不需要会话令牌**。请求体中的 **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**

```json
{
  "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` 读取（参见[网络](/api-reference/zh-cn/guides/networks.md#what-a-network-carries)）。签名前请确认目标网关期望的值，因为签名域不匹配只会返回 `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`。该代理地址已注册到此钱包。

### 示例

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

响应：

```json
{
  "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 身份验证。

### 示例

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

响应：

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

关于如何构造 `X-Timestamp` 和 `X-Signature`，请参见[身份验证](/api-reference/zh-cn/guides/authentication.md#signing-a-request-with-the-key)。

***

## `DELETE /agents/{address}`

撤销代理。

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

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

### 参数

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

### 响应

#### `200`

代理已撤销。

#### `401`

需要 HMAC 身份验证。

#### `404`

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

### 示例

```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"
```

***

## 运维说明

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

> **状态**：测试网预览版。代理注册目前还无法在网关重启后保留，因此请将其视为可重新创建的，与 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/zh-cn/guides/agent-keys.md?ask=<question>&goal=<endgoal>
```

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