> For the complete documentation index, see [llms.txt](https://docs.unix.market/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unix.market/authentication/agent-keys.md). # Agent Keys UniX does not use traditional HMAC API keys. Instead, a user authorizes an **Agent Key** on-chain through `POST /v1/account/approve-agent`. An Agent Key is a separate ECDSA keypair that can sign allowed trading requests without exposing the user's private key. The user's private key remains the highest-permission signer and does not need to be registered as an Agent. Agent Keys are a delegation mechanism for trading automation. {% hint style="info" %} Agent Keys can trade. They cannot withdraw, transfer funds, manage Agent Keys, or create sub-accounts. {% endhint %} ## Lifecycle ``` User private key signs POST /v1/account/approve-agent -> chain records signer, agent_address, authorized_address, label, expiry -> Agent Key signs allowed write requests -> node verifies signature, nonce, expiry, and authorization scope -> user private key can later renew or revoke the Agent ``` ## Rules | Rule | Detail | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Global uniqueness** | One Agent address can be authorized only once globally. It cannot be authorized on multiple accounts at the same time. | | **TradeVM account mutual exclusion** | `agent_address` must not already have a TradeVM account. If it does, `approve-agent` is rejected. If an already-approved Agent address later creates a TradeVM account, that Agent authorization is automatically unbound and becomes invalid. | | **Max per authorized account** | Each authorized account can have at most **4** Agent Keys. A main account can have 4, and each sub-account can independently have 4. | | **`label`** | Required and unique within the authorized account. It identifies the application, such as `"mm-bot-prod"` or `"algo-v2"`. Reusing a label replaces the prior Agent and invalidates the old Agent immediately. | | **Scope** | `authorized_address` defines the scope. Main account scope covers the main account and all sub-accounts. Sub-account scope covers only that sub-account. | | **Permissions** | Trading operations only, including order placement, cancellation, modification, batch order actions, leverage adjustments, position mode changes, and isolated margin updates. | | **Cannot do** | Withdrawals, transfers, Agent Key management, or other private-key-only account operations. | | **Nonce space** | Each Agent Key has an independent per-signer nonce space, separate from the user private key and from other Agents. | ## Field Meanings | Field | Used in | Meaning | | -------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `signer_address` | All signed write request bodies | The signer of the request. For Agent management endpoints, this must be the user's private-key address, not an Agent Key. | | `agent_address` | Agent management request body and response | The ECDSA address being approved, renewed, or revoked as an Agent Key. | | `authorized_address` | `approve-agent` request body and response | The account that receives this Agent authorization. It must be the signer account itself or a sub-account within the signer's permission scope. | | `valid_days` | `approve-agent`, `renew-agent` | Validity duration in days. The chain computes `expires_at` from the approval or renewal block time. Valid range is 1 to 180 days. | | `label` | `approve-agent`, `create-sub` | Human-readable identifier. For Agent Keys, it is unique within the authorized account and reusing it replaces the old Agent. | | `target_address` | Later Agent-signed Method A requests | The account the Agent is operating on. Agent management endpoints do not use `target_address`. | ## Approve, Renew, Revoke | Operation | Endpoint | Signing method | EIP-712 type | | ----------------- | -------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Approve Agent Key | `POST /v1/account/approve-agent` | Method B | `ApproveAgent(address signerAddress,address agentAddress,address authorizedAddress,uint32 validDays,string label,uint64 nonce,uint64 expiresAfter)` | | Renew Agent Key | `POST /v1/account/renew-agent` | Method B | `RenewAgent(address signerAddress,address agentAddress,uint32 validDays,uint64 nonce,uint64 expiresAfter)` | | Revoke Agent Key | `POST /v1/account/revoke-agent` | Method B | `RevokeAgent(address signerAddress,address agentAddress,uint64 nonce,uint64 expiresAfter)` | All three endpoints must be signed by the user's private key. An Agent Key cannot approve, renew, or revoke any Agent Key. ## Authorization Scope | `authorized_address` value | Agent can operate | | ----------------------------- | -------------------------------------- | | Signer's main account address | The main account and all sub-accounts. | | A sub-account address | Only that sub-account. | When the Agent later signs a Method A request, the node resolves the target account as: 1. `target_address`, if present. 2. Otherwise `signer_address`. The node then checks whether the Agent authorization covers that target account. ## Security Boundary Agent Keys are intentionally restricted to trading. Even if an Agent Key leaks, it cannot transfer funds, withdraw, create new Agents, or create sub-accounts. Those operations require a private-key signature from the relevant user-controlled account. --- # 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: ``` GET https://docs.unix.market/authentication/agent-keys.md?ask= ``` 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.