fix(oracle): price from the live book, and expire stale prints

The feed read $0.008546 while cross-venue consensus was $0.009280, low by 8.6%,
and wowdesk's fair guard is anchored to it: the desk was refusing to bid at
prices the market was actually trading, because the feed did not believe those
prices existed.

Two causes, both last-trade artefacts. Nonlogs WOW-BTC last traded at 10 sat
while its book stood 10 bid, 13 ask, so the live midpoint was 11.5 and we were
quoting a print instead. And CexSwap's WOW-XMR sample, which carries $635 of
seven-day volume against Nonlogs' $169 and therefore dominates the average, was
the 24-hour low and 11.5 hours old.

Nonlogs now prefers the midpoint of the best bid and ask, guarded: both sides
present, ask above bid, spread at or under 60%, else fall back to the last
trade. CexSwap publishes no book, so the only guard available there is age, and
a print older than 12 hours no longer anchors the feed.

Measured against live venues: Nonlogs moves $0.007989 to $0.009187, three dead
CexSwap pairs expire, and the feed as a whole moves $0.008546 to $0.008796.

GET /v1/oracle now returns the method, the guard values and the known limits
next to the rates, served by the code that implements them so the description
cannot drift from the behaviour. README carries the same in prose.
This commit is contained in:
jwinterm
2026-09-06 09:18:26 -04:00
parent 074b232267
commit c0802fe5d8
2 changed files with 181 additions and 5 deletions
+58
View File
@@ -55,3 +55,61 @@ curl 'localhost:8787/v2/rates?base=BTC&quote=USD'
## License
MIT.
## The oracle
`GET /v1/oracle` returns the current rates alongside the method that produced
them, the guard values, and the limits we know about. It is served by the code
that implements it, so it cannot drift from the truth the way a separate
document would.
### What it prices, and from what
| Source | Covers | Price basis |
| --- | --- | --- |
| Kraken | majors | spot ticker |
| Nonlogs | niche tickers, BTC and USDT routes | live book midpoint, falling back to last trade |
| CexSwap | niche tickers, all quote routes | last trade in USD, weighted by 7-day USD volume, expiring after 12 hours |
Niche tickers are volume-weighted across the venues that produce a usable
number.
### Why the book midpoint, and not the last trade
A last print says where somebody traded once. On a market doing a few hundred
dollars a day that can be many hours old, and it can sit at the day's extreme.
The midpoint of the current best bid and ask says where you could trade now,
which is what a price feed is being asked.
The case that prompted the change, on 2026-09-06: Nonlogs WOW-BTC last traded
at 10 sat while its book stood 10 bid, 13 ask. The feed said $0.007989; the
market said $0.009187. Meanwhile CexSwap's WOW-XMR print, carrying $635 of
seven-day volume against Nonlogs' $169, was the 24-hour low and 11.5 hours old.
The feed as a whole read $0.008546 against a cross-venue consensus of $0.009280,
low by 8.6%, and a desk quoting against it refused to bid where the market
actually traded.
### Guards
- **Spread.** A midpoint is only meaningful across a real two-sided book, so
both sides must exist, the ask must be above the bid, and the spread must be
at or under 60%. Otherwise the last trade is used. 60% is deliberately loose:
on these venues a 30% spread is ordinary, while dead pairs show books wider
than 1000% that must never set a price.
- **Staleness.** A CexSwap print older than 12 hours is dropped. Its summary
carries no book, so staleness is the only guard available there, and seven
days of volume can be a single old fill.
- **Dead pairs.** Any pair with no volume is ignored entirely. Without this, a
stale print on an untraded pair drags the average; WOW-ETH sat at $0.000087
and WOW-USDT at $0.070 on the same day the coin was worth about $0.009.
### What it does not do
- A midpoint is not depth-weighted. It says where the touch is, not what size
can trade there.
- CexSwap pool prices are not read directly. Only its last trade is available
without an authenticated quote, so between trades that source lags the pool
it describes.
- No source is excluded for being one we quote on ourselves. This is a public
price index and it prices the market as it finds it; a consumer that needs to
exclude its own influence has to do that itself.