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": "0.005"
        },
        "takeProfit": {
          "child": {
            "marketIoc": {}
          },
          "triggerPrice": "0.005"
        }
      },
      "newClientOrderId": "cli-ord-20250101-001",
      "newPriceTicks": "0.005",
      "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

Client idempotency key (required).

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

Target sub-account numeric ID. When omitted, uses caller's 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

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. AMENDED cancels the original order's remaining quantity without a successor; keep tracking old_order_id until its terminal state is confirmed. Unspecified for rejected items.

AMENDED REPLACED

Example AMENDED

clientOrderId string

Client order ID assigned to the successor when available.

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_CANCEL_REJECTED 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

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.

Example 5USXJZmk

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

Assigned successor order ID. Zero for cancel-only outcomes or rejection before assignment.

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	Status	Error	When
unauthenticated	401	Unauthenticated	Authentication required.
permission-denied	403	Permission Denied	Permission denied.
invalid-argument	400	Invalid Argument	Invalid argument.
not-found	404	Not Found	Not found.
unavailable	503	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": "0.005"
        },
        "takeProfit": {
          "child": {
            "marketIoc": {}
          },
          "triggerPrice": "0.005"
        }
      },
      "newClientOrderId": "cli-ord-20250101-001",
      "newPriceTicks": "0.005",
      "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"
}

Polyester is best experienced on desktop.

Request

Responses