Amending orders

Introduction

Amending an order is a common practice for many trading workflows. While you can cancel an open order and submit a new one, amending an order may be a preferred option. There are several fields that can be amended directly in one operation on Vega. These include:

• SIZE
  Amending the size of an order uses the notion of sizeDelta, meaning the user should specify a difference (either positive or negative) to the current size for the order. For example, an existing active order with size 100 could be amended with a size delta of -70 to give a new size after amendment of 30. If the size delta was 45 then the new size after amendment would be 145.

• PRICE
  Amending the price of an order uses price with a nested value. Specifying a non-zero value will attempt to amend the order to that price. For example, an existing active order with price 10000 can be amended with a non-negative price value, such as 5000. After the amendment the order should have a price of 5000. Any part of an order filled at a previous price will remain, only the unfilled portion can be amended.

• TIME IN FORCE (TIF)
  Amending the time in force for an active order can be done for TIME_IN_FORCE_GTC or TIME_IN_FORCE_GTT. TIME_IN_FORCE_FOK or TIME_IN_FORCE_IOC cannot be amended. Any attempt to amend to another time in force value will be rejected. A TIME_IN_FORCE_GTT order must have an expiresAt value but a TIME_IN_FORCE_GTC must not have one. Any attempt to amend to or from the values TIME_IN_FORCE_GFA and TIME_IN_FORCE_GFN will also result in a rejected amendment. See the Trading questions section for more detail on order types.

• EXPIRY
  It is possible to change the expiry time for an order, similar to amending the price, the expiresAt field has a nested value. Specifying a valid non-zero value will attempt to amend the order to that expiry timestamp. See the section on Vega Time for more detail on how to retrieve the current time from the blockchain.

• PEGGED ORDER
  A pegged order can be amended in a similar way to a regular limit order. Their reference, offset and TIF values can all be amended. If amending an order cannot be performed in-place, the order will lose time priority in the order book (but will keep its priority in the list of pegged orders). Amends must be done to the pegged order itself, not any limit orders derived from pegged orders. It is not possible to amend a regular limit order to be a pegged order, and similarly it is also not possible to amend a pegged order to be a regular limit/market order. Please use the peggedReference field to amend the pegged order reference and the peggedOffset field to amend the pegged order offset distance, both can be amended independently. Sample scripts for submitting and amending a pegged order are available on GitHub.

How do I amend an order?

If an order is active and was placed with a party for which you have a public/private key pair, you can amend it. Connect to a Vega API server, and amend an order:

1. Log in to wallet and get public key

See the section on the Wallet service to learn how to log in, list keys and select a public key.

For a working wallet example used by this how-to guide, please visit the API Samples GitHub repo.

2. Prepare an order amendment message

When sending an order amendment request, order, market and party identifiers are required. One of price, size delta, time in force or expiry values should be sent.

pip install --upgrade Vega-API-client

3. Sign and send the transaction

What’s next?

• Made a mistake? Cancel an order
• Retrieve a list of collateral Balances and positions