POST /exchange – Write API Overview for Upside

Every write operation on Upside — 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://dev.upsidemax.xyz/exchange
Content-Type: application/json

Request Envelope

Every request shares the same top-level envelope structure:

{
  "action": { "type": "<action_type>", ...actionFields },
  "signature": { "r": "0x...", "s": "0x...", "v": 28 },
  "nonce": 1778572816871
}

Field	Type	Description
`action`	object	The operation payload. Must include `type` plus any action-specific fields.
`signature`	object	ECDSA signature with `r`, `s`, and `v` components. The server recovers your wallet address from this.
`nonce`	integer	Current Unix timestamp in milliseconds. Prevents replay attacks.

Some actions accept additional envelope-level fields (such as inviteCode for registerAccount). These sit alongside action, signature, and nonce — not inside action — and are not included in the signed payload.

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.

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.

Fee Settings & API Wallets

Configure fees and 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.

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.

Fee Settings

Action	Description
`updateFeeSetting`	Update the fee configuration for your account.

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 successful request always returns HTTP 200 with "status": "ok":

{
  "status": "ok",
  "requestId": "req-144115188075855882",
  "response": {
    "type": "<action_type>",
    ...actionSpecificFields
  }
}

"status": "ok" indicates the request was received and processed — it does not guarantee the business operation succeeded. Some actions embed an errorCode / errorMessage inside response. Always check those fields after a successful HTTP 200.

​Endpoint

​Request Envelope

​Authentication

​Action Groups

Account

Orders

Margin & Leverage

Conditional Orders

Collateral

Fee Settings & API Wallets

​All Available Actions

​Account

​Orders

​Margin & Leverage

​Conditional Orders

​Collateral

​Fee Settings

​API Wallet

​Response Shape

Endpoint

Request Envelope

Authentication

Action Groups

All Available Actions

Account

Orders

Margin & Leverage

Conditional Orders

Collateral

Fee Settings

API Wallet

Response Shape