Every time the top offer of a collection changes (i.e. the 'top bid'), an event is generated. This API is designed to be polled at high frequency.
There are multiple event types, which describe what caused the change in price:
-
new-order> new bid at a higher price -
expiry> the previous top bid expired -
sale> the previous top bid was accepted -
cancel> the previous top bid was cancelled -
balance-change> the top bid was invalidated due NFT no longer available -
approval-change> the top bid was invalidated due to revoked approval -
revalidation> manual revalidation of orders (e.g. after a bug fixed) -
reprice> price update for dynamic orders (e.g. dutch auctions) -
bootstrap> initial loading of data, so that all tokens have a price associated
Some considerations to keep in mind
-
Due to the complex nature of monitoring off-chain liquidity across multiple marketplaces, including dealing with block re-orgs, events should be considered 'relative' to the perspective of the indexer, ie when they were discovered, rather than when they happened. A more deterministic historical record of price changes is in development, but in the meantime, this method is sufficent for keeping an external system in sync with the best available prices.
-
Events are only generated if the top bid changes. So if a new order or sale happens without changing the top bid, no event is generated. This is more common with 1155 tokens, which have multiple owners and more depth. For this reason, if you need sales data, use the Sales API.