# Agent Keys

Manage Agent Keys — delegated ECDSA keys that can sign trade requests on behalf of a user account, without exposing the main private key. Approve / Revoke / Renew operations require the **user's own private key** (Agent Keys cannot manage other Agent Keys).

## Approve Agent Key

> Delegate trading authority to an Agent Key. Each \*\*authorized account\*\* may hold at most\
> \*\*4\*\* Agent Keys; an Agent address can be approved \*\*globally only once\*\*.\
> \
> \*\*Must be signed by the user's own private key\*\* — Agent Keys cannot approve other Agent Keys.\
> \
> \*\*TradeVM-account mutual exclusion\*\*: \`agent\_address\` must not already have a TradeVM account\
> (rejected with \`10011\` if it does). If an already-approved Agent address later creates a\
> TradeVM account, its Agent authorization is automatically unbound and becomes invalid.\
> \
> \*\*Signing Method\*\*: B (Typed Data direct sign). EIP-712 type:\
> \`ApproveAgent(address sender,address agentAddress,address authorizedAddress,uint32 validDays,string label,uint64 nonce,uint64 expiresAfter)\`.\
> \
> See \[Signing Method B]\(/authentication/signing-method-b).\
> \
> \### Scope by \`authorized\_address\`\
> \
> \- \*\*Signer's own address\*\* → Agent can act on the signer and all of its sub-accounts\
> \- \*\*Sub-account address\*\* → Agent can act on that sub-account only<br>

