Order lifecycle

The order lifecycle begins when you create an order and it gets an orderId. Depending on the orderType, it start in either new or awaitingTrigger status. To track your orders status changes in real time, we recommend using the Track your orders WebSocket channel. You can also make requests to our REST API to get all open orders or the status of a single order.

To track the status of your order, you use the orderId, but you can also assign it your own clientOrderId.

When tracking orders, you should:

• Track the orderId and the latest status.
• Check partial fills.
• Check different cancellation reasons.
• Monitor events that follow.

Order types

Bitvavo supports different types of orders to help you manage your trades. To do this from your app, you make requests to create, update, or cancel orders using the REST or WebSocket APIs.

You can create the following types of orders by setting the orderType parameter in your request:

• market: executes immediately by matching with the best-priced and oldest available order in the order book.
• limit: executes only when the market price meets or improves upon the set limit price.
• stopLoss: creates a market order to buy or sell when the trigger price is met to prevent further losses.
• stopLossLimit: triggers a limit order instead of a market order when the price meets the stop level, to prevent further losses.
• takeProfit: creates a market order to buy or sell when the price meets the set level to ensure profits.
• takeProfitLimit: like take profit but uses a limit order instead of a market order to ensure profits.

Order status

From creation to completion, orders move through different statuses. To understand the lifecycle of an order, you need to know that there are two categories of status:

• Active orders: orders that are open and can be filled.
• Completed orders: orders that are filled or canceled by the system or the user.

Order lifecycle

The diagram below shows the sequence of status changes of an order.

info

Orders can be cancelled for different reasons. Check the specific canceled order status to learn more.

Active orders

When you create an order, it gets an orderId. An order starts in either the new status, or awaitingTrigger if you put a condition when to trigger the execution. If it is only partially filled, an order remain active and waits for more matching orders to be completely filled.

The active statuses are:

Status	Description	Can move to
new	The order is in the order book and is waiting for a matching order.	filled , partiallyFilled, canceled
awaitingTrigger	The condition to execute is not met. When met, the status moves to new.	new, canceled
partiallyFilled	A part of the order is filled. More matching orders are needed to fill the order.	filled , canceled

While still active, you can update or cancel your orders.

tip

We recommend using the Track your orders WebSocket channel to track the status of your orders in real time.

Completed orders

Completed orders can either be filled or canceled. Depending on the cancellation reason, you can get different statuses:

• filled: all trades necessary to complete the order have been filled.
• canceled: the orderId is manually removed from the order book.
• canceledSelfTradePrevention: Bitvavo cancelled the order because you are both the buyer and the seller.
• canceledIOC: the filledAmount is filled against existing orders. The rest of the order is cancelled and the amountRemaining is returned to your balance.
• canceledFOK: the amount could not be filled against existing orders. The order is cancelled and the onHold currency is processed.
• canceledMarketProtection: Bitvavo cancelled the order because the spread is too high.
• canceledPostOnly: Bitvavo cancelled the order because it can't be filled in accordance with your postOnly requirements.

Track your orders

The best way to track your partially filled orders is to subscribe to the Track your orders WebSocket channel. You then compare the values of the total amount and the amountRemaining parameters to learn how much of your order has been filled and is still open.

info

You can also use the REST API to get the status of a single or all open orders. However, it is not real-time and can consume your rate limits quickly if your app makes frequent requests.

Prevent self-trade

Self-trading is not allowed on Bitvavo. An order from one account cannot be matched with an order from the same account.

To prevent self-trade, you can set the selfTradePrevention parameter in your order request to one of the following values:

• cancelOldest: cancels the earlier order.
• cancelNewest: cancels the later order.
• cancelBoth: cancels both orders.
• decrementAndCancel: decreases the amount of the conflicting order by the difference between the buy and sell orders. Cancels the lower order.

Market status

The status of the market also impacts the execution of orders. There are three market statuses:

• trading: open for trading.
• halted: closed for trading, for example during maintenance windows.
• auction: in transition from closed to open. You can only create trigger orders. They are matched and then executed when the market opens.

info

To check the status of the market, make a Get markets request to the REST or WebSocket API to receive latest updates about the market status.

Next steps

• Create an order
• Update an order