Cancel Orders

Cancel one or more existing orders by venue order ID or client order ID (CLOID)

Endpoint

POST https://papi.synthetix.io/v1/trade

Request

Request Format

Cancel by venue order ID:

{
  "params": {
    "action": "cancelOrders",
    "subAccountId": "1867542890123456789",
    "orderIds": ["1948058938469519360"]
  },
  "nonce": 1704067200000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  },
  "expiresAfter": 1704067300
}

Cancel by client order ID (CLOID):

{
  "params": {
    "action": "cancelOrders",
    "subAccountId": "1867542890123456789",
    "clientOrderIds": ["my-order-alpha", "my-order-beta"]
  },
  "nonce": 1704067200000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  },
  "expiresAfter": 1704067300
}

Note: orderIds and clientOrderIds are mutually exclusive. Providing both in the same request returns a validation error.

Request Parameters

Parameter	Type	Required	Description
`params`	object	Yes	Parameters object containing method details
`params.action`	string	Yes	Must be `"cancelOrders"`
`params.subAccountId`	string	Yes	SubAccount ID to cancel orders for
`params.orderIds`	array	Conditional	Array of venue order IDs to cancel (strings). Mutually exclusive with `clientOrderIds`.
`params.clientOrderIds`	array	Conditional	Array of client order IDs (CLOIDs) to cancel (strings). Mutually exclusive with `orderIds`.

Exactly one of orderIds or clientOrderIds must be provided.

Parameter	Type	Required	Description
`nonce`	uint64	Yes*	Positive integer nonce (must be incrementing and unique per request)
`signature`	object	Yes	EIP-712 signature object
`expiresAfter`	uint64	No	Unix milliseconds expiration timestamp (5x rate limit on stale cancels)

:::info Common Parameters These are top-level request parameters. The subAccountId parameter is specified within the params object (see each endpoint's parameter table). :::

:::info SubAccountAction Endpoints Endpoints using SubAccountAction signing (getPositions, getOpenOrders, getOrderHistory, getTrades, getFundingPayments, getSubAccount, getSubAccounts, getDelegatedSigners, getBalanceUpdates, getWithdrawableAmounts, getFeeRate, getSnaxpotEpochTickets) do not require the nonce parameter. Only signature and optional expiresAfter are needed. :::

EIP-712 Type Definition

Cancel by venue order ID (orderIds mode) — uses primary type CancelOrders:

const CancelOrdersTypes = {
  CancelOrders: [
    { name: "subAccountId", type: "uint256" },
    { name: "orderIds", type: "uint256[]" },
    { name: "nonce", type: "uint256" },
    { name: "expiresAfter", type: "uint256" }
  ]
}

Note: orderIds is uint256[] in EIP-712, but sent as string[] in the JSON request body.

Cancel by client order ID (clientOrderIds mode) — uses primary type CancelOrdersByCloid:

const CancelOrdersByCloidTypes = {
  CancelOrdersByCloid: [
    { name: "subAccountId", type: "uint256" },
    { name: "clientOrderIds", type: "string[]" },
    { name: "nonce", type: "uint256" },
    { name: "expiresAfter", type: "uint256" }
  ]
}

clientOrderIds is string[] in both the EIP-712 type and the JSON request body. The EIP-712 primary type must match the cancel mode used.

Response

Success Response

{
  "status": "ok",
  "response": {
    "statuses": [
      {
        "canceled": {
          "order": {
            "venueId": "1948058938469519360",
            "clientId": "cli-1948058938469519360"
          },
          "id": "1948058938469519360"
        }
      }
    ]
  },
  "requestId": "5ccf215d37e3ae6d"
}

Success Response - Multiple Orders

{
  "status": "ok",
  "response": {
    "statuses": [
      {
        "canceled": {
          "order": {
            "venueId": "1948058938469519360",
            "clientId": "cli-1948058938469519360"
          },
          "id": "1948058938469519360"
        }
      },
      {
        "canceled": {
          "order": {
            "venueId": "1948058938469519361",
            "clientId": "cli-1948058938469519361"
          },
          "id": "1948058938469519361"
        }
      }
    ]
  },
  "requestId": "5ccf215d37e3ae6d"
}

Error Response

Request-level errors return an error status. For per-item errors in batch requests, see Batch Request Error Handling.

{
  "status": "error",
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Order not found",
    "category": "TRADING",
    "retryable": false
  },
  "requestId": "5ccf215d37e3ae6d",
  "traceId": "abc123def456",
  "timestamp": 1704067200000
}

Partial Success Response

When cancelling multiple orders, some may succeed while others fail:

