Approve Agent

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

required

A human-readable label. Pass an empty string "" for the anonymous slot, or a name for one of the 3 named quota slots (re-using a name overwrites that entry). Must be present in the signed JSON — omitting it yields 401 SIGNATURE_INVALID.

int64

required

Expiry as Unix milliseconds; 0 = permanent (no expiry). Must be present in the signed JSON (send 0 for permanent) — omitting it yields 401 SIGNATURE_INVALID.

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

API Wallet

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