Skip to main content

Cancel on disconnect

In case of network outages, extreme latency, or similar issues your orders can remain open and be filled at unfavorable prices while you are disconnected.

To prevent this, you can use Cancel on disconnect which automatically cancels your open orders if there is no activity from you within a set period of time.

info

You cannot use Cancel on disconnect for market orders.

How it works​

  1. You send a cancelOrdersAfter request to:
    • Create a group identifier for new orders: codGroupId.
    • Set the time countdown timer after which the orders are canceled: expiryAfterSeconds.
  2. You create orders and add that codGroupId in the body of the requests.
  3. You keep sending cancelOrdersAfter requests to reset the countdown timer.
  4. If there is no cancelOrdersAfter message from you before the countdown timer expires, we cancel all open orders with that codGroupId.

Orders that are cancelled on disconnect always have cancelOnDisconnect specified as their restatementReason.

Prerequisites​

Before you start, make sure you have:

Also, be sure to read the Authentication instructions for WebSocket and REST API.

Step 1: Create a codGroupId​

Firstly, you need to create a group identifier that you can specify when creating new orders. This enables Cancel on disconnect for those open orders and sets the countdown timer after which the orders are automatically canceled.

To create a group identifier:

  1. Send either a WebSocket or REST API request to create a codGroupId.
  2. In the body of the request specify:
  • codGroupId: your identifier for a group of orders.
  • expiryAfterSeconds: your countdown timer in seconds after which open orders are canceled. The minimum allowed value is 10.
privateCancelOrdersAfter
{
  "action": "privateCancelOrdersAfter",
  "codGroupId": 1,
  "expiryAfterSeconds": 30,
  "requestId": 1
}
  1. The codGroupId is created with the timeOfExpirySeconds countdown timer in the number of seconds you specified.

You can now specify that codGroupId when creating new orders to enable the Cancel on disconnect.

Step 2: Create orders with the codGroupId​

After you have created a codGroupId, you can create orders as usual with either the WebSocket or REST API.

To add an order to a group:

  1. Send either a WebSocket or REST API request to create an order.
  2. In the body of the request specify the codGroupId parameter with the value you created.
privateCancelOrdersAfter
{
  "action": "privateCreateOrder",
  "requestId": 1,
  "market": "BTC-EUR",
  "side": "buy",
  "orderType": "market",
  "operatorId": 543462,
  "clientOrderId": "2be7d0df-d8dc-7b93-a550-8876f3b393e9",
  "amount": "1.567",
  "amountQuote": "5000",
  "price": "6000",
  "triggerAmount": "4000",
  "triggerType": "price",
  "triggerReference": "lastTrade",
  "timeInForce": "GTC",
  "postOnly": false,
  "selfTradePrevention": "decrementAndCancel",
  "responseRequired": true,
  "codGroupId": 1
}
  1. An order is created in the order book and added to the codGroupId you specified.

Cancel on disconnect is now active for your order. You now have to keep sending requests periodically to reset the countdown timer.

If you want to disable Cancel on disconnect, you need to remove the group.

Step 3: Reset the countdown timer​

To reset the countdown timer you can use the same request that you used to create the codGroupId:

  1. Send either a WebSocket or REST API request.
  2. In the request body, specify the codGroupId you want to send the heartbeat for.
  3. Keep sending requests to before the specified countdown timer expires.
tip

To prevent consuming your rate limits, avoid sending reset messages too often. For example, if you set the expiryAfterSeconds to 30 seconds, we recommend that you send a reset message once every 15 seconds.

For example:

  • You send a WebSocket message:

    privateCancelOrdersAfter
    {
      "action": "privateCancelOrdersAfter",
      "codGroupId": 1,
      "expiryAfterSeconds": 30,
      "requestId": 12
    }

  • If successful, the countdown timer resets and you receive the 200 OK response:

    privateCancelOrdersAfter response
      {
        "action": "privateCancelOrdersAfter",
        "requestId": 12,
        "response": {
          "codGroupId": 1,
          "timeOfExpirySeconds": 17202139111
        }
    }

  • If it fails, the countdown timer does not reset and you receive the 400 Bad Request response:

    • errorCode: this is always 433
    • error: description of the reason. Can be:

      • limit of group ids is reached: the maximum of number of groups

      • invalid group id: the invalid groupId provided

      • invalid expiryAfterSeconds: the invalid value

      error response
      {
        "errorCode":433,
        "error": "limit of group ids is reached: 5"
      }

If this happens, to reset the countdown timer, you need to send a new cancelOrdersAfter message with the correct parameters depending on the rejectionReason you received.

Possible rejection reasons are:

  • LIMIT_REACHED: you have reached the maximum number of groups you can create. Wait for one of the existing groups to expire or remove a group.
  • INVALID_GROUP_ID: check the codGroupId and send the request again.
  • INVALID_EXPIRY_AFTER_SECONDS: check the expiryAfterSeconds value and send the request again.

(Optional) Remove the group​

If you want to disable Cancel on disconnect but keep your orders open, you can remove the group you created. Those orders will no longer have a countdown timer.

However, be aware that removing the group does not automatically remove the codGroupId parameter from those open orders.

This is important because you can reuse the codGroupId to create a new group. If you use the same codGroupId to create a new group, the open orders that already have that codGroupId will not have cancel on disconnect enabled.

To remove a group:

  1. Send either a WebSocket message or REST API request and specify:
    • codGroupId: the group identifier you want to remove.
    • expiryAfterSeconds: set this to 0.
privateCancelOrdersAfter
{
  "action": "privateCancelOrdersAfter",
  "codGroupId": 1,
  "expiryAfterSeconds": 0,
  "requestId": 2
}
  1. If successful, you receive the 200 OK response and your codGroupId is removed. Your orders with that codGroupId stay open in the order book.