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 canceled 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 canceled 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 canceled and the amountRemaining is returned to your balance.
• canceledFOK: the amount could not be filled against existing orders. The order is canceled and the onHold currency is processed.
• canceledMarketProtection: Bitvavo cancelled the order because the spread is too high.
• canceledPostOnly: Bitvavo canceled 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. You cannot create, update, or cancel orders.
• auction: in transition from closed to open. You cannot create market orders. You can create other order types, but there is still no matching.
• auctionMatching: the opening price is calculated. Orders created during the auction phase that meet the final opening price are matched and executed.
• cancelOnly: you can only cancel orders and cannot create or update orders.

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.

Price protection

Bitvavo enforces a set of pre-trade checks to safeguard market integrity, maintain orderly markets, and protect customers from clearly erroneous trades. These checks are always active and protect users and the order book from fat finger errors, unintended market behavior, or manipulative actions.

The following checks are always active:

• Placement price protection: Good-Till-Canceled (GTC) limit orders outside the acceptable price range are canceled. For instance, if the BTC-EUR mid-point price is 100,000€ (the average between the best bid and best ask in the order book) and the threshold multiplier is 5, buy orders below 20,000€ and sell orders above 500,000€ are automatically canceled.
• Execution price protection: Good-Till-Canceled (GTC), Immediate-or-Cancel (IOC), and Fill-or-Kill (FOK) limit orders outside the current market range are canceled. For example, if the BTC-EUR mid-point price is 100,000€ and the threshold is 80%, buy orders above 180,000€ and sell orders below 20,000€ are canceled.
• Spread price protection: Market orders are prevented from executing at prices outside the acceptable range. For example, the best bid in BTC-EUR is 100,000€ and the threshold is 4%. The sell orders in the book are 1BTC at 100,010€, 5BTC at 102,000€, 1BTC at 103,000€ and 10BTC at 105,000€. In a market order to buy 10BTC, 1BTC is filled at 100,010€, 5BTC at 102,000€, 1BTC at 103,000€, and the remaining 4BTC are canceled.
• Reference price protection: Orders outside the acceptable price range compared to the index price are partially or fully canceled. For example, the reference protection threshold is 10% and the reference price is 100,000€. The sell orders in the book are 1BTC at 100,010€, 5BTC at 102,000€, 1BTC at 103,000€ and 10BTC at 111,000€. A limit order to buy 10 BTC at 115,000€, fills for 1BTC at 100,010€, 5BTC at 102,000€, and 1BTC at 103,000€ and the remaining 3BTC are canceled.

When canceled by a price protection check, orders end up in the status specific to the check that canceled them.

Next steps

• Create an order
• Update an order