> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsidemax.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# approveAgent: Authorize an API Wallet for Automated Trading

> Approve an agent wallet to sign trade operations on behalf of your master account, keeping your master private key offline during automated trading.

The `approveAgent` action authorizes an **agent** — a separate hot wallet — to sign trading operations on your behalf. Agents can submit orders, cancellations, modifies, and TP/SL requests without requiring your master account's private key to be present. This lets you keep your master key in cold storage while running automated strategies with a dedicated API wallet.

Each master account supports up to **1 anonymous agent** and **3 named agents**. Re-approving an already-authorized address refreshes its expiry without consuming an additional quota slot. If you approve a named agent with a name that matches an existing named agent, the new entry overwrites the old one.

<Warning>
  Only a master account can approve or revoke agents. Agent wallets cannot manage other agents.
</Warning>

## Endpoint

```
POST https://dev.upsidemax.xyz/exchange
```

## Request

All requests must include an ECDSA signature and a millisecond-precision nonce. This request must be signed by the **master account**.

```json theme={"system"}
{
  "action": {
    "type": "approveAgent",
    "agentAddress": "0xabc0000000000000000000000000000000000001",
    "agentName": "bot1",
    "validUntil": 0
  },
  "signature": { "r": "0x...", "s": "0x...", "v": 28 },
  "nonce": 1778859500000
}
```

### Action fields

<ParamField body="type" type="string" required>
  Fixed value: `"approveAgent"`.
</ParamField>

<ParamField body="agentAddress" type="string" required>
  The Ethereum address of the wallet to authorize as an agent. Must be a valid checksummed or lowercase hex address in the format `0x` followed by 40 hex characters.
</ParamField>

<ParamField body="agentName" type="string">
  A human-readable label for this agent. Omit or pass an empty string to use the anonymous agent slot. Named agents consume one of the 3 named quota slots. If a named agent with the same name already exists, this request overwrites it.
</ParamField>

<ParamField body="validUntil" type="int64">
  Expiry timestamp as Unix milliseconds. Pass `0` or omit entirely to create a permanent authorization that does not expire.
</ParamField>

## Response

### Success

```json theme={"system"}
{
  "status": "ok",
  "response": {
    "type": "approveAgent",
    "data": { "agentAddress": "0xabc0000000000000000000000000000000000001" }
  }
}
```

### Response fields

<ResponseField name="agentAddress" type="string">
  The address of the agent that was approved, echoed back for confirmation.
</ResponseField>

## Error reference

Rejections return `status: "ok"` with an `errorCode` and `errorMessage` in `data`.

| Cause                                  | Description                                                                   |
| -------------------------------------- | ----------------------------------------------------------------------------- |
| Invalid agent address                  | The provided `agentAddress` is not a valid Ethereum address.                  |
| Address already used by another master | The wallet is already registered as an agent for a different master account.  |
| Named quota full                       | You already have 3 named agents and are trying to add a fourth distinct name. |
| Signer not registered                  | The signing key is not recognized as a valid master account.                  |

<Tip>
  To view your currently authorized agents, query `userAgents` via POST `/info`. To revoke an agent, use [revokeAgent](/exchange/revoke-agent).
</Tip>