Create Order

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