Add daily BTC/USD endpoint with historical caching and Swagger UI

2026-09-30 07:47:14 +02:00
parent 814da02b09
commit e0c81e3be3
10 changed files with 352 additions and 1 deletions
@@ -9,6 +9,33 @@ Bitcoin data backend service. Fetches BTC prices from Binance (WebSocket) and Kr
 | `GET /api/price/ws` | WebSocket — sends HTML fragments with live price updates (HTMX-compatible) |
 | `GET /api/price/latest` | Latest price as JSON |
 | `GET /api/health` | Health check |
+| `GET /api/price/day/:date` | Completed UTC BTC/USD daily OHLC, e.g. `/api/price/day/2020-01-01` |
+| `GET /api/price/day?date=YYYY-MM-DD` | Same daily OHLC endpoint using a query parameter |
+| `GET /api/swagger.json` | Swagger specification |
+| `GET /swagger` | Interactive Swagger UI |
+
+### Daily OHLC
+
+Dates must be valid `YYYY-MM-DD` values strictly before today in UTC. Both
+`kraken_day` and `kraken_day_history` are checked before contacting Kraken.
+Missing recent candles are fetched from the OHLC API and saved in `kraken_day`.
+Older days outside Kraken's 720-candle window are calculated from paginated
+historical trades and saved in `kraken_day_history` for subsequent requests.
+Only trades in `[00:00 UTC, next midnight UTC)` contribute; VWAP is volume-weighted.
+
+Example response (prices and volume are JSON numbers):
+
+```json
+{"date":"2020-01-01","pair":"BTC/USD","open":7200,"high":7300,"low":7100,"close":7250,"vwap":7230.5,"volume":123.45,"trade_count":1000}
+```
+
+Errors are JSON: 400 for invalid, current or future dates, 404 for days without
+trades, and 502 for Kraken failures. Failed calculations are not cached.
+Historical requests wait for completion and can take several minutes; clients
+and reverse proxies need sufficiently long request timeouts. Kraken requests
+have a 60-second per-page timeout and historical pages are spaced one second apart.
+
+The `kraken_day_history` migration runs automatically on application startup.

 ## Quick Start