aiolabs/payroll
9
0
Fork 0
Code Issues 6 Pull requests Projects Releases Packages Wiki Activity Actions

docs: record the measured reach of the rate lookup

Browse source 
Ran the real lookup against both live APIs rather than the stubs. Three
findings worth being written down instead of rediscovered:

- Kraken returns ~721 daily candles, so ~2 years for any pair it quotes.
  EUR and GBP both resolve from it directly; the fallback never fires for
  them.
- CoinGecko's free tier answers within 365 days and returns 401
  Unauthorized beyond it — a plan limit wearing an auth error's clothes,
  not a transient failure. The practical ceiling is therefore ~2 years for
  major pairs and 1 year for anything else, which matters given the ask was
  "historical data for up to even a year".
- The two sources disagree by ~2.5% on the same date (2026-05-15: Kraken
  68,047.50 EUR/BTC, CoinGecko 69,743.26) — one exchange's daily close
  versus a cross-exchange average. Neither is wrong, which is the reason
  the ledger records rate_source beside rate rather than presenting a bare
  figure as canonical.

Refusal behaviour confirmed live: an unknown pair and a 2019 date both come
back None rather than falling through to some other number.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018jy52j9GRZ6XKa1Zt21LLj
This commit is contained in:
Padreug 2026-08-31 21:44:21 +02:00
commit 2e6009b612
2 changed files with 31 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

17
docs/operations.md
View file

@ -67,6 +67,23 @@ exchange providers: those are spot tickers with no date parameter, and the
rate history behind the admin chart is RAM-only, single-currency and wiped
on restart.
How far back this actually reaches, measured against both live APIs:
| payday age | major pair (EUR, GBP, USD…) | currency Kraken doesn't quote |
|---|---|---|
| under 1 year | Kraken | CoinGecko |
| 1–2 years | Kraken | **unavailable** |
| over 2 years | **unavailable** | **unavailable** |
CoinGecko's free tier returns `401 Unauthorized` past 365 days — a plan
limit wearing an auth error's clothes. Unavailable means the period fails
and says so; it never guesses.
The two sources disagree by a couple of percent on the same date (for
2026-05-15: Kraken 68,047.50 EUR/BTC, CoinGecko 69,743.26 — one exchange's
close versus a cross-exchange average). That is why the ledger records
`rate_source` beside `rate` instead of presenting a bare figure as canonical.
Where payroll converts, it hands `create_invoice` a **sat** amount, because
`create_invoice` always prices fiat itself and cannot be told a rate. The
rate used and its source are recorded on the payout row either way — in

14
rates.py
View file

@ -18,6 +18,20 @@ LNbits itself trusts.
addressed by date rather than by series, so it costs one request per date —
fine as a fallback, bad as a default against free-tier rate limits.
Verified coverage (measured against both live APIs, 2026-08-31):
* Kraken returns ~721 daily candles, so **roughly two years** back for any
pair it quotes. EUR and GBP both resolve from it directly.
* CoinGecko's free tier answers within **365 days** and returns `401
Unauthorized` beyond that — a plan limit dressed as an auth error, not a
transient failure. So dates older than ~2 years are unreachable for
everything, and older than a year for currencies Kraken does not quote.
* The two disagree: for 2026-05-15 Kraken gave 68,047.50 EUR/BTC and
CoinGecko 69,743.26, about 2.5% apart — one exchange's daily close versus
a cross-exchange volume-weighted average. Neither is wrong, which is
exactly why the payout records `rate_source` next to `rate` rather than
presenting a bare number as though it were canonical.
Both return None rather than raising. A rate that cannot be established is
a payout that must not happen: the caller records a failed period and lets
a human decide, which is the same thing an underfunded wallet does. The one