Price scaling in websocket API

[andyjenkinson]

The websocket docs say this, for the response structures where an order price is quoted: "price is the price at which the order had offered to trade, scaled by a factor of 10000."

However in practice this is not the case. For XBT/GBP at least, the price is in fact scaled by a factor of 100. This is actually what is documented in the scale docs, so should I assume that it is 100 in all pairs? As you may appreciate, it is very difficult to test these things without risking money.

[whitslack]

Your confusion is understandable, and perhaps the documentation could go into more detail about how Coinfloor's trade engine handles quantities and prices internally: everything is computed using integer math, no floating-point operations anywhere. From the perspective of the trade engine, there is no notion of "bitcoins" or "pounds"; there are only whole units of opaque, numbered asset types. We define "1 unit of asset 0xF800" to be notionally equivalent to 0.0001 XBT and "1 unit of asset 0xFA20" to be notionally equivalent to 0.01 GBP, but these definitions are matters for humans and are completely outside the scope of the trade engine. Thus, a notional price of "5000 GBP per 1 XBT," expressed in the units of the trade engine, is "500,000 units of asset 0xFA20 per 10,000 units of asset 0xF800," which reduces to "50 units of asset 0xFA20 per unit of asset 0xF800." We couldn't encode this price simply as the integer "50," as then we wouldn't have enough precision in prices, so we build in a scale factor of 10,000, thus making the price encode as the integer "500000."

[andyjenkinson]

Thanks for the reply Matt. Ok I think I get it, it's that the price is expressed relative to the raw currencies than 1 of the base currency. And that price is itself scaled by 10,000 So because the ratio of scale factors for the markets currently available happen to be 10000:100, to get back to "per 1 of base asset" you end up dividing by 100. But this would cease to be true if the quote asset were scaled at, say, 1000, even if the quote currency scale factor stayed at 100.

I'm storing them as mathjs fractions personally as I find it more intuitive, but so long as the docs are good enough I do think integers are a better way to serialise them to stop developers making mistakes with floats - it forces them to think about it.

So in that vein, I definitely find the SCALES and websocket documents to be very confusing when taken together, as the former makes it sound like prices are encoded with a scale of 100 - which they are, but only when relative to the downscaled base currency. I think this needs to be cleared up.

[whitslack]

You've hit it exactly!

As luck would have it, I will be focused almost exclusively on generating internal documentation for Coinfloor over the next couple of weeks, so I will make sure I clarify the scaling nuances in the public API documentation as well.

[andyjenkinson]

Great stuff. Must say I'm having fun on my new project. APIs are my thing :)

[whitslack]

So in that vein, I definitely find the SCALES and websocket documents to be very confusing when taken together, as the former makes it sound like prices are encoded with a scale of 100 - which they are, but only when relative to the downscaled base currency. I think this needs to be cleared up.

Done in c71b34abe45d183e12cb20333341f5e224dfa993.