Spot Atomic Amends

Behavior

The amend model is a fast, single phase transaction that enables clients to modify order parameters in-place within the trading engine.

A single order will be maintained across the lifetime of amend transactions. Each amended order will:

• Keep the same order identifiers assigned by Kraken and/or client.
• Keep the execution information on the order for any previous fills.
• Keep queue priority in the order book where possible.

Amending Below Fill Quantity

To keep the behaviour consistent with the client intentions (i.e. not to trade above given order quantity), amending the order quantity to below the filled quantity will be accepted.

The order quantity will be amended to match the filled quantity and the remaining order is canceled back to the client.

In terms of rate limits, if an order is cancelled by an amend it has the standard cancel rate limit penalty.

Identifiers

The order to be amended can be identified by either:

• Kraken order identifier: the Kraken order identifier is unique over all order history and is received following the creation of a new order, e.g. OGYHBI-KTAUP-5TC3HO.
• Client order identifier: cl_ord_id are generated by the client and passed as a parameter on new orders, they are enforced to be unique over open orders and can be a UUID or text string, e.g.2c6be801-1f53-4f79-a0bb-4ea1c95dfae9.

Example: modifying limit price with client order identifier (cl_ord_id parameter).

{
    "method": "amend_order",
    "params": {
        "cl_ord_id": "2c6be801-1f53-4f79-a0bb-4ea1c95dfae9",
        "limit_price": 690795,
        "token": "PM5Qm0MDrS54l657AQAtb7AhrwN30e2LBg1nUYOd6vU"
    }
}

Supported Fields

The atomic amend model allows modification of the price and quantity fields.

• Order limit price.
• Order trigger price.
• Order quantity.
• Display quantity on iceberg orders.

All other order attributes are not amendable. If the order type, margin characteristics or the lifetime attributes (start, end, time-in-force) need to be changed then cancel the existing order and resend a new one.

Post Only

For changes to limit price, an additional post_only attribute can be added to the transaction. The post_only flag will cause the amend to be rejected if the transaction would cause an immediate match in the book. This prevents clients from inadvertently crossing the spread and taking liquidity.

Queue Priority

The matching engine uses a central limit order book (CLOB) model that matches orders on a price-time priority basis. Keeping queue priority can be important, especially for illiquid assets.

The impact of an amend on queue priority depends on which field is amended, see table below.

Field	Amend Up	Amend Down	Notes
Order Quantity	Order placed at back of price queue.	Order maintains position in price queue.
Display Quantity	Displayed order maintains position in the price queue, the next iceberg reload will be at the new display quantity.	Displayed order maintains position in the price queue.	Iceberg orders only.
Order Limit Price	Order placed at back of new price queue.	Order placed at back of new price queue.
Trigger Price	No impact.	No impact.	Trigger based orders are placed in the book after triggering.

Iceberg Order Types

Iceberg orders show display size resting in the price queue with the remaining order quantity hidden. When the display quantity fully fills, the iceberg order appends the more quantity to the back of the visible price queue from the hidden residual.

The iceberg display size parameter is a maximum quantity to show in the book, the amount of quantity in the market at any time can be less than display size but never more. Amending display size will always try to maintain queue priority: amending down will maintain existing queue position and amending up will come into effect next reload cycle.

To avoid very granular trading of iceberg orders, there is a restriction on display size which must be greater than or equal to 1/15 of order remaining size. This validation is performed on amendment of both display quantity and order quantity for iceberg orders.

Chaining of Unacknowledged Requests

For the FIX API, chaining of unacknowledged amends and cancels is fully supported. They are guaranteed to be processed in sequence by the API layer and the trading engine.

For websockets API, the sequence of unacknowledged amends and cancels is not guaranteed. The sequence of transactions is not deterministic, the API hot path depends on the load balancing of processes and threads.

Caveats

• Orders with conditional close terms attached are not supported by the atomic amend model.