Exchange API Overview

Every write operation on UpsideMAX — placing orders, cancelling positions, adjusting margin, managing collateral, and configuring your account — is submitted through a single endpoint: POST /exchange. The server inspects the action.type field in the request body to determine which operation to execute, then recovers your wallet address from the accompanying ECDSA signature to authorize it. This unified design means you only need one integration point for all state-changing calls.

Endpoint

POST https://upsidemax.xyz/exchange
Content-Type: application/json

Request Envelope

Every request shares the same top-level envelope structure:

{
  "action": { "type": "cancelAll", "a": 1 },
  "signature": { "r": "0x...", "s": "0x...", "v": 28 },
  "nonce": 1778572816871,
  "sync": true
}

Field	Type	Required	Description
`action`	object	Yes	The operation payload. Must include `type` plus any action-specific fields.
`signature`	object	Yes	ECDSA signature with `r`, `s`, and `v` components. The server recovers the signing address from it.
`nonce`	int64	Yes	Unix timestamp in milliseconds. Checked per signing address; see Nonce.
`sync`	boolean	No	Selects the response form for `order`, `cancel`, `cancelByCloid`, `cancelAll`, and `modify` only. See Synchronous and asynchronous responses. Any other action rejects it.
`signatureChainId`	string	No	`0x`-prefixed hex string giving the `domain.chainId` used to sign a typed-path action, for browser wallets that sign with their active chain. Defaults to the environment’s chain ID — `0x2627` (9767) on Devnet, `0x263c` (9788) on Mainnet. Ignored on the Agent path. A malformed value returns `400 BAD_REQUEST`; a value that differs from the chain ID actually signed returns `401 SIGNATURE_INVALID`. See Authentication.

sync, signatureChainId, and action-specific envelope fields (such as inviteCode for registerAccount) sit alongside action, signature, and nonce — not inside action — and are not included in the signed payload. Switching sync therefore requires no change to your signing code.

Authentication

All requests require a valid ECDSA signature. The server recovers your wallet address from the (r, s, v) tuple and uses it to authorize the operation — no API key header is needed. See the Authentication guide for details on what to sign and how to construct the signature.

Use the exact action.type strings listed below. They are the complete set — an unrecognised value returns UNKNOWN_ACTION. Placing an order is order, not newOrder, createOrder or placeOrder; cancelling is cancel. Do not infer an action name from a method name in an SDK or from another exchange’s API.

Action Groups

Account

Orders

Place, modify, and cancel perpetual orders.

Margin & Leverage

Adjust margin mode, leverage, and isolated margin balances.

Conditional Orders

Set and cancel take-profit, stop-loss, and other conditional orders.

Collateral

Lock, unlock, and transfer collateral across deployers and share groups.

API Wallets

Delegate signing to agent wallets.

All Available Actions

Account

Action	Description
`registerAccount`	Register your wallet address and receive a unique `accountId`.
`enrollUserToMarketDeployer`	Enroll in an additional market deployer to trade its contracts.

Orders

Action	Description
`order`	Place a new limit or market order.
`cancel`	Cancel an open order by its server-assigned order ID.
`cancelByCloid`	Cancel an open order using your client-assigned order ID (cloid).
`cancelAll`	Cancel all open orders for a single contract (contract `a` required).
`modify`	Modify the price or size of an existing open order.
`updateSlippageSetting`	Set the market-order slippage cap for your account within a market deployer.

Margin & Leverage

Action	Description
`updateIsolatedMargin`	Add or remove margin from an isolated-margin position.
`updateLeverage`	Change the leverage multiplier for a contract.
`updateMarginMode`	Switch a contract between cross and isolated margin mode.

Conditional Orders

Action	Description
`tpSl`	Attach a take-profit and/or stop-loss to an open position.
`cancelTpSl`	Remove the take-profit and/or stop-loss from a position.
`cancelConditional`	Cancel a specific conditional order by its ID.

Collateral

Action	Description
`lockCollateral`	Lock collateral into a market deployer.
`unlockCollateral`	Unlock collateral from a market deployer.
`transferBetweenDeployers`	Move collateral from one market deployer to another.
`setMarginShareType`	Configure the margin share type for an account.
`transferMdToShareGroup`	Transfer collateral from a market deployer into a share group.
`transferShareGroupToMd`	Transfer collateral from a share group back to a market deployer.
`lockIntoShareGroup`	Lock collateral directly into a share group.
`unlockFromShareGroup`	Unlock collateral from a share group.

API Wallet

Action	Description
`approveAgent`	Delegate signing authority to an agent wallet address.
`revokeAgent`	Remove signing authority from a previously approved agent.

Response Shape

A request that is processed synchronously returns HTTP 200 with "status": "ok". The action’s result is inside response.data, except for registerAccount, which places accountId directly under response.

{
  "status": "ok",
  "requestId": "req-144115188075855882",
  "response": {
    "type": "cancelAll",
    "data": { "limitCancelled": 2, "conditionalCancelled": 0 }
  }
}

Field	Type	Description
`status`	string	`"ok"` for a processed request.
`requestId`	string	Server-assigned request ID. Quote it when contacting support.
`response.type`	string	Echoes `action.type`.
`response.data`	object	The action-specific result, documented on each action page.

"status": "ok" indicates the request was received and processed — it does not guarantee the business operation succeeded. Order and cancel actions report each item in response.data.statuses[]; the other actions embed an errorCode (number) and errorMessage inside response.data when the request is refused. Always check those fields after an HTTP 200.

Error responses

A request rejected before processing returns a non-2xx HTTP status with "status": "error":

