> 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/agents/fetch-agents.md).
# GET /agents
List your agents
List your agents.
`operationId`: `fetchAgents`
> **Declared server:** `https://api.testnet.nexus.xyz/v1`. See [Networks](/api-reference/guides/networks.md).
> **Not reachable through CCXT.** Nexus-specific trading-agent registration. No CCXT equivalent — the closest unified concepts are API-key management, which CCXT deliberately leaves to the venue.
**Authentication:** `hmacAuth`, `walletSignature`.
## List your agents
> Returns all non-expired agent keys registered to the authenticated wallet.\
> \
> \*\*Agent keys are refused here\*\* with \`403\` (code \`AGENT\_KEY\_FORBIDDEN\`): a trade-only agent key may not list, rename or revoke its sibling credentials. Call this as the wallet itself: its own API key (\`hmacAuth\`), or a signature from the wallet over this action (\`walletSignature\`), which is how a client holding only an agent key does it.
````json
{"openapi":"3.1.0","info":{"title":"Nexus Exchange API","version":"0.9.101"},"tags":[{"name":"Agents","description":"Agent key registration and management (EIP-712 signed, no session token required)"}],"servers":[{"url":"https://api.testnet.nexus.xyz/v1","description":"Public testnet (play funds) — the default server and /v1 transport base for unversioned paths."},{"url":"https://api.nexus.xyz/v1","description":"Mainnet — **REAL FUNDS**. Collateral is USDX bridged from Ethereum Mainnet; orders placed here move real money, and there is no faucet. The durable per-network base. Listed after testnet on purpose, so nothing that reaches for \"the first https server\" lands on the real-funds target. Not resolvable yet: DNS/TLS is a separate infra change."},{"url":"http://localhost:9090","description":"Local development — the indexer served directly. Not a public network; whatever your local instance holds."}],"security":[{"hmacAuth":[]},{"walletSignature":[]}],"components":{"securitySchemes":{"hmacAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"HMAC API key authentication. Send three headers:\n- `X-API-Key`: your key ID (e.g. `nx_a1b2c3...`)\n- `X-Timestamp`: current time in unix milliseconds\n- `X-Signature`: `hex(hmac_sha256(secret, timestamp + \"\\n\" + METHOD + \"\\n\" + path + \"\\n\" + query + \"\\n\" + sha256_hex(body)))`\n\nTimestamp must be within 30 seconds of server time.\n\n**The key is network-scoped; the signature is not.** The canonical string above has no network component, so the same signed request is byte-identical on every host. What stops a testnet key from authenticating against mainnet is that the key does not exist in that host's key store — sign only for the host that minted the key, and never replay a signed payload against another network. Presented to the wrong host, a key is refused with the same opaque `401` as an unknown key and must not be retried there. See “API keys are bound to one network” in the API description."},"walletSignature":{"type":"apiKey","in":"header","name":"x-wallet-signature","description":"Wallet-signed authorization for managing agent keys. It is accepted only by `GET /agents`, `PATCH /agents/{address}` and `DELETE /agents/{address}`, and every other operation ignores these headers. It exists so a client that holds only an agent key (a trade-only credential, refused here with `403 AGENT_KEY_FORBIDDEN`) can still list, rename and revoke its keys: the wallet signs the action itself, the way it signs `POST /agents/register`, and the server checks that the signer is the account owner.\n\nSend four headers:\n\n- `x-wallet-account`: the wallet, `0x` + 40 hex.\n- `x-wallet-nonce`: the Unix time in milliseconds when the wallet signed, base 10.\n- `x-wallet-signature`: `0x` + the 65-byte signature `r (32) ‖ s (32) ‖ v (1)`, `v ∈ {27, 28}`.\n- `x-wallet-chain-id`: optional, the domain `chainId` the wallet signed with, base 10. Defaults to `20056`. A wallet signs with its active chain, so send what it used.\n\n**Typed data (EIP-712).** The domain is the one `POST /agents/register` uses: `{name: \"Nexus Exchange\", version: \"1\", chainId, salt}`, with `salt = keccak256(network)` as listed under `x-nexus-networks`, so a signature made on one network is not valid on another. One message type per operation:\n\n```\nListAgents { address account; uint64 nonce; } // GET /agents\nRenameAgent { address account; address agent; string label; uint64 nonce; } // PATCH /agents/{address}\nRevokeAgentKey { address account; address agent; uint64 nonce; } // DELETE /agents/{address}\n```\n\n`account` must equal `x-wallet-account`, `agent` is the `{address}` in the path, and `label` is the body's `label` exactly as sent (before trimming), so the wallet approves the bytes the server receives. `nonce` equals `x-wallet-nonce`. Sign with `eth_signTypedData_v4`.\n\n**Freshness and replay.** `nonce` must be no more than 60 seconds ahead of the server clock, and no older than 5 minutes for rename and revoke, or 30 minutes for the list. Rename and revoke are single use: the nonce must be strictly greater than the last one the same wallet used for either. A list signature is not consumed, so one signature can refresh the list for its 30 minutes without another wallet prompt.\n\n**Precedence.** When `x-wallet-signature` is present on one of the three operations, it is the request's only credential: any `hmacAuth`, `agentAuth` or session headers on the same request are ignored, and a bad wallet signature is refused rather than retried as another credential.\n\n**Errors.** `400 WALLET_AUTH_INCOMPLETE` (a missing or malformed `x-wallet-account`, `x-wallet-nonce` or `x-wallet-chain-id`). `401` with one of: `WALLET_SIGNATURE_EXPIRED` (outside the window, so sign again), `WALLET_SIGNATURE_INVALID` (not a 65-byte recoverable signature), `WALLET_SIGNER_MISMATCH` (it recovers to a different address than `x-wallet-account`, which is also what a signature over a different label, agent, network or operation produces), `WALLET_NONCE_REPLAY` (rename or revoke only: the nonce was already used, or a newer one has been).\n\n**Test vector.** Testnet domain, `chainId` 20056, `account` = `0x1111111111111111111111111111111111111111`, `agent` = `0xabababababababababababababababababababab`, `nonce` = `1790000000000`. Digests: `ListAgents` `0xd9f84ba368390c81c4f82e576b7633a92c9144fedbe07224e1c0ae5d01d3c491`; `RenameAgent` with `label` = `desk bot` `0x8dde1641182130307201e1e0e2a9a2bd73786c03cfa2aed2e47c6d58d5b0f660`; `RevokeAgentKey` `0x73669adde69e6f7cd9f9ecc0825887403ee05d5fc6322d462e91c42920192bcb`."}},"schemas":{"AgentInfo":{"type":"object","description":"A registered agent key as `GET /agents` reports it.\n\n**This schema is camelCase**, unlike the snake_case native Nexus schemas around it: `expiresAt` and `registeredAt`, not `expires_at` and `registered_at`. It is not one of the CCXT-compatible schemas either, so it matches neither naming family the Schema Reference's conventions describe. Read the field names here literally rather than inferring them from the rest of the API.","properties":{"address":{"type":"string","description":"Agent address (0x-prefixed)"},"expiresAt":{"$ref":"#/components/schemas/TimestampMs","description":"Expiry Unix ms"},"registeredAt":{"$ref":"#/components/schemas/TimestampMs","description":"Registration time Unix ms"},"label":{"type":["string","null"],"description":"Optional label"}}},"TimestampMs":{"type":"integer","format":"int64","description":"Unix epoch timestamp in milliseconds."}}},"paths":{"/agents":{"get":{"operationId":"fetchAgents","tags":["Agents"],"summary":"List your agents","description":"Returns all non-expired agent keys registered to the authenticated wallet.\n\n**Agent keys are refused here** with `403` (code `AGENT_KEY_FORBIDDEN`): a trade-only agent key may not list, rename or revoke its sibling credentials. Call this as the wallet itself: its own API key (`hmacAuth`), or a signature from the wallet over this action (`walletSignature`), which is how a client holding only an agent key does it.","responses":{"200":{"description":"Array of agent records","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AgentInfo"}}}}},"400":{"description":"`WALLET_AUTH_INCOMPLETE`: `x-wallet-signature` was sent without a valid `x-wallet-account`, `x-wallet-nonce` or `x-wallet-chain-id`"},"401":{"description":"Missing or invalid credentials. With `walletSignature`, the code says why: `WALLET_SIGNATURE_EXPIRED`, `WALLET_SIGNATURE_INVALID` or `WALLET_SIGNER_MISMATCH`."},"403":{"description":"`AGENT_KEY_FORBIDDEN`: the request was signed by an agent key and carried no `walletSignature`"}}}}}}
````
**Test it** cannot sign this request. `X-Signature` is an HMAC computed per call: see [Authentication](/api-reference/guides/authentication.md), or use an SDK.
***
API version `0.9.131`
---
# 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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.nexus.xyz/api-reference/agents/fetch-agents.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.