> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsidemax.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /exchange – Write API Overview for Upside

> All state-changing operations on Upside route through POST /exchange and are dispatched by the action.type field in your request body.

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

```text theme={"system"}
POST https://dev.upsidemax.xyz/exchange
Content-Type: application/json
```

## Request Envelope

Every request shares the same top-level envelope structure:

```json theme={"system"}
{
  "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.                                  |

<Note>
  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.
</Note>

## 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](/guide/authentication) for details on what to sign and how to construct the signature.

## Action Groups

<CardGroup cols={2}>
  <Card title="Account" icon="user">
    Register your wallet and enroll in market deployers.

    * [`registerAccount`](/exchange/register-account)
    * [`enrollUserToMarketDeployer`](/exchange/enroll-user-to-market-deployer)
  </Card>

  <Card title="Orders" icon="arrow-right-arrow-left">
    Place, modify, and cancel perpetual orders.

    * [`order`](/exchange/order)
    * [`cancel`](/exchange/cancel)
    * [`cancelByCloid`](/exchange/cancel-by-cloid)
    * [`cancelAll`](/exchange/cancel-all)
    * [`modify`](/exchange/modify)
  </Card>

  <Card title="Margin & Leverage" icon="sliders">
    Adjust margin mode, leverage, and isolated margin balances.

    * [`updateIsolatedMargin`](/exchange/update-isolated-margin)
    * [`updateLeverage`](/exchange/update-leverage)
    * [`updateMarginMode`](/exchange/update-margin-mode)
  </Card>

  <Card title="Conditional Orders" icon="code-branch">
    Set and cancel take-profit, stop-loss, and other conditional orders.

    * [`tpSl`](/exchange/tp-sl)
    * [`cancelTpSl`](/exchange/cancel-tp-sl)
    * [`cancelConditional`](/exchange/cancel-conditional)
  </Card>

  <Card title="Collateral" icon="vault">
    Lock, unlock, and transfer collateral across deployers and share groups.

    * [`lockCollateral`](/exchange/lock-collateral)
    * [`unlockCollateral`](/exchange/unlock-collateral)
    * [`transferBetweenDeployers`](/exchange/transfer-between-deployers)
    * [`setMarginShareType`](/exchange/set-margin-share-type)
    * [`transferMdToShareGroup`](/exchange/transfer-md-to-share-group)
    * [`transferShareGroupToMd`](/exchange/transfer-share-group-to-md)
    * [`lockIntoShareGroup`](/exchange/lock-into-share-group)
    * [`unlockFromShareGroup`](/exchange/unlock-from-share-group)
  </Card>

  <Card title="Fee Settings & API Wallets" icon="key">
    Configure fees and delegate signing to agent wallets.

    * [`updateFeeSetting`](/exchange/update-fee-setting)
    * [`approveAgent`](/exchange/approve-agent)
    * [`revokeAgent`](/exchange/revoke-agent)
  </Card>
</CardGroup>

## All Available Actions

### Account

| Action                                                                   | Description                                                     |
| ------------------------------------------------------------------------ | --------------------------------------------------------------- |
| [`registerAccount`](/exchange/register-account)                          | Register your wallet address and receive a unique `accountId`.  |
| [`enrollUserToMarketDeployer`](/exchange/enroll-user-to-market-deployer) | Enroll in an additional market deployer to trade its contracts. |

### Orders

| Action                                       | Description                                                           |
| -------------------------------------------- | --------------------------------------------------------------------- |
| [`order`](/exchange/order)                   | Place a new limit or market order.                                    |
| [`cancel`](/exchange/cancel)                 | Cancel an open order by its server-assigned order ID.                 |
| [`cancelByCloid`](/exchange/cancel-by-cloid) | Cancel an open order using your client-assigned order ID (cloid).     |
| [`cancelAll`](/exchange/cancel-all)          | Cancel all open orders for a single contract (contract `a` required). |
| [`modify`](/exchange/modify)                 | Modify the price or size of an existing open order.                   |

### Margin & Leverage

| Action                                                     | Description                                               |
| ---------------------------------------------------------- | --------------------------------------------------------- |
| [`updateIsolatedMargin`](/exchange/update-isolated-margin) | Add or remove margin from an isolated-margin position.    |
| [`updateLeverage`](/exchange/update-leverage)              | Change the leverage multiplier for a contract.            |
| [`updateMarginMode`](/exchange/update-margin-mode)         | Switch a contract between cross and isolated margin mode. |

### Conditional Orders

| Action                                              | Description                                                |
| --------------------------------------------------- | ---------------------------------------------------------- |
| [`tpSl`](/exchange/tp-sl)                           | Attach a take-profit and/or stop-loss to an open position. |
| [`cancelTpSl`](/exchange/cancel-tp-sl)              | Remove the take-profit and/or stop-loss from a position.   |
| [`cancelConditional`](/exchange/cancel-conditional) | Cancel a specific conditional order by its ID.             |

### Collateral

| Action                                                             | Description                                                       |
| ------------------------------------------------------------------ | ----------------------------------------------------------------- |
| [`lockCollateral`](/exchange/lock-collateral)                      | Lock collateral into a market deployer.                           |
| [`unlockCollateral`](/exchange/unlock-collateral)                  | Unlock collateral from a market deployer.                         |
| [`transferBetweenDeployers`](/exchange/transfer-between-deployers) | Move collateral from one market deployer to another.              |
| [`setMarginShareType`](/exchange/set-margin-share-type)            | Configure the margin share type for an account.                   |
| [`transferMdToShareGroup`](/exchange/transfer-md-to-share-group)   | Transfer collateral from a market deployer into a share group.    |
| [`transferShareGroupToMd`](/exchange/transfer-share-group-to-md)   | Transfer collateral from a share group back to a market deployer. |
| [`lockIntoShareGroup`](/exchange/lock-into-share-group)            | Lock collateral directly into a share group.                      |
| [`unlockFromShareGroup`](/exchange/unlock-from-share-group)        | Unlock collateral from a share group.                             |

### Fee Settings

| Action                                             | Description                                    |
| -------------------------------------------------- | ---------------------------------------------- |
| [`updateFeeSetting`](/exchange/update-fee-setting) | Update the fee configuration for your account. |

### API Wallet

| Action                                    | Description                                                |
| ----------------------------------------- | ---------------------------------------------------------- |
| [`approveAgent`](/exchange/approve-agent) | Delegate signing authority to an agent wallet address.     |
| [`revokeAgent`](/exchange/revoke-agent)   | Remove signing authority from a previously approved agent. |

## Response Shape

A successful request always returns HTTP 200 with `"status": "ok"`:

```json theme={"system"}
{
  "status": "ok",
  "requestId": "req-144115188075855882",
  "response": {
    "type": "<action_type>",
    ...actionSpecificFields
  }
}
```

<Warning>
  `"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.
</Warning>