> ## 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.

# order: Place Limit and Market Orders on Upside

> Place limit (GTC, IOC, ALO) or market orders on Upside. Submit up to 10 orders in a single batched request using compact single-letter keys.

The `order` action lets you place one or more limit or market orders against a specific contract. Each request can contain up to 10 order objects, all signed with a single ECDSA signature. Order objects use compact single-letter keys to keep payloads small and reduce bandwidth overhead.

## Endpoint

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

## Request Body

<Tabs>
  <Tab title="Limit Order">
    Place a limit order that rests in the order book until filled or cancelled (GTC), or choose IOC/ALO for alternative execution policies.

    ```json theme={"system"}
    {
      "action": {
        "type": "order",
        "orders": [
          {
            "a": 1,
            "b": true,
            "p": "100",
            "s": "10",
            "r": false,
            "t": { "limit": { "tif": "Gtc" } }
          }
        ],
        "grouping": "na"
      },
      "signature": { "r": "0x...", "s": "0x...", "v": 28 },
      "nonce": 1778572951477
    }
    ```
  </Tab>

  <Tab title="Market Order">
    Place a market order that executes immediately at the best available price. Omit the `p` field entirely for market orders.

    ```json theme={"system"}
    {
      "action": {
        "type": "order",
        "orders": [
          {
            "a": 1,
            "b": true,
            "s": "10",
            "r": false,
            "t": { "market": {} }
          }
        ],
        "grouping": "na"
      },
      "signature": { "r": "0x...", "s": "0x...", "v": 28 },
      "nonce": 1778572951478
    }
    ```
  </Tab>
</Tabs>

<Warning>
  Testnet market orders may return `"price 10000 exceeds maxTicks 10000"`. Use limit orders when testing against the testnet environment.
</Warning>

## Action Fields

<ParamField body="type" type="string" required>
  Fixed value: `"order"`.
</ParamField>

<ParamField body="orders" type="array" required>
  Array of order objects to submit. Maximum **10** orders per request. See the order object fields below.
</ParamField>

<ParamField body="grouping" type="string" required>
  Fixed value: `"na"`. Reserved for future order grouping strategies.
</ParamField>

## Order Object Fields

Each element of the `orders` array uses compact single-letter keys.

<ParamField body="a" type="int32" required>
  **asset** — The integer contract ID identifying which perpetual to trade.
</ParamField>

<ParamField body="b" type="boolean" required>
  **isBuy** — `true` to open a buy/long position; `false` to open a sell/short position.
</ParamField>

<ParamField body="p" type="string">
  **price** — Limit price as a decimal string (e.g. `"100"`). Required for limit orders. Omit entirely for market orders.
</ParamField>

<ParamField body="s" type="string" required>
  **size** — Order quantity as a decimal string (e.g. `"10"`). Must be positive.
</ParamField>

<ParamField body="r" type="boolean" required>
  **reduceOnly** — When `true`, the order only reduces an existing position and will never increase or open a new one. Set to `false` for standard orders.
</ParamField>

<ParamField body="t" type="object" required>
  **orderType** — Specifies the execution type and time-in-force. See the order type formats table below.
</ParamField>

<ParamField body="c" type="string">
  **clientOrderId** — An int64 decimal string you assign for your own tracking (e.g. `"1778572951477"`). Use this value later with `cancelByCloid` to cancel by your own ID without needing the exchange-assigned `oid`.
</ParamField>

## Order Types

| Type      | Format                    | Description                                                                            |
| --------- | ------------------------- | -------------------------------------------------------------------------------------- |
| Limit GTC | `{"limit":{"tif":"Gtc"}}` | **Good-til-cancel** — rests in the book until filled or explicitly cancelled           |
| Limit IOC | `{"limit":{"tif":"Ioc"}}` | **Immediate-or-cancel** — fills whatever is available instantly, cancels the remainder |
| Limit ALO | `{"limit":{"tif":"Alo"}}` | **Add-liquidity-only (post-only)** — rejected if it would immediately cross the spread |
| Market    | `{"market":{}}`           | Executes at the best available price; omit `p` when using this type                    |

## Responses

You will receive one status entry per order in the same index order as your request.

<Tabs>
  <Tab title="Resting (Queued)">
    The limit order was accepted and is waiting in the order book for a match.

    ```json theme={"system"}
    {
      "status": "ok",
      "response": {
        "type": "order",
        "data": {
          "statuses": [
            { "resting": { "oid": 1 } }
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Filled Immediately">
    The order matched against existing liquidity and was fully or partially filled on arrival.

    ```json theme={"system"}
    {
      "status": "ok",
      "response": {
        "type": "order",
        "data": {
          "statuses": [
            { "filled": { "totalSz": "5", "avgPx": "100", "oid": 2 } }
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Rejected">
    The order was rejected. The `error` string explains the reason.

    ```json theme={"system"}
    {
      "status": "ok",
      "response": {
        "type": "order",
        "data": {
          "statuses": [
            { "error": "size must be positive" }
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Response Fields

<ResponseField name="resting.oid" type="int64">
  Exchange-assigned order ID for an order that is now resting in the book. Store this value to cancel the order later via the `cancel` action.
</ResponseField>

<ResponseField name="filled.oid" type="int64">
  Exchange-assigned order ID for an order that filled immediately.
</ResponseField>

<ResponseField name="filled.totalSz" type="string">
  Total quantity filled, as a decimal string.
</ResponseField>

<ResponseField name="filled.avgPx" type="string">
  Average fill price across all matched lots, as a decimal string.
</ResponseField>

<ResponseField name="error" type="string">
  Rejection reason when the order could not be placed or filled.
</ResponseField>

## Known Order Errors

| Error                                | Cause                                                                                                    |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| `size must be positive`              | The submitted quantity is zero or negative                                                               |
| `price 99999 exceeds maxTicks 10000` | The limit price exceeds the contract's allowed maximum tick                                              |
| `share margin group is FROZEN`       | Account is in Portfolio margin mode and the share group is frozen; only `reduceOnly` orders are accepted |

<Note>
  For accounts using **Portfolio (PORTFOLIO) margin mode**, the system automatically draws from the shared margin pool for all contracts in the same share group. You do not need to include any additional fields in the order request to opt into this behavior.
</Note>