{
  "status": "ok",
  "response": {
    "statuses": [
      {
        "canceled": {
          "order": {
            "venueId": "1948058938469519360",
            "clientId": "cli-1948058938469519360"
          },
          "id": "1948058938469519360"
        }
      },
      {
        "error": "Order not found",
        "errorCode": "ORDER_NOT_FOUND"
      }
    ]
  },
  "requestId": "5ccf215d37e3ae6d",
  "traceId": "abc123def456",
  "timestamp": 1704067200000
}

Code Examples

Cancel Single Order

{
  "params": {
    "action": "cancelOrders",
    "subAccountId": "1867542890123456789",
    "orderIds": ["1948058938469519360"]
  },
  "nonce": 1704067200000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  },
  "expiresAfter": 1704067300
}

Cancel Multiple Orders

{
  "params": {
    "action": "cancelOrders",
    "subAccountId": "1867542890123456789",
    "orderIds": ["1948058938469519360", "1948058938469519361"]
  },
  "nonce": 1704067200000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  },
  "expiresAfter": 1704067300
}

Cancel by Client Order ID

Use clientOrderIds to cancel orders using the client-assigned IDs set at order placement. The EIP-712 primary type changes to CancelOrdersByCloid.

{
  "params": {
    "action": "cancelOrders",
    "subAccountId": "1867542890123456789",
    "clientOrderIds": ["my-order-alpha", "my-order-beta"]
  },
  "nonce": 1704067200000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  },
  "expiresAfter": 1704067300
}

Cancel Behavior

Migration Note: In each status object, use canceled.order.venueId as canonical. canceled.id is deprecated compatibility output.

Only OPEN/PARTIALLY_FILLED orders can be cancelled
Filled portions of partially filled orders remain executed
Cancellation is immediate upon validation
Freed margin becomes available instantly
Cancelling a TWAP parent order automatically cancels any in-flight child chunk orders; the parent transitions to Cancelled status

Order States

State	Can Cancel
OPEN	✅ Yes
PARTIALLY_FILLED	✅ Yes (remaining quantity)
FILLED	❌ No
CANCELLED	❌ No
EXPIRED	❌ No

Validation Rules

nonce must be a positive integer, incrementing and unique per request
Exactly one of orderIds or clientOrderIds must be provided — providing both returns an error
The provided array must contain at least one entry
When using orderIds: each value must be a valid integer (as a string)
When using clientOrderIds: values must not have leading or trailing whitespace
Orders must belong to the requesting account
Must be signed by order owner or authorized delegate
The EIP-712 primary type must match the cancel mode: CancelOrders for orderIds, CancelOrdersByCloid for clientOrderIds

Signing

All trading methods are signed using EIP-712. Each successful trading request will contain:

A piece of structured data that includes the sender address
A signature of the hash of that structured data, signed by the sender

For detailed information on EIP-712 signing, see EIP-712 Signing.

Nonce Management

The nonce system prevents replay attacks and ensures order uniqueness:

Use any positive integer as nonce
Each nonce must be greater than the previous one (incrementing)
Date.now() is a convenient option, not a requirement
If nonce conflicts occur, increment by 1 and retry

:::note SubAccountAction Exception SubAccountAction endpoints (getPositions, getOpenOrders, getOrderHistory, getTrades, getFundingPayments, getSubAccount, getSubAccounts, getDelegatedSigners, getBalanceUpdates, getWithdrawableAmounts, getFeeRate, getSnaxpotEpochTickets) do not require a nonce. Only the signature and optional expiresAfter parameters are needed. :::

Error Handling

Common Errors

Error Code	Description
`ORDER_NOT_FOUND`	Order ID does not exist or not owned by user
`VALIDATION_ERROR`	Order already cancelled or filled
`INVALID_VALUE`	Empty orderIds array or invalid order ID format

Batch Cancel Errors

When cancelling multiple orders, each is processed independently. The response includes a status for each order ID in the same sequence as submitted. See Batch Request Error Handling for details.

Error Code	Description	Retryable
`UNAUTHORIZED`	EIP-712 signature validation failed	No
`VALIDATION_ERROR`	Request validation failed	No
`MISSING_REQUIRED_FIELD`	Required field is missing	No
`INVALID_FORMAT`	Field format is invalid	No
`INVALID_VALUE`	Invalid parameter value	No
`RATE_LIMIT_EXCEEDED`	Too many requests in time window	Yes
`INSUFFICIENT_MARGIN`	Not enough margin for trade	No
`ORDER_NOT_FOUND`	Order does not exist	No
`OPERATION_TIMEOUT`	Operation timed out	Yes