# Agent Keys

An **Agent Key** is a separate ECDSA keypair that you authorize on-chain to sign trade requests on your behalf. It lets you run a bot, market maker, or any automation **without ever exposing your main private key**.

> **Agent Keys can trade. They cannot move funds, manage other Agents, or change account relationships.** Even if an Agent Key leaks, the worst case is loss bounded by trading risk — never theft.

## Rules

| Rule                             | Detail                                                                                                                                                                                  |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Global uniqueness**            | An Agent address can be approved **once globally**. Re-use the address only after revoking. Run a separate Agent per independent account.                                               |
| **Max per authorized account**   | **4** Agent Keys per authorized account. (A main account can have 4; each sub-account can independently have 4.)                                                                        |
| **`label`**                      | Required, unique within the authorized account. Used to identify the bot (`"mm-bot-prod"`, `"algo-v2"`). Reusing a label **replaces** the prior Agent (old one is immediately revoked). |
| **Scope** (`authorized_address`) | If set to your own main → Agent can act on the main account and all of its sub-accounts. If set to a sub-account address → Agent is scoped to that sub-account only.                    |
| **Permissions**                  | **Trading only** — place, modify, cancel, batch, leverage adjustments, position mode.                                                                                                   |
| **Cannot do**                    | Withdrawals, transfers, Agent management, creating sub-accounts. These require a private-key signature.                                                                                 |
| **Nonce space**                  | Each Agent has its own per-signer nonce space. Independent of your main private key and of other Agents. See [Nonce & Replay](broken://pages/8a71eea73f598368c6f1a45ec1078ee9c2cf7b3d). |

## Approve, Revoke, Renew

| Operation | Endpoint                         | EIP-712 type                                                                                                                                       |
| --------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Approve   | `POST /v1/account/approve-agent` | `ApproveAgent(address sender, address agentAddress, address authorizedAddress, uint32 validDays, string label, uint64 nonce, uint64 expiresAfter)` |
| Revoke    | `POST /v1/account/revoke-agent`  | `RevokeAgent(address sender, address agentAddress, uint64 nonce, uint64 expiresAfter)`                                                             |
| Renew     | `POST /v1/account/renew-agent`   | `RenewAgent(address sender, address agentAddress, uint32 validDays, uint64 nonce, uint64 expiresAfter)`                                            |

All three use [Signing Method B](broken://pages/1b294f6690c8101dac23707ef1ffe599bc1d8479) so that your wallet can display the human-readable fields (Agent address, validity, label) at signature time — not an opaque hash.

> **Approve / Revoke / Renew must be signed by the user's own private key.** Agent Keys cannot manage other Agent Keys — that would defeat the safety guarantee.

## Permission Verification

The chain applies these rules on every signed transaction. Let `target = target_address` (or `signer` if omitted):

1. `signer == target` → operate as that account's private key.
2. `signer` is an approved Agent:
   * Agent approved on main, `target` ∈ {main, its subs} → trade only.
   * Agent approved on sub, `target` == that sub → trade only.
3. `target` is a sub of `signer` → operate as main private key (allowed).
4. Otherwise → reject.

> **Security design:** Agent Keys can only trade — they cannot transfer funds. Even if an Agent Key leaks, the attacker cannot withdraw, transfer, or authorize new Agents.


---

# Agent Instructions: 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:

```
GET https://docs.lynxtrade.world/authentication/agent-keys.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.