Looking for a quickstart?
Let's talk pricing. This guide will focus on the two most important Pegasys prices: the mid price and the execution price.
The mid price, in the context of Pegasys, is the price that reflects the ratio of reserves in one or more pairs. There are three ways we can think about this price. Perhaps most simply, it defines the relative value of one token in terms of the other. It also represents the price at which you could theoretically trade an infinitesimal amount (ε) of one token for the other. Finally, it can be interpreted as the current market-clearing or fair value price of the assets.
Let's consider the mid price for DAI-WSYS (that is, the amount of DAI per 1 WSYS).
The simplest way to get the DAI-WSYS mid price is to observe the pair directly:
You may be wondering why we have to construct a route to get the mid price, as opposed to simply getting it from the pair (which, after all, includes all the necessary data). The reason is simple: a route forces us to be opinionated about the direction of trading. Routes consist of one or more pairs, and an input token (which fully defines a trading path). In this case, we passed WSYS as the input token, meaning we're interested in a WSYS -> DAI trade.
Now we understand that the mid price is going to be defined in terms of DAI/WSYS. Not to worry though, if we need the WSYS/DAI price, we can easily invert.
Finally, you may have noticed that we're formatting the price to 6 significant digits. This is because internally, prices are stored as exact-precision fractions, which can be converted to other representations on demand. For a full list of options, see Price.
For the sake of example, let's imagine a direct pair between DAI and WSYS doesn't exist. In order to get a DAI-WSYS mid price we'll need to pick a valid route. Imagine both DAI and WSYS have pairs with a third token, USDC. In that case, we can calculate an indirect mid price through the USDC pairs:
Mid prices are great representations of the current state of a route, but what about trades? It turns out that it makes sense to define another price, the execution price of a trade, as the ratio of assets sent/received.
Imagine we're interested in trading 1 WSYS for DAI:
Notice that we're constructing a trade of 1 WSYS for as much DAI as possible, given the current reserves of the direct pair. The execution price represents the average DAI/WSYS price for this trade. Of course, the reserves of any pair can change every block, which would affect the execution price.
Also notice that we're able to access the next mid price, if the trade were to complete successfully before the reserves changed.