Batch Create Order

#Endpoint

POST /v1/batch-order

Request limit: 1 request per second. A request can contain up to 10 orders. Each order included counts toward the overall create-order rate limit. This endpoint requires an API key with the trading scope.

#Authentication headers

Send the signed-request headers with the JSON body.

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

#Request body

The body contains an orders array. Each array item represents one order and can set reduce_only independently. The order item accepts these fields:

• symbol (string, required) — market identifier, such as PERP_ETH_USDC.
• order_type (string, required) — LIMIT, MARKET, IOC, FOK, POST_ONLY, ASK, or BID.
• side (string, required) — BUY or SELL.
• client_order_id (string) — optional client-defined ID, unique among open orders.
• order_price (number) — price for the order; not needed for MARKET, ASK, or BID.
• order_quantity (number) — base-quantity size.
• order_amount (number) — quote-currency size for MARKET, ASK, and BID.
• reduce_only (boolean) — when true, the order can only reduce an existing position. This setting applies independently to each item.
• visible_quantity (number) — quantity displayed in the order book.
• order_tag (string) — optional referral or custom-fee tag. For a PangoPerps custom-fee tag, use enum:pangoperps:<enum_id>.

Order-type execution rules and the detailed field constraints follow the standard order rules described in Create Order

Endpoint environments:

Mainnet: POST https://api.orderly.org/v1/batch-order.

Testnet: POST https://testnet-api.orderly.org/v1/batch-order.

For each order item, client_order_id is optional, limited to 36 characters, allows hyphens except as the first character, and must be unique among open orders.

order_price is required except for MARKET, ASK, and BID. For MARKET, ASK, and BID, order_amount specifies the order size in quote currency. order_quantity specifies base-quantity size, with precision limited to 8 decimal places.

visible_quantity defaults to order_quantity. It cannot be negative or exceed order_quantity; 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. For LIMIT orders, hidden quantity is matched before visible quantity, and hidden fills are charged the taker fee.

client_order_id defaults to null. The same identifier may be reused after the earlier order completes.

order_tag behavior: a plain referral code (for example, REFERRAL2026) overrides the existing referral relationship. A custom-fee tag uses enum:<owning_broker_id>:<enum_id>; for PangoPerps, use enum:pangoperps:<enum_id> (example: enum:pangoperps:GRID_PRO). It adds the custom fee while preserving the referral relationship. New custom-fee tags must use the three-part format; the legacy enum:<enum_id> form is supported only for orders accepted before cutover. Tags are limited to 128 characters and cannot be changed after placement.

margin_mode (string, optional) accepts CROSS or ISOLATED. It defaults to the symbol’s current margin mode and can be set independently for each order in the batch.

reduce_only is set per order item. When true, that item can only reduce an existing position.

margin_mode accepts CROSS or ISOLATED. If omitted, the symbol's current default margin mode is used.

#Example request

curl --request POST \
  --url https://api.orderly.org/v1/batch-order \
  --header 'Content-Type: application/json' \
  --header 'orderly-account-id: <account-id>' \
  --header 'orderly-key: <public-api-key>' \
  --header 'orderly-signature: <signature>' \
  --header 'orderly-timestamp: <timestamp-in-ms>' \
  --data '{
    "orders": [
      {
        "symbol": "PERP_ETH_USDC",
        "order_type": "LIMIT",
        "side": "BUY",
        "client_order_id": "pango-batch-001",
        "order_price": 3000,
        "order_quantity": 0.1,
        "reduce_only": false
      },
      {
        "symbol": "PERP_ETH_USDC",
        "order_type": "LIMIT",
        "side": "SELL",
        "client_order_id": "pango-batch-002",
        "order_price": 3100,
        "order_quantity": 0.1,
        "reduce_only": true
      }
    ]
  }'

#Successful response

HTTP 200. The data.rows array contains one result per order, including its order_id, client_order_id, order_type, order_price, order_quantity, and error_message.

{
  "success": true,
  "data": {
    "rows": [
      {
        "order_id": 13,
        "client_order_id": "pango-batch-001",
        "order_type": "LIMIT",
        "order_price": 3000,
        "order_quantity": 0.1,
        "error_message": "none"
      }
    ]
  },
  "timestamp": 1702989203989
}