> For the complete documentation index, see [llms.txt](https://docs.pangolin.exchange/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pangolin.exchange/pangoperps/trading-api/order-management/create-order.md).

# Create Order

Submit a new PangoPerps order with the selected type, side, size, and execution options.

### Endpoint

`POST /v1/order — Mainnet: https://api.orderly.org/v1/order; Testnet: https://testnet-api.orderly.org/v1/order`

**Request limit:** 10 requests per second.

The endpoint accepts a new order and returns an order-created result. Use the private account stream to receive later execution updates. Requests require an API key with the `trading` scope.

### Authentication headers

Send the signed-request headers with the JSON request. These header names are protocol fields and must be kept exactly as shown.

* `orderly-timestamp` — required; signed request time in milliseconds.
* `orderly-account-id` — required; account that owns the request.
* `orderly-key` — required; public API key.
* `orderly-signature` — required; signature generated for the request.
* `x-recv-window` — optional; adjusts the request timeout window, in milliseconds.
* `Content-Type: application/json`

### Request body

Content type: `application/json`

* `symbol` (string, required) — market identifier, for example `PERP_ETH_USDC`.
* `order_type` (string, required) — one of `LIMIT`, `MARKET`, `IOC`, `FOK`, `POST_ONLY`, `ASK`, or `BID`.
* `side` (string, required) — `BUY` or `SELL`.
* `client_order_id` (string, optional) — client-defined identifier, up to 36 characters. Hyphens are allowed, but not as the first character. It must be unique among open orders; a duplicate is rejected while the earlier order remains incomplete.
* client\_order\_id defaults to null. Reuse the same identifier only after the earlier order has completed.
* `order_price` (number) — required except for `MARKET`, `ASK`, and `BID` orders.
* `order_quantity` (number) — order size in base quantity. Quantity precision is limited to 8 decimal places.
* `order_amount` (number) — quote-currency size for `MARKET`, `ASK`, and `BID` orders.
* `visible_quantity` (number, optional) — maximum quantity displayed in the book; defaults to `order_quantity`. It cannot be negative or exceed the total quantity. A value of `0` hides the order. It is not supported for `POST_ONLY`; `MARKET`, `IOC`, and `FOK` orders are not displayed because they execute or cancel immediately.
* `reduce_only` (boolean, optional) — restricts the order to reducing an existing position; defaults to `false`.
* `slippage` (number, optional) — for `MARKET` orders, execution is blocked when the slippage exceeds this value.
* `order_tag` (string, optional) — attach a referral code or custom-fee tag. Custom-fee tags use `enum:<broker_id>:<enum_id>`; for PangoPerps, use `enum:pangoperps:<enum_id>`. The tag can be up to 128 characters and cannot be changed after placement. The legacy `enum:<enum_id>` format applies only to orders accepted before the format change.
* Referral and custom-fee behavior: a plain referral code such as REFERRAL2026 overrides the existing referral relationship. A custom-fee tag such as enum:pangoperps:GRID\_PRO adds the fee configured for PangoPerps and preserves that relationship.
* `level` (integer, optional) — a price level from `0` to `4`; only valid with `ASK` or `BID`.
* `post_only_adjust` (boolean, optional) — for `POST_ONLY` orders, move the price one tick closer to the current best price.
* `margin_mode` (string, optional) — `CROSS` or `ISOLATED`; defaults to the symbol’s current margin mode.

### Order behavior

* `MARKET` orders match available book liquidity until filled. Any remainder is cancelled if the book is exhausted or execution would pass the market’s price-range limit.
* `IOC` orders execute what is available at `order_price` and cancel any unfilled remainder.
* `FOK` orders execute only when the full quantity can be filled at `order_price`; otherwise the request is cancelled without a fill.
* `POST_ONLY` orders are cancelled if placement would immediately trade against displayed maker liquidity. If the only match is hidden liquidity at that level, the incoming post-only order is treated as maker and the resting hidden order as taker.
* `ASK` and `BID` orders use the best ask or best bid, respectively, when accepted. `level` selects which of the first five price levels to use.
* For a limit order, `visible_quantity` controls how much appears in the book while the order remains open. Hidden quantity is matched before visible quantity. A hidden portion that trades is treated as taker liquidity and charged the taker fee.
* For ASK and BID orders, the accepted price is guaranteed to be the best ask or best bid at the time of acceptance. The level value is zero-indexed: ASK selects ask0 through ask4, while BID selects bid0 through bid4.

### Successful response

HTTP `200`

The response indicates whether the order was accepted. Watch the account stream for subsequent fill and execution updates.

The 200 response uses application/json. success is a required boolean; Example: true; data is a required object containing order\_id (number, example 13), client\_order\_id (string, example testclientid), order\_type (string, example LIMIT), order\_price (number, example 100.12), order\_quantity (number, example 0.987654), and error\_message (string, example none). timestamp is an integer with the server time in milliseconds (example 1702989203989).

Example 200 response:

```
{
  "success": true,
  "data": {
    "order_id": 13,
    "client_order_id": "testclientid",
    "order_type": "LIMIT",
    "order_price": 100.12,
    "order_quantity": 0.987654,
    "error_message": "none"
  },
  "timestamp": 1702989203989
}
```

Example request (cURL)

```
curl --request POST \
  --url https://api.orderly.org/v1/order \
  --header 'Content-Type: application/json' \
  --header 'orderly-account-id: <orderly-account-id>' \
  --header 'orderly-key: <orderly-key>' \
  --header 'orderly-signature: <orderly-signature>' \
  --header 'orderly-timestamp: <orderly-timestamp>' \
  --data '{
    "symbol": "PERP_ETH_USDC",
    "order_type": "LIMIT",
    "side": "BUY",
    "client_order_id": "testclientid",
    "order_price": 100.12,
    "order_quantity": 0.987654,
    "visible_quantity": 0.5,
    "reduce_only": false,
    "margin_mode": "CROSS",
    "order_tag": "enum:pangoperps:GRID_PRO"
  }'
```

Example response (HTTP 200)

```
{
  "success": true,
  "data": {
    "order_id": 13,
    "client_order_id": "testclientid",
    "order_type": "LIMIT",
    "order_price": 100.12,
    "order_quantity": 0.987654,
    "error_message": "none"
  },
  "timestamp": 1702989203989
}
```