```json
{"openapi":"3.0.3","info":{"title":"Lynx DEX API","version":"1.5.0"},"tags":[{"name":"Agent Keys","description":"Manage Agent Keys — delegated ECDSA keys that can sign trade requests on behalf of a user\naccount, without exposing the main private key. Approve / Revoke / Renew operations\nrequire the **user's own private key** (Agent Keys cannot manage other Agent Keys).\n"}],"servers":[{"url":"http://10.34.8.77:8481/v1","description":"Production"}],"paths":{"/account/approve-agent":{"post":{"tags":["Agent Keys"],"summary":"Approve Agent Key","operationId":"approveAgent","description":"Delegate trading authority to an Agent Key. Each **authorized account** may hold at most\n**4** Agent Keys; an Agent address can be approved **globally only once**.\n\n**Must be signed by the user's own private key** — Agent Keys cannot approve other Agent Keys.\n\n**TradeVM-account mutual exclusion**: `agent_address` must not already have a TradeVM account\n(rejected with `10011` if it does). If an already-approved Agent address later creates a\nTradeVM account, its Agent authorization is automatically unbound and becomes invalid.\n\n**Signing Method**: B (Typed Data direct sign). EIP-712 type:\n`ApproveAgent(address sender,address agentAddress,address authorizedAddress,uint32 validDays,string label,uint64 nonce,uint64 expiresAfter)`.\n\nSee [Signing Method B](/authentication/signing-method-b).\n\n### Scope by `authorized_address`\n\n- **Signer's own address** → Agent can act on the signer and all of its sub-accounts\n- **Sub-account address** → Agent can act on that sub-account only\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_address","authorized_address","valid_days","label","address","nonce","expires_after","signature"],"properties":{"agent_address":{"type":"string","description":"New Agent Key's Ethereum address."},"authorized_address":{"type":"string","description":"Account being delegated to. Must be the signer's own address or a sub-account."},"valid_days":{"type":"integer","minimum":1,"maximum":180,"description":"Validity in days. On-chain expiry = `approval_block_time + valid_days × 86400000`."},"label":{"type":"string","description":"Unique-per-authorized-account identifier. If an existing label is reused, the old Agent is immediately revoked."},"address":{"type":"string","description":"Signer (user) address."},"nonce":{"type":"integer","format":"int64"},"expires_after":{"type":"integer","format":"int64"},"signature":{"$ref":"#/components/schemas/Signature"}}}}}},"responses":{"200":{"description":"Agent Key approved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"tx_hash":{"type":"string"},"agent_address":{"type":"string"},"label":{"type":"string"},"authorized_address":{"type":"string"},"valid_days":{"type":"integer"},"expires_at":{"type":"integer","format":"int64"},"replaced_agent_address":{"type":"string","nullable":true,"description":"Old Agent address if a same-label record was overwritten."}}}}}]}}}},"422":{"description":"Errors: `10007` (limit reached), `10009` (address already approved), `10010` (invalid authorized_address), `10011` (agent_address already has a TradeVM account)"}}}}},"components":{"schemas":{"Signature":{"type":"object","description":"ECDSA signature components `(r, s, v)` over the EIP-712 signing hash.","required":["r","s","v"],"properties":{"r":{"type":"string","description":"32-byte hex string with `0x` prefix."},"s":{"type":"string","description":"32-byte hex string with `0x` prefix."},"v":{"type":"integer","description":"Recovery identifier — typically 27 or 28.","enum":[27,28]}}},"ResponseEnvelope":{"type":"object","description":"Standard response envelope shared by every endpoint.","required":["code","msg","data"],"properties":{"code":{"type":"string","description":"`\"0\"` for success. Non-zero indicates an error code — see [Error Codes](/reference/error-codes)."},"msg":{"type":"string","description":"Empty on success; human-readable error description on failure."},"data":{"description":"Endpoint-specific payload on success; `null` on failure.","nullable":true},"trace_code":{"type":"string","description":"Backend trace identifier. Empty on success; populated on failure for support diagnostics."}}}}}}
```

## Revoke Agent Key

> Permanently revoke an Agent Key.\
> \*\*Must be signed by the user's own private key.\*\*\
> \
> Signing Method B, type:\
> \`RevokeAgent(address sender,address agentAddress,uint64 nonce,uint64 expiresAfter)\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Lynx DEX API","version":"1.5.0"},"tags":[{"name":"Agent Keys","description":"Manage Agent Keys — delegated ECDSA keys that can sign trade requests on behalf of a user\naccount, without exposing the main private key. Approve / Revoke / Renew operations\nrequire the **user's own private key** (Agent Keys cannot manage other Agent Keys).\n"}],"servers":[{"url":"http://10.34.8.77:8481/v1","description":"Production"}],"paths":{"/account/revoke-agent":{"post":{"tags":["Agent Keys"],"summary":"Revoke Agent Key","operationId":"revokeAgent","description":"Permanently revoke an Agent Key.\n**Must be signed by the user's own private key.**\n\nSigning Method B, type:\n`RevokeAgent(address sender,address agentAddress,uint64 nonce,uint64 expiresAfter)`.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_address","address","nonce","expires_after","signature"],"properties":{"agent_address":{"type":"string"},"address":{"type":"string"},"nonce":{"type":"integer","format":"int64"},"expires_after":{"type":"integer","format":"int64"},"signature":{"$ref":"#/components/schemas/Signature"}}}}}},"responses":{"200":{"description":"Agent revoked","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"tx_hash":{"type":"string"},"agent_address":{"type":"string"}}}}}]}}}},"422":{"description":"Errors: `10012` (Agent not found or not approved)"}}}}},"components":{"schemas":{"Signature":{"type":"object","description":"ECDSA signature components `(r, s, v)` over the EIP-712 signing hash.","required":["r","s","v"],"properties":{"r":{"type":"string","description":"32-byte hex string with `0x` prefix."},"s":{"type":"string","description":"32-byte hex string with `0x` prefix."},"v":{"type":"integer","description":"Recovery identifier — typically 27 or 28.","enum":[27,28]}}},"ResponseEnvelope":{"type":"object","description":"Standard response envelope shared by every endpoint.","required":["code","msg","data"],"properties":{"code":{"type":"string","description":"`\"0\"` for success. Non-zero indicates an error code — see [Error Codes](/reference/error-codes)."},"msg":{"type":"string","description":"Empty on success; human-readable error description on failure."},"data":{"description":"Endpoint-specific payload on success; `null` on failure.","nullable":true},"trace_code":{"type":"string","description":"Backend trace identifier. Empty on success; populated on failure for support diagnostics."}}}}}}
```

## Renew Agent Key

> Update an existing Agent Key's expiry. The new \`valid\_days\` is counted from the current\
> block time (not extended from the prior expiry).\
> \*\*Must be signed by the user's own private key.\*\*\
> \
> Signing Method B, type:\
> \`RenewAgent(address sender,address agentAddress,uint32 validDays,uint64 nonce,uint64 expiresAfter)\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Lynx DEX API","version":"1.5.0"},"tags":[{"name":"Agent Keys","description":"Manage Agent Keys — delegated ECDSA keys that can sign trade requests on behalf of a user\naccount, without exposing the main private key. Approve / Revoke / Renew operations\nrequire the **user's own private key** (Agent Keys cannot manage other Agent Keys).\n"}],"servers":[{"url":"http://10.34.8.77:8481/v1","description":"Production"}],"paths":{"/account/renew-agent":{"post":{"tags":["Agent Keys"],"summary":"Renew Agent Key","operationId":"renewAgent","description":"Update an existing Agent Key's expiry. The new `valid_days` is counted from the current\nblock time (not extended from the prior expiry).\n**Must be signed by the user's own private key.**\n\nSigning Method B, type:\n`RenewAgent(address sender,address agentAddress,uint32 validDays,uint64 nonce,uint64 expiresAfter)`.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_address","valid_days","address","nonce","expires_after","signature"],"properties":{"agent_address":{"type":"string"},"valid_days":{"type":"integer","minimum":1,"maximum":180},"address":{"type":"string"},"nonce":{"type":"integer","format":"int64"},"expires_after":{"type":"integer","format":"int64"},"signature":{"$ref":"#/components/schemas/Signature"}}}}}},"responses":{"200":{"description":"Agent renewed","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"tx_hash":{"type":"string"},"agent_address":{"type":"string"},"valid_days":{"type":"integer"},"expires_at":{"type":"integer","format":"int64"}}}}}]}}}}}}}},"components":{"schemas":{"Signature":{"type":"object","description":"ECDSA signature components `(r, s, v)` over the EIP-712 signing hash.","required":["r","s","v"],"properties":{"r":{"type":"string","description":"32-byte hex string with `0x` prefix."},"s":{"type":"string","description":"32-byte hex string with `0x` prefix."},"v":{"type":"integer","description":"Recovery identifier — typically 27 or 28.","enum":[27,28]}}},"ResponseEnvelope":{"type":"object","description":"Standard response envelope shared by every endpoint.","required":["code","msg","data"],"properties":{"code":{"type":"string","description":"`\"0\"` for success. Non-zero indicates an error code — see [Error Codes](/reference/error-codes)."},"msg":{"type":"string","description":"Empty on success; human-readable error description on failure."},"data":{"description":"Endpoint-specific payload on success; `null` on failure.","nullable":true},"trace_code":{"type":"string","description":"Backend trace identifier. Empty on success; populated on failure for support diagnostics."}}}}}}
```

## List Authorized Agents

> All Agent Keys currently authorized on \`address\`.

```json
{"openapi":"3.0.3","info":{"title":"Lynx DEX API","version":"1.5.0"},"tags":[{"name":"Agent Keys","description":"Manage Agent Keys — delegated ECDSA keys that can sign trade requests on behalf of a user\naccount, without exposing the main private key. Approve / Revoke / Renew operations\nrequire the **user's own private key** (Agent Keys cannot manage other Agent Keys).\n"}],"servers":[{"url":"http://10.34.8.77:8481/v1","description":"Production"}],"paths":{"/account/agents":{"get":{"tags":["Agent Keys"],"summary":"List Authorized Agents","operationId":"listAgents","description":"All Agent Keys currently authorized on `address`.","parameters":[{"$ref":"#/components/parameters/AddressQuery"}],"responses":{"200":{"description":"Authorized Agent Keys","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/AccountAgent"}}}}}}]}}}}}}}},"components":{"parameters":{"AddressQuery":{"name":"address","in":"query","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"description":"Account address (`0x`-prefixed hex)."}},"schemas":{"ResponseEnvelope":{"type":"object","description":"Standard response envelope shared by every endpoint.","required":["code","msg","data"],"properties":{"code":{"type":"string","description":"`\"0\"` for success. Non-zero indicates an error code — see [Error Codes](/reference/error-codes)."},"msg":{"type":"string","description":"Empty on success; human-readable error description on failure."},"data":{"description":"Endpoint-specific payload on success; `null` on failure.","nullable":true},"trace_code":{"type":"string","description":"Backend trace identifier. Empty on success; populated on failure for support diagnostics."}}},"AccountAgent":{"type":"object","properties":{"agent_address":{"type":"string"},"authorized_address":{"type":"string"},"label":{"type":"string"},"approved_at":{"type":"integer","format":"int64"},"expires_at":{"type":"integer","format":"int64"}}}}}}
```


---

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