approveAgent: Authorize an API Wallet for 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.

Only a master account can approve or revoke agents. Agent wallets cannot manage other agents.

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.

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

Action fields

string

required

Fixed value: "approveAgent".

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.

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.

int64

Expiry timestamp as Unix milliseconds. Pass 0 or omit entirely to create a permanent authorization that does not expire.

Response

Success

{
  "status": "ok",
  "response": {
    "type": "approveAgent",
    "data": { "agentAddress": "0xabc0000000000000000000000000000000000001" }
  }
}

Response fields

string

The address of the agent that was approved, echoed back for confirmation.

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.

To view your currently authorized agents, query userAgents via POST /info. To revoke an agent, use revokeAgent.

Overview

Account

Orders

Margin & Leverage

Conditional Orders

Collateral Transfers

Fee Settings

API Wallet

approveAgent: Authorize an API Wallet for Automated Trading

Endpoint

Request

Action fields

Response

Success

Response fields

Error reference

​Endpoint

​Request

​Action fields

​Response

​Success

​Response fields

​Error reference

Endpoint

Request

Action fields

Response

Success

Response fields

Error reference