68 lines
2.6 KiB
Markdown
68 lines
2.6 KiB
Markdown
# btcdata
|
|
|
|
Bitcoin data backend service. Fetches BTC prices from Binance (WebSocket) and Kraken (HTTP polling), stores them in PostgreSQL, and exposes a JSON API with WebSocket for live price streaming.
|
|
|
|
## API
|
|
|
|
| Endpoint | Description |
|
|
|---|---|
|
|
| `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
|
|
|
|
```bash
|
|
# Local dev (requires PostgreSQL)
|
|
cp .env.example .env # edit JDBC_URL
|
|
make run # starts on port 4100
|
|
|
|
# Docker
|
|
docker compose up -d # starts on port 4101
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `BTCDATA_PORT` | `4100` | HTTP server port |
|
|
| `JDBC_URL` | — | PostgreSQL connection string |
|
|
| `CORS_ORIGIN` | `*` | Allowed origin for CORS headers |
|
|
|
|
## Data Sources
|
|
|
|
- **Binance** — WebSocket trade stream (`btcusdt@trade`), throttled to 5s writes
|
|
- **Kraken hourly** — OHLC candles polled at HH:01:00 UTC
|
|
- **Kraken daily** — OHLC candles polled at 00:01:00 UTC
|
|
|
|
## Tech Stack
|
|
|
|
Clojure · Kit · Undertow · Reitit · PostgreSQL · conman · Migratus
|