OrdersService

Batch Create Orders

Create up to 20 orders in a single request with accepted or rejected outcomes for each item. Supports mixed symbols and attached risk payloads.

Method

POST

Path

/v1/orders/batch

Visibility

Authentication required

Authentication

Session token or API key

MFA Requirement

Not required

POST

/v1/orders/batch

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/v1/orders/batch' \
  --header 'Accept: */*' \
  --header 'X-API-KEY-ID: YOUR_API_KEY_ID' \
  --header 'X-API-TIMESTAMP: YOUR_API_TIMESTAMP' \
  --header 'X-API-SIGNATURE: YOUR_API_SIGNATURE' \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "attachedRisk": {
        "oco": false,
        "stopLoss": {
          "child": {
            "marketIoc": {}
          },
          "triggerPrice": "61000.25",
          "triggerPriceSource": "LAST_PRICE"
        },
        "takeProfit": {
          "child": {
            "marketIoc": {}
          },
          "triggerPrice": "61000.25",
          "triggerPriceSource": "LAST_PRICE"
        }
      },
      "baseQty": "0.001",
      "clientOrderId": "cli-ord-20250101-001",
      "feeAsset": "QUOTE",
      "marketIoc": {
        "clientRefPrice": "61000.25",
        "maxSlippageTicks": 1
      },
      "selfTradePreventionMode": "EXPIRE_MAKER",
      "side": "BUY",
      "symbol": "BTC-USDT"
    }
  ],
  "requestId": "request_01J0EXAMPLE",
  "subaccountId": "45LUmqjT"
}'

Responses

{
  "acceptedCount": 1,
  "rejectedCount": 1,
  "results": [
    {
      "accepted": {
        "orderId": "5USXJZmk",
        "resolvedBaseQtyScaled": 100000,
        "stopLossTriggerId": "59VD7Lar",
        "submittedMaxQuoteDebitScaled": 100000000,
        "takeProfitTriggerId": "59VD7Lar",
        "trailingStopTriggerId": "59VD7Lar"
      },
      "clientOrderId": "cli-ord-20250101-001"
    }
  ],
  "ts": "2025-01-01T00:00:00Z",
  "tsNs": "1735689600000000000"
}

items object[] required

Orders to create (max 20). client_order_id is optional per item. For a new request_id, a reused client_order_id rejects only that item with CONFLICT_DUPLICATE_CLIENT_ORDER_ID; other valid items continue.

Edit in JSON

requestId string required

Required account-scoped idempotency key for the entire ordered batch. Reusing it with the same payload within 15 minutes returns each decided item's original result and result time, and retries the items still unresolved, never admitting an already admitted item again. Reusing it with a different payload during that window returns CONFLICT_IDEMPOTENCY_KEY_REUSE. After 15 minutes the ID is free: a repeat is a new request and can place its orders again, so read the items back instead of repeating an older batch.

subaccountId string /^[1-9A…m-z]+$/

Optional public subaccount ID. When omitted, subaccount-scoped API keys use their bound subaccount; other callers use their authenticated root account.

acceptedCount integer (int32)

Number of requested orders that were accepted.

Example 1

rejectedCount integer (int32)

Number of requested orders that were rejected.

Example 1

3 fields

6 fields

clientOrderId string

Echoed client order ID.

Example cli-ord-20250101-001

1 field

4 fields

code enum

Stable error code matching the REST problem+json "code" field.

BAD_REQUEST INVALID_ARGUMENT INSUFFICIENT_FUNDS UNKNOWN_SYMBOL BAD_PRICE BAD_QTY MIN_NOTIONAL QTY_STEP_SIZE CONFLICT_DUPLICATE_CLIENT_ORDER_ID UNAVAILABLE UNAUTHENTICATED PERMISSION_DENIED NOT_FOUND UPSTREAM_ERROR FEE_ASSET_NOT_ALLOWED PAIR_DISABLED ORDER_UNKNOWN INTERNAL_ERROR SUBACCOUNT_INACTIVE POLICY_MARKET_DENY POLICY_MAX_NOTIONAL POLICY_TRADING_HALTED POLICY_SPOT_TRADE_DENY API_KEY_ROOT_SCOPE_ONLY API_KEY_SUB_SCOPE_ONLY API_KEY_SUBACCOUNT_MISMATCH API_KEY_POLICY_REQUIRED API_KEY_UNKNOWN API_KEY_MARKET_DENY PRICE_TICK_SIZE MIN_QTY POST_ONLY_LIMIT_ONLY BATCH_TOO_LARGE POLICY_MAX_OPEN_ORDERS MODIFICATION_REQUIRES_REPLACE CONFLICT_IDEMPOTENCY_KEY_REUSE MARKET_PRICE_UNAVAILABLE PAIR_NOT_LISTED_YET PAIR_DELISTED PAIR_CANCEL_ONLY PAIR_POST_ONLY PAIR_REDUCE_ONLY RISK_LIMIT MARKET_HALTED ACCOUNT_UNKNOWN POST_ONLY_CROSS REDUCE_ONLY_BLOCKED PRICE_BAND_VIOLATION MARKET_CAP_VIOLATION EMPTY_BOOK FOK_INSUFFICIENT_LIQUIDITY ORDER_ALREADY_TERMINAL TRIGGER_PRICE_INVALID TRIGGER_PRICE_SOURCE_UNSUPPORTED TRAILING_DISTANCE_INVALID TRIGGER_NOT_FOUND TRIGGER_STATUS_INVALID TRIGGER_NOT_MODIFIABLE CONFLICT_DUPLICATE_CLIENT_TRIGGER_ID MAX_SLIPPAGE_INVALID STALE_QUOTE VALIDATION_ERROR OVERLOADED MAX_QUOTE_DEBIT_TOO_SMALL RATE_LIMIT_EXCEEDED SUBACCOUNT_READ_FORBIDDEN POLICY_SPOT_READ_DENY API_KEY_SPOT_READ_DENY CANCEL_REQUEST_EXPIRED MAX_QTY MAX_NOTIONAL QTY_AT_OR_BELOW_FILLED GATEWAY_MISCONFIGURED INVALID_ORDER_ID CHILD_QTY_RAISE_NOT_ALLOWED ATTACHED_RISK_NOT_SUPPORTED SETTLEMENT_BACKLOGGED PRICE_LEVEL_QUANTITY_LIMIT MARKET_QUOTE_STALE MARKET_QUOTE_UNHEALTHY INVALID_TIME_IN_FORCE QUICKSWAP_NOT_PERMITTED DUPLICATE_ORDER_ID MAX_OPEN_ORDERS_TOTAL STP_MODE_NOT_ALLOWED PAIR_BACKLOGGED PRICE_LEVELS_EXHAUSTED CLIENT_ORDER_IDS_EXHAUSTED ORDER_ID_CONFLICT INVALID_SIDE INVALID_ORDER_TYPE INVALID_STP_MODE INVALID_ORDER_FLAGS BATCH_OTHER_ITEM_INVALID REPLACE_ONTO_OWN_ID INVALID_CLIENT_ORDER_ID ORDER_SEQUENCE_EXHAUSTED INVALID_HANDLING_MODE FEE_SCHEDULE_UNAVAILABLE POLICY_UNAVAILABLE CANCEL_ALL_AFTER_TIMEOUT_INVALID CANCEL_SCOPE_TOO_LARGE RATE_LIMIT_POLICY_UNAVAILABLE SYSTEM_RATE_LIMITED ORDER_MODIFY_IN_PROGRESS ORDER_PLACEMENT_PENDING INVALID_MODIFY_BEHAVIOR BATCH_REPLACE_ONLY_REQUIRED BATCH_SINGLE_SYMBOL_REQUIRED REQUEST_RECEIPTS_EXHAUSTED INTENT_ID_INVALID DRY_RUN_INVALID CANCEL_ALL_AFTER_SCOPE_CONFLICT NEW_ACCOUNT_CAPACITY_REACHED TRIGGER_CHILD_PRICE_NOT_MODIFIABLE TRIGGER_GENERATIONS_EXHAUSTED TRIGGER_CONTROL_SHARE_EXHAUSTED TRIGGER_CONTROLS_BUSY TRIGGER_TYPE_NOT_SUPPORTED INVALID_TRIGGER_TYPE TRIGGER_DIRECTION_INVALID TRIGGER_QTY_INVALID TRIGGER_BUY_REQUIRES_LIMIT ACCOUNT_ROUTING_INVALID TRIGGER_LIMIT_EXCEEDED TRIGGER_CONTROL_IN_PROGRESS TRIGGER_PATCH_EMPTY CLIENT_TRIGGER_ID_INVALID TRIGGER_ACTIVATION_PRICE_INVALID SLIPPAGE_TICKS_INVALID SLIPPAGE_BPS_INVALID TRIGGER_CONTROL_OUTCOME_UNKNOWN TRIGGER_CAPACITY_REACHED RESERVATION_CAPACITY_REACHED CLIENT_ORDER_ID_CAPACITY_REACHED ACCOUNT_RESERVATION_LIMIT_REACHED INVALID_TRIGGER_CONTROL TRIGGER_PATCH_NOT_ALLOWED TRIGGER_PATCH_FIELD_UNKNOWN TRIGGER_PATCH_VALUE_UNMASKED TRIGGER_PATCH_PRICE_MODE_INVALID ACCOUNT_ORDERS_SUSPENDED TRAILING_SIDE_NOT_SUPPORTED TRAILING_CHILD_NOT_MARKET TWAP_DURATION_INVALID LIMIT_CHILD_SLIPPAGE_SET SLIPPAGE_BOUNDS_CONFLICT TWAP_INTERVAL_INVALID LADDER_LEVEL_REJECTED LADDER_RANGE_TOO_NARROW LADDER_LEVELS_INVALID ORDER_LIMITS_UNAVAILABLE ORDER_TYPE_NOT_ALLOWED_IN_AUCTION POST_ONLY_NOT_ALLOWED_IN_AUCTION QUICKSWAP_FEE_DETAILS_INCOMPLETE QUICKSWAP_MARKET_NOT_PRICED QUICKSWAP_BROKER_FEE_TERMS_MISMATCH QUICKSWAP_FEE_RECIPIENT_IS_PAYER QUICKSWAP_BROKER_FEE_TERMS_UNAVAILABLE QUICKSWAP_BROKER_ACCOUNT_UNAVAILABLE QUICKSWAP_ACCOUNT_OWNER_UNKNOWN QUICKSWAP_DISABLED QUICKSWAP_ATTACHED_RISK_NOT_ALLOWED QUICKSWAP_ORDER_NOT_MODIFIABLE QUICKSWAP_FEE_TOTAL_TOO_HIGH QUICKSWAP_BROKER_FEE_TERMS_INVALID QUICKSWAP_BROKER_INVALID QUICKSWAP_FEE_SCHEDULE_INVALID QUICKSWAP_MARKET_FEE_INVALID QUICKSWAP_SETUP_INVALID QUICKSWAP_CAPACITY_REACHED ATTACHED_EXIT_WORKING MARKET_TRIGGER_LIMIT_EXCEEDED MARKET_TWAP_LIMIT_EXCEEDED MARKET_LADDER_LIMIT_EXCEEDED CHILD_QTY_EXCEEDS_REMAINING ORDER_CANCEL_OUTCOME_UNKNOWN ORDER_MODIFY_OUTCOME_UNKNOWN ORDER_REPAIRING ACCOUNT_REPAIRING TRIGGER_WOULD_TRIGGER_IMMEDIATELY ORDER_CREATE_OUTCOME_UNKNOWN TRIGGER_CREATE_OUTCOME_UNKNOWN TRIGGER_SYMBOL_MISMATCH MAX_OPEN_ORDERS_PER_PAIR SELF_TRADE_PREVENTED ATTACHED_LEGS_EXCEEDED FEE_ASSET_INVALID FEE_CEILING_INVALID UNSUPPORTED_FIELD_SET TRIGGER_FIRE_LIMIT_REACHED CONDITION_FLAGS_INVALID CONDITION_PARAMETER_SET TWAP_CAPACITY_REACHED CHILD_ORDER_INCONSISTENT

existingOrderId string /^[1-9A…m-z]+$/

Public order ID holding this account's client order ID for a duplicate rejection; omitted when no existing holder is known.

9 fields

3 fields

ts string (date-time)

Server timestamp.

Example 2025-01-01T00:00:00Z

tsNs string /^[0-9]+$/

Server timestamp as epoch nanoseconds (for bots).

Example 1735689600000000000

Possible errors: 5

Key	HTTP status	Connect code	Error	When
unauthenticated	401	unauthenticated	Unauthenticated	Authentication required.
permission-denied	403	permission_denied	Permission Denied	Permission denied.
invalid-argument	400	invalid_argument	Invalid Argument	Invalid argument.
not-found	404	not_found	Not Found	Not found.
unavailable	503	unavailable	Unavailable	Service unavailable.

POST

/v1/orders/batch

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/v1/orders/batch' \
  --header 'Accept: */*' \
  --header 'X-API-KEY-ID: YOUR_API_KEY_ID' \
  --header 'X-API-TIMESTAMP: YOUR_API_TIMESTAMP' \
  --header 'X-API-SIGNATURE: YOUR_API_SIGNATURE' \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "attachedRisk": {
        "oco": false,
        "stopLoss": {
          "child": {
            "marketIoc": {}
          },
          "triggerPrice": "61000.25",
          "triggerPriceSource": "LAST_PRICE"
        },
        "takeProfit": {
          "child": {
            "marketIoc": {}
          },
          "triggerPrice": "61000.25",
          "triggerPriceSource": "LAST_PRICE"
        }
      },
      "baseQty": "0.001",
      "clientOrderId": "cli-ord-20250101-001",
      "feeAsset": "QUOTE",
      "marketIoc": {
        "clientRefPrice": "61000.25",
        "maxSlippageTicks": 1
      },
      "selfTradePreventionMode": "EXPIRE_MAKER",
      "side": "BUY",
      "symbol": "BTC-USDT"
    }
  ],
  "requestId": "request_01J0EXAMPLE",
  "subaccountId": "45LUmqjT"
}'

Responses

{
  "acceptedCount": 1,
  "rejectedCount": 1,
  "results": [
    {
      "accepted": {
        "orderId": "5USXJZmk",
        "resolvedBaseQtyScaled": 100000,
        "stopLossTriggerId": "59VD7Lar",
        "submittedMaxQuoteDebitScaled": 100000000,
        "takeProfitTriggerId": "59VD7Lar",
        "trailingStopTriggerId": "59VD7Lar"
      },
      "clientOrderId": "cli-ord-20250101-001"
    }
  ],
  "ts": "2025-01-01T00:00:00Z",
  "tsNs": "1735689600000000000"
}