Trading through code— a limit-sell order partially executed by someone else’s market-buy order

4 min readJan 18, 2021

I will provide a walk through of a situation where a market trade operation, initiated by an user B (a buyer), resulted in a limit order from an user A (a seller) to be executed.

Moment 1 — User A is committed to sell

At moment 1, user A places a limit-sell order. It’s a commitment to sell an amount of bitcoin at a given price. This is an order that won’t be automatically executed. It’s a price P which user A asks for a volume V of bitcoins. The following structure lists the main attributes of this limit-sell order. I kept a few numbers listed to better illustrate:

Side: Sell
OrderType: Limit // the type of order, limit, meaning it says in the book waiting for bidders.
OrderId: 66380326 // The id of the order — generated after it was sent to the market platform
Price: 104000.00 // the price I am asking
Quantity: 0.01570710 // the total volume that I am commited to sell
Instrument: 1 // 1= BITCOIN
Account: “user A”

Once sent, this order stays in the book together with other limit orders of other users. The following picture is a screenshot taken from the market platform after the above other was sent using the API. Notice that the above order is there, listed at position 5 from bottom-up under the red section:

This means that user A’s limit-sell order was not the cheapest. The cheaper one was in fact the first, priced at 193995.72 with a volume of .64857391 bitcoins. Therefore, in order for user A’s limit order to become a trade, to effectivelly be sold, it would be necessary for others to buy all the 4 orders which are available at lower prices.

Moment 2 — user B buys from A using a market-order trading operation

Later, after some time, a trade happened between these two users. At this moment, user B sends a market-buy order to the platform. The structured data of the market-buy order is a bit different. It does not tell the price because it will buy at the book price, starting from the lower. I am not showing the structured order data, like shown above, because I am imagining a scenario where I am able to see user A data but don’t have the user account of user B to look at what happened.

However, using the market’s API, it’s possible to subscribe to a stream of events showing all trades in real-time. The following is the raw information of the trading event between these two users:

TradeDataUpdateEvent: ({“m”:3,”i”:50,”n”:”TradeDataUpdateEvent”,”o”:”[[2523371,1,\”0.00102528\”,\”104000.00\”,66380326,66380331,1610982205708,1,0,false,0]]”})

Breaking the most significant information from it:

trade id: 2523371
volume: 0.00102528
price: 104000.00
order 1: 66380326
order 2: 66380331
datetime: Mon Jan 18 2021 13:03:25 GMT-0200 (Brasilia Summer Time)
direction: 1 (2=down, 1=up, 0=nochange)

Notice that the attribute order 1 shows the id (66380326). We know that this is from user A because we had access to see the structure of the order sent by user A. Although we don’t have the original order data from user B, this trading information shows that the trading was real due to another order — 66380331 — our user B in this story, the one that executed at market price with a market-buy order.

Platform note: you will notice that the above event is named TradeDataUpdateEvent. The subscription to this event depends on a call to an API function named SubscribeTrades.

Other considerations

Some things can be observed from the above situation. First, that the volume which was traded didn’t complete the volume that user A was commited to sell. Second, that in order for the trade to be effective, all the prior limit-sell orders had to be completelly executed. Let’s check each case:

The volume of the trade is different from the limit-sell order

The actual trade event initiated by user B shows a volume that is lower (0.00102528) in contrast with the limit-sell order (0.01570710) commited by user A. In other words, user B bought part of what user A was offering.

This situation is very common. After that, the order will stay there in the book showing the remaining volume which is 0.01570710–0.00102528 = 0.01468182:

All limit-sell orders bellow had to be sold

From the lower limit-sell order to the limit-sell from user A, the book showed 4 orders. For user A’s limit-sell to be partly executed, it means that the 4 cheaper orders had to be sold:

I have annotated “entirely sold” in the sense that they had to be traded among users before the “194000.00” order from user A could be considered.

This technical article is based in the Foxbit API — a Brazilian cryptocurrency trading platform that offers a socket-based API enabling users to buy, sell, and to access other market features such as to read the order book and to monitor recent trades. I am assuming that many of these exchange systems are similar, so my hope is that this article can illustrate what goes on when a trading happens.