Cancel Orders

Removes specified orders from orderbook.

Rate limits

• When no digests are provided: 600 cancellations/min or 10 cancellations/sec per wallet. (weight=1)

• When digests are provided: 600/(total digests) cancellations per minute per wallet. (weight=total digests)

See more details in API Rate limits.

Request

Websocket

Connect

WEBSOCKET [GATEWAY_WEBSOCKET_ENDPOINT]

Message

{
  "cancel_orders": {
    "tx": {
      "sender": "0x7a5ec2748e9065794491a8d29dcf3f9edb8d7c43746573743000000000000000",
      "productIds": [2],
      "digests": ["0x"],
      "nonce": "1"
    },
    "signature": "0x"
  }
}

REST

POST [GATEWAY_REST_ENDPOINT]/execute

Body

{
  "cancel_orders": {
    "tx": {
      "sender": "0x7a5ec2748e9065794491a8d29dcf3f9edb8d7c43746573743000000000000000",
      "productIds": [0],
      "digests": ["0x"],
      "nonce": "1"
    },
    "signature": "0x"
  }
}

Request Parameters

Parameter	Type	Required	Description
tx	object	Yes	Cancel order transaction object. See Signing section for details on the transaction fields.
tx.sender	string	Yes	Hex string representing the subaccount's 32 bytes (address + subaccount name) of the tx sender.
tx.productIds	number[]	Yes	A list of product IDs, corresponding to the product ids of the orders in digests
tx.digests	string[]	Yes	A list of order digests, represented as hex strings.
tx.nonce	string	Yes	Used to differentiate between the same cancellation multiple times. See Signing section for more details.
signature	string	Yes	Signed transaction. See Signing section for more details.

Signing

See more details and examples in our signing page.

The solidity typed data struct that needs to be signed is:

struct Cancellation {
    bytes32 sender;
    uint32[] productIds;
    bytes32[] digests;
    uint64 nonce;
}

sender: a bytes32 sent as a hex string; includes the address and the subaccount identifier

productIds: a list of product IDs, corresponding to the product ids of the orders in digests

digests: a list of order digests, represented as hex strings, for the orders you want to cancel.

nonce: used to differentiate between the same cancellation multiple times, and a user trying to place a cancellation with the same parameters twice. Sent as a string. Encodes two bit of information:

• Most significant 44 bits encoding the recv_time in milliseconds after which the cancellation should be ignored by the matching engine; the engine will accept cancellations where current_time < recv_time <= current_time + 100000

• Least significant 20 bits are a random integer used to avoid hash collisions

  For example, to place a cancellation with a random integer of 1000, and a discard time 50 ms from now, we would send a nonce of (timestamp_ms() + 50) << 20 + 1000

Note: for signing you should always use the data type specified in the solidity struct which might be different from the type sent in the request e.g: nonce should be an uint64 for Signing but should be sent as a string in the final payload.

Response

Success

{
  "status": "success",
  "signature": {signature},
  "data": {
    "cancelled_orders": [
      {
        "product_id": 2,
        "sender": "0x7a5ec2748e9065794491a8d29dcf3f9edb8d7c43746573743000000000000000",
        "price_x18": "20000000000000000000000",
        "amount": "-100000000000000000",
        "expiration": "1686332748",
        "order_type": "post_only",
        "nonce": "1768248100142339392",
        "unfilled_amount": "-100000000000000000",
        "digest": "0x3195a7929feb8307edecf9c045j5ced68925108f0aa305f0ee5773854159377c",
        "placed_at": 1686332708
      },
      ...
    ]
  },
  "request_type": "execute_cancel_orders"
}

Failure

{
  "status": "failure",
  "signature": {signature}
  "error": "{error_msg}"
  "error_code": {error_code}
  "request_type": "execute_cancel_orders"
}