Exchange Requests

All state-changing operations on UpsideMAX — placing orders, cancelling orders, registering accounts, adjusting margin, and more — use a single endpoint: POST /exchange. The operation to perform is determined entirely by the action.type field inside the JSON body, not by the URL. This action-based routing means your HTTP client only ever needs to know one write URL; you change the payload to change the operation.

Endpoint

POST /exchange
Content-Type: application/json

Envelope Structure

Every POST /exchange request body is a JSON object with the following top-level fields:

{
  "action": {
    "type": "<actionType>",
    "<field>": "<value>"
  },
  "signature": {
    "r": "0x<64 hex>",
    "s": "0x<64 hex>",
    "v": 27
  },
  "nonce": 1778572951477
}

Fields

object

required

action (required) — The operation payload. Must contain a type string that identifies the action (e.g. "order", "cancel", "registerAccount"). All other fields are action-specific.

string

required

action.type (required) — Identifies which action to perform. It also selects the EIP-712 signing path — funds/permission actions use a typed struct, everything else uses the Agent path. See Authentication.Common values: order, cancel, cancelByCloid, modify, registerAccount, updateLeverage, updateIsolatedMargin.

object

required

signature (required) — EIP-712 ECDSA signature (secp256k1) over the action. The server recovers the signer’s Ethereum address from this signature to authorize the operation — there are no API keys.

string

required

signature.r (required) — The r component of the ECDSA signature. Must be a 0x-prefixed lowercase hex string representing a 32-byte value (66 characters total).

string

required

signature.s (required) — The s component of the ECDSA signature. Same format as r.

integer

required

signature.v (required) — The recovery parameter. Must be 27 or 28 (Ethereum convention: 27 + recovery_bit).

integer

required

nonce (required) — An int64 Unix millisecond timestamp. Must be unique per signer. Used as replay protection — the server rejects any previously seen nonce from the same address. While a request is still being processed, a second request from the same address with the same nonce returns 400 DUPLICATE_NONCE. See Nonce.

string

vaultAddress — Optional. Reserved for vault operations, which are not currently enabled; the server ignores this field. Delegated agent trading does not use it: an API wallet signs with its own key and the server routes to the master account from the recovered signer, so you do not send vaultAddress or any master identifier.

boolean

sync — Optional. Selects the response form for the order and cancel family only: order, cancel, cancelByCloid, cancelAll, and modify. true returns HTTP 200 with the action’s result after it has been executed; false returns HTTP 202 accepted immediately. Must be a JSON boolean. Sits at the top level of the envelope and is not part of the signed message. Sending it with any other action returns 400 SYNC_NOT_APPLICABLE. See Synchronous and asynchronous responses.

string

signatureChainId — Optional. The domain.chainId your client used when signing a typed-path action, as a 0x-prefixed hex string. Defaults to the environment’s chain ID — 0x2627 (9767) on Devnet, 0x263c (9788) on Mainnet. Sits at the top level of the envelope and is not part of the signed message. See Authentication.

string

inviteCode — Conditional. A 6-character alphanumeric invitation code required by registerAccount. Include this field at the top level of the envelope — not inside action. This field is not included in the signed message.

Synchronous and asynchronous responses

The order and cancel family — order, cancel, cancelByCloid, cancelAll, and modify — supports two response forms, selected per request by the top-level sync field. Both forms submit the same transaction and produce the same matching result; they differ only in when and how the HTTP response is returned.

	`sync: true`	`sync: false`
HTTP status	`200`	`202`
Body	The action’s own result (see below)	`{"type": "accepted", "data": {"count": 1}}` — no business result
Returned when	The action has been executed	The request has been accepted for processing
How to get the result	Read the response	Subscribe to `orderUpdates` or `userFills`, or poll `userOrders`

When sync is omitted, the server default applies, which is currently the asynchronous 202 form. An omitted sync is not the same as false: to rely on one form, set sync explicitly.

{
  "action": {
    "type": "order",
    "orders": [
      { "a": 1, "b": true, "p": "50", "s": "10", "r": false, "t": { "limit": { "tif": "Gtc" } } }
    ],
    "grouping": "na"
  },
  "signature": { "r": "0x...", "s": "0x...", "v": 27 },
  "nonce": 1778572951477,
  "sync": true
}

sync is not part of the signature, so the same signed action can be submitted in either form without changing any signing code. The 200 body differs by action:

Action	`response.type`	`response.data`
`order`	`"order"`	`{"statuses": [...]}`, one entry per element of `orders[]`, in order (`resting`, `filled`, or `error`)
`cancel`, `cancelByCloid`	`"cancel"`, `"cancelByCloid"`	`{"statuses": [...]}`, one entry per element of `cancels[]`, in order
`cancelAll`	`"cancelAll"`	`{"limitCancelled": n, "conditionalCancelled": m}` — no `statuses[]`
`modify`	`"modify"`	`{"statuses": [...]}` with exactly one entry, in the same form as `order`

Do not write a generic parser that reads statuses[] from every 200; a cancelAll response has none. Constraints:

sync applies only to the five actions above. Every other write action already returns its result synchronously and has no asynchronous form; sending sync with any of them — true or false — returns 400 SYNC_NOT_APPLICABLE.
sync must be a JSON boolean. A string such as "true" or a number such as 1 is rejected with 400.
Under heavy load, a sync: true request can return 503 DOWNSTREAM_UNAVAILABLE. Submit with sync: false and read the result from WebSocket instead.
A 504 DOWNSTREAM_TIMEOUT on a sync: true request means the server did not receive the result in time — not that the request failed. The transaction may already have executed. Confirm the final state through orderUpdates or a query before submitting anything new. See Error Codes.
Do not submit the same nonce concurrently. While a request is in flight, a second request with the same nonce from the same signing address returns 400 DUPLICATE_NONCE; re-sending that envelope cannot succeed.

Action-Based Routing

Unlike a traditional REST API where POST /orders creates an order and DELETE /orders/:id cancels one, UpsideMAX routes every write operation through POST /exchange. Routing is determined by action.type in the body. This keeps the transport layer simple and makes it easy to batch operations in a single request structure.

The table below maps action.type values to their operations:

`action.type`	Operation
`registerAccount`	Register a new trading account for an address
`order`	Place one or more orders (up to 10 per request)
`cancel`	Cancel one or more orders by order ID
`cancelByCloid`	Cancel an order by client order ID
`modify`	Modify the price or size of an existing order
`updateSlippageSetting`	Set the market-order slippage cap for an account
`updateLeverage`	Change leverage for an asset
`updateIsolatedMargin`	Add or remove isolated margin for a position

Example Request

The following example places a limit GTC buy order (raw p / s values — scale per the contract’s configs):

{
  "action": {
    "type": "order",
    "orders": [
      {
        "a": 1,
        "b": true,
        "p": "50",
        "s": "10",
        "r": false,
        "t": { "limit": { "tif": "Gtc" } }
      }
    ],
    "grouping": "na"
  },
  "signature": {
    "r": "0x3b2a1f...",
    "s": "0x7cf133...",
    "v": 28
  },
  "nonce": 1778572951477
}

See Authentication for instructions on building the signature, and Nonce for nonce generation rules.

Overview

Authentication

Request Format

Reference

SDKs

Endpoint

Envelope Structure

Fields

Synchronous and asynchronous responses

Action-Based Routing

Example Request

​Endpoint

​Envelope Structure

​Fields

​Synchronous and asynchronous responses

​Action-Based Routing

​Example Request

Endpoint

Envelope Structure

Fields

Synchronous and asynchronous responses

Action-Based Routing

Example Request