{
  "status": "error",
  "requestId": "req-144115188075855906",
  "code": "SIGNATURE_INVALID",
  "message": "signature recovery failed"
}

A parameter that fails validation returns HTTP 400 with code INVALID_PARAM and an errors[] array with one entry per failing field. Such a request is not executed.

{
  "status": "error",
  "requestId": "req-0",
  "code": "INVALID_PARAM",
  "message": "s OUT_OF_RANGE",
  "errors": [ { "field": "s", "reason": "OUT_OF_RANGE", "expected": "> 0" } ]
}

Field	Type	Description
`code`	string	Machine-readable error code.
`message`	string	Human-readable description.
`errors[].field`	string	The request field that failed validation.
`errors[].reason`	string	Why it failed, for example `MISSING_PARAM`, `INVALID_FORMAT`, or `OUT_OF_RANGE`.
`errors[].expected`	string	The accepted value or range. Present only when the rule has one.

Synchronous and asynchronous responses

order, cancel, cancelByCloid, cancelAll, and modify support two response forms, selected per request by the top-level envelope field sync. Both forms submit the same transaction and produce the same outcome; only the HTTP answer differs.

`sync`	HTTP	Body	Where the result is
`true`	200	The action’s own result (see below)	In the response
`false`	202	`{"status":"accepted","response":{"type":"accepted","data":{"count":1}}}`	`orderUpdates`, `userFills`, or `userOrders`
omitted	200 or 202	The server default applies, currently asynchronous (202)	As above

Set sync explicitly whenever you need a predictable form — an omitted sync follows the server default, which is not guaranteed to be identical across environments. The 202 body is identical for all five actions: type is the literal "accepted", and count is always 1 — it acknowledges the request, not the number of orders or cancels it carried. The 200 body depends on the action:

Action	`response.type`	`response.data`
`order`	`"order"`	`statuses[]`, one entry per element of `orders[]` (`resting`, `filled`, or `error`)
`cancel` / `cancelByCloid`	`"cancel"` / `"cancelByCloid"`	`statuses[]`, one entry per element of `cancels[]`
`cancelAll`	`"cancelAll"`	`limitCancelled` and `conditionalCancelled` counts — no `statuses[]`
`modify`	`"modify"`	`statuses[]` with exactly one entry for the modified order

Constraints:

Only these five actions accept sync. Every other action always answers synchronously; a sync field in its envelope — true or false — returns 400 SYNC_NOT_APPLICABLE.
sync must be a JSON boolean. A string such as "true" or a number returns 400 BAD_REQUEST.
Synchronous requests occupy server capacity while they wait. Under load the server may return 503 DOWNSTREAM_UNAVAILABLE; sending the request with sync: false and reading the result from WebSocket avoids it.

Timeouts and retries

A synchronous request that does not receive its result within the server’s waiting window returns 504 DOWNSTREAM_TIMEOUT. A 504 does not mean the request failed — the action may already have been executed. The same nonce is executed at most once per signing address. Re-sending an identical signed envelope therefore cannot execute the action twice: while the first copy is still in flight it returns 400 DUPLICATE_NONCE, and once the first copy is processed a re-send cannot return its result either. Neither answer tells you whether the first attempt executed. After a 504, a network error, or any other unknown outcome:

Do not sign again with a fresh nonce yet

A new nonce makes a new request. If the first one executed, a new signature executes the action a second time.

Reconcile by query

Look the request up by its effect: userOrders for orders still resting, orderHistory and userFills for orders that already ended, or the orderUpdates channel. Correlate orders by your client order ID c. For margin and collateral actions, read the resulting state from userAccount.

Retry only what did not execute

Once you have confirmed the action did not execute, sign it again with a new nonce and submit it.

HTTP errors

The codes below apply across POST /exchange. Each action page lists the ones that action can return; Error Codes carries the full reference.

HTTP	`code`	Cause
400	`BAD_REQUEST`	Malformed body or missing field, or the signing address has no registered account and is not an approved API wallet (`signer has no registered account`).
400	`INVALID_PARAM`	A parameter failed validation; see `errors[]`.
400	`UNKNOWN_ACTION`	`action.type` is not recognized.
400	`SYNC_NOT_APPLICABLE`	`sync` was sent with an action that does not accept it.
400	`DUPLICATE_NONCE`	A request with the same `nonce` from the same signing address is still being processed.
400	`BATCH_TOO_LARGE`	`orders[]` or `cancels[]` holds more than 10 entries.
401	`SIGNATURE_INVALID`	Signature recovery failed, or the recovered address does not match.
429	`RATE_LIMITED`	Too many requests.
503	`DOWNSTREAM_UNAVAILABLE`	Temporarily unavailable or busy; retry later.
503	`WARMING_UP`	The service is starting; retry later.
504	`DOWNSTREAM_TIMEOUT`	No result within the waiting window. The outcome is unknown — see Timeouts and retries.

​Endpoint

​Request Envelope

​Authentication

​Action Groups

Account

Orders

Margin & Leverage

Conditional Orders

Collateral

API Wallets

​All Available Actions

​Account

​Orders

​Margin & Leverage

​Conditional Orders

​Collateral

​API Wallet

​Response Shape

​Error responses

​Synchronous and asynchronous responses

​Timeouts and retries

​HTTP errors

Endpoint

Request Envelope

Authentication

Action Groups

All Available Actions

Account

Orders

Margin & Leverage

Conditional Orders

Collateral

API Wallet

Response Shape

Error responses

Synchronous and asynchronous responses

Timeouts and retries

HTTP errors