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"],
    "source": "direct"
  },
  "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"],
    "source": "direct"
  },
  "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`.
`params.source`	string	No	Request source identifier for tracking and rebates (max 100 characters). Use `"direct"` for generic integrations

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, getOrdersHistory, getTrades, getFundingPayments, getSubAccount, getSubAccounts, getDelegatedSigners, getBalanceUpdates) 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",
        "order": { "venueId": "0", "clientId": "" }
      }
    ]
  },
  "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

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, getOrdersHistory, getTrades, getFundingPayments, getSubAccount, getSubAccounts, getDelegatedSigners, getBalanceUpdates) 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