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

# Agent Keys

Agent key registration and management. Three operations.

An **agent** is an Ethereum-derived keypair that can sign trading requests on your behalf without exposing your main wallet. You register the agent's address once, authorized by a signature from the owning wallet, and from then on the agent key carries the trading authority — while the wallet key stays offline.

**No session token is required for any operation in this section.** Registration is authorized in-band by an **EIP-712** signature in the request body, so it needs no credential at all. The two management operations (`GET /agents`, `DELETE /agents/{address}`) authenticate with your HMAC API key.

| Operation                  | Authorization                                                        |
| -------------------------- | -------------------------------------------------------------------- |
| `POST /agents/register`    | EIP-712 signature in the request body. No session token, no API key. |
| `GET /agents`              | `hmacAuth`                                                           |
| `DELETE /agents/{address}` | `hmacAuth`                                                           |

Base URL for every example below: `https://exchange.nexus.xyz/api/exchange`.

## The EIP-712 payload

Registration is authorized by a typed-data signature from the wallet that will own the agent.

**Domain**

```json
{
  "name": "Nexus Exchange",
  "version": "1",
  "chainId": "<testnet chain id>"
}
```

**Type**

```
RegisterAgent {
  address agent
  uint64  expiresAt
  uint64  nonce
}
```

Notes on getting this right:

* The signature covers **three** fields — `agent`, `expiresAt`, `nonce`. The owning `wallet` is **not** part of the typed data; it is sent alongside in the request body and the server checks that the recovered signer matches it.
* The typed-data field names are **camelCase** (`expiresAt`), while the JSON request body uses **snake\_case** (`expires_at`). Sign the camelCase names; send the snake\_case ones.
* If you let `expires_at` default server-side, you have nothing to sign. Compute the expiry yourself, sign it, and send it explicitly.
* The contract writes the domain's `chainId` as the placeholder `<testnet chain id>` and does not pin a value. Published Nexus chain IDs are listed under [Developer Environment Setup](https://docs.nexus.xyz/network/building-on-nexus/developer-environment-setup); confirm the value your target gateway expects before signing, since a domain mismatch produces `signer_mismatch`, not a descriptive error.

***

## `POST /agents/register`

Register an agent key.

Register a new agent key for your wallet. An agent is an Ethereum-derived keypair that can sign trading requests on your behalf without exposing your main wallet. The registration is authorized by an EIP-712 signature from the wallet that will own the agent — no session token required.

EIP-712 domain: `{ name: 'Nexus Exchange', version: '1', chainId: <testnet chain id> }`. Typed data type: `RegisterAgent { address agent, uint64 expiresAt, uint64 nonce }`.

**Authentication:** None — the request authorizes itself with the EIP-712 signature it carries.

### Request body

`AgentRegistrationRequest` — `application/json`, required.

| Field        | Type            | Required | Description                                                                                               |
| ------------ | --------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `wallet`     | string          | Yes      | Owner wallet address (0x-prefixed, 20 bytes)                                                              |
| `agent`      | string          | Yes      | Agent Ethereum address (0x-prefixed, 20 bytes) derived from the agent keypair                             |
| `expires_at` | integer (int64) | No       | Expiry as Unix ms. Optional — defaults to now+30 d. Must be in `[now+1d, now+90d]`.                       |
| `nonce`      | integer (int64) | Yes      | Monotonic nonce. Use the current Unix timestamp in ms as a safe starting value.                           |
| `signature`  | string          | Yes      | EIP-712 signature over `RegisterAgent{agent, expiresAt, nonce}` from the wallet private key (0x-prefixed) |
| `label`      | string          | No       | Optional human-readable label for the agent (e.g. `my-bot`)                                               |

### Responses

#### `200`

Agent registered. The contract gives this response an example but no named schema.

| Field           | Type            | Description                                                                             |
| --------------- | --------------- | --------------------------------------------------------------------------------------- |
| `agent_address` | string          | The registered agent address (0x-prefixed)                                              |
| `expires_at`    | integer (int64) | Effective expiry, Unix ms — the value you sent, or the server default if you omitted it |

#### `400`

Bad request: `bad_wallet`, `bad_agent`, `expiry_out_of_range` (`[1 d, 90 d]` from now), or `invalid_json`.

#### `401`

`signature_invalid` or `signer_mismatch` — the EIP-712 signature did not recover to the claimed wallet.

#### `409`

`duplicate_agent` — the agent address is already registered to this wallet.

### Example

```bash
curl -X POST 'https://exchange.nexus.xyz/api/exchange/agents/register' \
  -H 'Content-Type: application/json' \
  -d '{
    "wallet": "0xAbCdEf0123456789AbCdEf0123456789AbCdEf01",
    "agent": "0x1234567890AbCdEf1234567890AbCdEf12345678",
    "expires_at": 1782000000000,
    "nonce": 1,
    "signature": "0xdeadbeef..."
  }'
```

Response:

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

***

## `GET /agents`

List your agents.

Returns all non-expired agent keys registered to the authenticated wallet. Expired agents are filtered out server-side, so an agent disappearing from this list is the expected end of its lifecycle, not an error.

**Authentication:** `hmacAuth` — HMAC API key.

### Responses

#### `200`

Array of agent records. Items are `AgentInfo`.

| Field          | Type            | Description                 |
| -------------- | --------------- | --------------------------- |
| `address`      | string          | Agent address (0x-prefixed) |
| `expiresAt`    | integer (int64) | Expiry, Unix ms             |
| `registeredAt` | integer (int64) | Registration time, Unix ms  |
| `label`        | string \| null  | Optional label              |

Response field names are **camelCase** here, unlike the snake\_case registration request body.

#### `401`

HMAC authentication required.

### Example

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

Response:

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

See [Authentication](/api-reference/guides/authentication.md#signing-a-request-with-the-key) for how to build `X-Timestamp` and `X-Signature`.

***

## `DELETE /agents/{address}`

Revoke an agent.

Immediately revoke an agent key. Any in-flight requests signed by the revoked agent will be rejected after this call returns.

**Authentication:** `hmacAuth` — HMAC API key.

### Parameters

| Name      | In   | Type   | Required | Description                           |
| --------- | ---- | ------ | -------- | ------------------------------------- |
| `address` | path | string | Yes      | Agent address to revoke (0x-prefixed) |

### Responses

#### `200`

Agent revoked.

#### `401`

HMAC authentication required.

#### `404`

Agent not found or not owned by you. Ownership failures are reported as `404`, not `403` — you cannot probe for other wallets' agents.

### Example

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

***

## Operating notes

* **Expiry is bounded.** An agent must expire between 1 and 90 days from registration; omitting `expires_at` gives you 30 days. There is no renewal operation in version 0.9.27 — re-register a fresh agent before the old one lapses.
* **Nonces are monotonic per wallet.** Using the current Unix millisecond timestamp as the nonce satisfies that ordering without tracking state.
* **Revocation is immediate**, and it applies to in-flight requests: a request signed by a revoked agent is rejected once the `DELETE` returns.
* **Registration is unauthenticated at the transport layer.** Anyone can submit a registration; only a valid EIP-712 signature from the claimed wallet is accepted. Guard the wallet key accordingly — a signature over `RegisterAgent` grants trading authority for up to 90 days.

> **Status:** testnet preview. Agent registrations are not yet durable across gateway restarts — treat them as re-creatable alongside API keys.


---

# 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/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.