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.

Alternatively, a market order can also end up in an expired status if there is no match, enough liquidity in the order book, or enough balance in your account.

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, expired
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, expired

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

For orders that are no longer active, we return the following statuses:

• filled: all trades necessary to complete the order have been filled.
• expired: the market order expires because there is no match, enough liquidity in the order book, or enough balance in your account. Also, if you set the timeInForce parameter to IOC or FOK for your order, the order can expire if those conditions are not met.
• canceled: the orderId is removed from the order book by either you or Bitvavo.

Canceled orders

When an order is canceled, you can get the reason in the restatementReason parameter of the response to the following requests:

• REST API: Create order, Update order, Get order, Get orders, and Get open orders.
• WebSocket API: Create order, Update order, Get order, Get orders, Get open orders, and Track your orders.

Depending on the mechanism that canceled the order, the restatementReason parameter returns one of the following values:

• decrementOnSelfTradePrevention: the order was partially filled and the remaining amount was decremented to prevent self-trade.
• cancelOnSelfTradePrevention: we canceled the order to prevent self-trade.
• cancelOnPlacementPriceProtection: placement price protection check canceled the order was canceled because it was outside the acceptable price range.
• cancelOnExecutionPriceProtection: execution price protection check canceled the limit order because it was outside the current market range.
• cancelOnSpreadProtection: spread price protection check canceled the market order because it was outside the acceptable range.
• cancelOnReferencePriceProtection: reference price protection check canceled the order because it was outside the acceptable price range compared to the index price.
• cancelPostOnlyOnAuctionMatching: we canceled the order because it was a post-only order and the market was in the auctionMatching status.
• cancelOnMaintenance: we canceled the order because the market was in the maintenance status.
• cancelOnDisconnect: cancel on disconnect mechanism canceled the order because the connection was lost or there was no heartbeat.
• cancelOnDelisting: the order was canceled because the market was delisted.
• cancelOnLockPlaced: the order was canceled because the market was locked.
• cancelOnAdminRequest: an administrator canceled the order.
• cancelPostOnly: we canceled the order because it was a post-only order and the market was in the cancelOnly status.

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. A market can be in one of the following 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