OrdersService

Batch Replace Orders

Replace up to 50 orders for one symbol and return an admission receipt for status and private realtime reconciliation.

Method

POST

Path

/v1/orders/replace-batch

Visibility

Authentication required

Authentication

Session token or API key

MFA Requirement

Not required

POST

/v1/orders/replace-batch

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/v1/orders/replace-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": [
    {
      "newAttachedRisk": {
        "oco": false,
        "stopLoss": {
          "child": {
            "marketIoc": {}
          },
          "triggerPrice": "61000.25",
          "triggerPriceSource": "LAST_PRICE"
        },
        "takeProfit": {
          "child": {
            "marketIoc": {}
          },
          "triggerPrice": "61000.25",
          "triggerPriceSource": "LAST_PRICE"
        }
      },
      "newClientOrderId": "cli-ord-20250101-001",
      "newPrice": "61000.25",
      "newQtyScaled": 100000,
      "orderId": "5USXJZmk"
    }
  ],
  "requestId": "request_01J0EXAMPLE",
  "subaccountId": "45LUmqjT",
  "symbol": "BTC-USDT"
}'

Responses

{
  "acceptedCount": 1,
  "acceptedTs": "2025-01-01T00:00:00Z",
  "acceptedTsNs": "1735689600000000000",
  "batchRequestId": "2",
  "rejectedCount": 1,
  "results": [
    {
      "actionTaken": "AMENDED",
      "clientOrderId": "cli-ord-20250101-001",
      "code": "value",
      "error": {
        "code": "BAD_REQUEST",
        "rateLimit": {
          "limit": 100,
          "operationId": "value",
          "policyClass": "AUTH_PUBLIC",
          "policyVersion": 1,
          "reason": "QUOTA_EXCEEDED",
          "refillModel": "CONTINUOUS",
          "remaining": 1,
          "retryAfterMs": 1,
          "scope": "CLIENT_IP"
        },
        "violations": [
          {
            "fieldPath": "value",
            "message": "value",
            "ruleId": "value"
          }
        ]
      },
      "itemIndex": 1,
      "oldOrderId": "5USXJZmk",
      "replacementOrderId": "5USXJZmk",
      "status": "ADMITTED"
    }
  ],
  "status": "ADMITTED"
}

items object[] required

Replacement items.

Edit in JSON

requestId string required

Client idempotency key (required).

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.

symbol string required

Trading pair symbol, e.g. BTC-USDT.

acceptedCount integer (int32)

Number of items admitted and handed to execution.

Example 1

acceptedTs string (date-time)

Server acceptance timestamp.

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

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

Server acceptance timestamp as epoch nanoseconds.

Example 1735689600000000000

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

Server-issued opaque identity used for status and private realtime correlation.

Example 2

rejectedCount integer (int32)

Number of items rejected before execution handoff.

Example 1

8 fields

actionTaken enum

REPLACED admits a successor under replacement_order_id, with queue priority reset. AMENDED keeps the order under old_order_id with no successor: the order is amended in place and keeps its queue priority, or, when the new total quantity is at or below its filled quantity, ends at its filled quantity. Keep tracking old_order_id for an AMENDED item. Not set for rejected items; JSON and REST responses then omit it.

AMENDED REPLACED

Example AMENDED

clientOrderId string

Client order ID assigned to the successor, for a REPLACED item only.

Example cli-ord-20250101-001

code string

Stable rejection code. Empty for admitted items.

Example value

3 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

Example BAD_REQUEST

9 fields

3 fields

itemIndex integer (int32)

Zero-based index in the request.

Example 1

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

Original order targeted by the replacement: the requested order ID, or the order the requested client order ID names. Rejected items keep it too. Unset only when the requested client order ID names no order.

Example 5USXJZmk

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

Assigned successor order ID, for a REPLACED item only. Unset for an AMENDED item, whose order keeps old_order_id, and for rejected items.

Example 5USXJZmk

status enum

Admission result for this item.

ADMITTED REJECTED

Example ADMITTED

status enum

Aggregate admission status.

ADMITTED PARTIALLY_ADMITTED REJECTED

Example ADMITTED

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/replace-batch

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/v1/orders/replace-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": [
    {
      "newAttachedRisk": {
        "oco": false,
        "stopLoss": {
          "child": {
            "marketIoc": {}
          },
          "triggerPrice": "61000.25",
          "triggerPriceSource": "LAST_PRICE"
        },
        "takeProfit": {
          "child": {
            "marketIoc": {}
          },
          "triggerPrice": "61000.25",
          "triggerPriceSource": "LAST_PRICE"
        }
      },
      "newClientOrderId": "cli-ord-20250101-001",
      "newPrice": "61000.25",
      "newQtyScaled": 100000,
      "orderId": "5USXJZmk"
    }
  ],
  "requestId": "request_01J0EXAMPLE",
  "subaccountId": "45LUmqjT",
  "symbol": "BTC-USDT"
}'

Responses

{
  "acceptedCount": 1,
  "acceptedTs": "2025-01-01T00:00:00Z",
  "acceptedTsNs": "1735689600000000000",
  "batchRequestId": "2",
  "rejectedCount": 1,
  "results": [
    {
      "actionTaken": "AMENDED",
      "clientOrderId": "cli-ord-20250101-001",
      "code": "value",
      "error": {
        "code": "BAD_REQUEST",
        "rateLimit": {
          "limit": 100,
          "operationId": "value",
          "policyClass": "AUTH_PUBLIC",
          "policyVersion": 1,
          "reason": "QUOTA_EXCEEDED",
          "refillModel": "CONTINUOUS",
          "remaining": 1,
          "retryAfterMs": 1,
          "scope": "CLIENT_IP"
        },
        "violations": [
          {
            "fieldPath": "value",
            "message": "value",
            "ruleId": "value"
          }
        ]
      },
      "itemIndex": 1,
      "oldOrderId": "5USXJZmk",
      "replacementOrderId": "5USXJZmk",
      "status": "ADMITTED"
    }
  ],
  "status": "ADMITTED"
}