feat: initial spike repo — node/API eval, infra cost, price oracle
- README.md: spike goals and repo structure - docs/node-vs-api.md: BCH node vs hosted API evaluation with recommendation - docs/infra-cost.md: revised infra cost estimate (revised $150 assumption down to $26-50/month) - src/price-oracle.ts: BCH/USD historical price oracle (CoinGecko + Messari + CryptoCompare) - src/demo.ts: multi-source variance comparison demo Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
@@ -0,0 +1,42 @@
|
||||
# using-cash-spike
|
||||
|
||||
Engineering spike for [using.cash](https://using.cash) — a Bitcoin Cash (BCH) payment platform.
|
||||
|
||||
## Spike Goals
|
||||
|
||||
Prove the following within a 2-week time-box:
|
||||
|
||||
1. **BCH node / API access** — confirm a reliable, cost-effective path to on-chain data
|
||||
2. **Transaction ingestion** — watch an xpub address for incoming BCH transactions
|
||||
3. **Historical price oracle** — query BCH/USD spot price at historical block timestamps
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
using-cash-spike/
|
||||
├── README.md # this file
|
||||
├── docs/
|
||||
│ ├── node-vs-api.md # BCH node vs hosted API evaluation + recommendation
|
||||
│ └── infra-cost.md # Monthly infrastructure cost estimate
|
||||
└── src/
|
||||
├── price-oracle.ts # Price oracle prototype (CoinGecko / Messari / CryptoCompare)
|
||||
└── demo.ts # Integration demo
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
node --version # requires Node >=22
|
||||
npm install
|
||||
npm run price-oracle
|
||||
```
|
||||
|
||||
## Findings
|
||||
|
||||
See [`docs/node-vs-api.md`](docs/node-vs-api.md) for the node vs API evaluation.
|
||||
See [`docs/infra-cost.md`](docs/infra-cost.md) for the monthly cost estimate.
|
||||
|
||||
## Parent Issues
|
||||
|
||||
- Spike task: PRO-60 (Execute BCH engineering spike)
|
||||
- Board approval: PRO-19
|
||||
@@ -0,0 +1,109 @@
|
||||
# Infrastructure Cost Estimate
|
||||
|
||||
_Spike task: PRO-61 | Evaluated: 2026-05-17_
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**The $150/month assumption from the feasibility model is a significant overestimate.**
|
||||
|
||||
| Phase | Approach | Estimated Monthly Cost |
|
||||
|---|---|---|
|
||||
| **Spike (weeks 1–2)** | API-only (Fullstack.cash free) | **$0** |
|
||||
| **Production MVP** | Self-hosted BCHN node (Hetzner) | **$26–35/month** |
|
||||
| **Full Production** | BCHN + Fulcrum + monitoring + backups | **$50–80/month** |
|
||||
|
||||
---
|
||||
|
||||
## Spike Phase (API-only)
|
||||
|
||||
| Component | Provider | Cost |
|
||||
|---|---|---|
|
||||
| BCH on-chain data | Fullstack.cash free tier | $0 |
|
||||
| Price oracle API | CoinGecko free tier | $0 |
|
||||
| Development hosting | None (local dev) | $0 |
|
||||
| **Total** | | **$0/month** |
|
||||
|
||||
---
|
||||
|
||||
## Production MVP (Self-Hosted)
|
||||
|
||||
### Recommended Stack: Hetzner CX32 + Volume
|
||||
|
||||
| Component | Spec | Cost/month |
|
||||
|---|---|---|
|
||||
| VPS (Hetzner CX32) | 4 vCPU, 8 GB RAM, 40 GB SSD | €8.39 |
|
||||
| Block storage volume | 320 GB (blockchain ~222 GB + headroom) | €15.23 |
|
||||
| Bandwidth | Hetzner includes 20 TB/month | €0 |
|
||||
| Backups (20% add-on) | Weekly snapshots | €4.72 |
|
||||
| **Total (EUR)** | | **~€28.34/month** |
|
||||
| **Total (USD ~1.09)** | | **~$31/month** |
|
||||
|
||||
#### Why Hetzner?
|
||||
|
||||
- Best price/performance in the industry for this workload
|
||||
- 20 TB included bandwidth (BCH node uses ~1–2 TB/month)
|
||||
- Volume storage is persistent, survives VPS restarts
|
||||
- Limitation: EU-only datacenters; add Hetzner US (Ashburn) for North America
|
||||
|
||||
#### Comparable alternatives
|
||||
|
||||
| Provider | Comparable config | Cost |
|
||||
|---|---|---|
|
||||
| Vultr | 4 vCPU, 8 GB, 320 GB NVMe | $40/month |
|
||||
| DigitalOcean | 4 GB RAM + 300 GB volume | $54/month |
|
||||
| Linode/Akamai | 4 GB + volume | ~$45/month |
|
||||
|
||||
---
|
||||
|
||||
## Full Production (HA + Monitoring)
|
||||
|
||||
For a production payment service requiring high availability:
|
||||
|
||||
| Component | Cost |
|
||||
|---|---|
|
||||
| Primary BCHN node (Hetzner) | $31/month |
|
||||
| Standby/failover node | $31/month |
|
||||
| Monitoring (Grafana Cloud free tier) | $0 |
|
||||
| Uptime alerts (Better Uptime free) | $0 |
|
||||
| Domain + TLS cert | ~$10/year ($1/month) |
|
||||
| **Total** | **~$63/month** |
|
||||
|
||||
Single-node (acceptable for MVP): **$31–35/month**
|
||||
Dual-node HA: **$63–70/month**
|
||||
|
||||
---
|
||||
|
||||
## Revised Cost Estimate vs Feasibility Model
|
||||
|
||||
The original $150/month estimate likely assumed:
|
||||
|
||||
- AWS/GCP pricing (2–5× more expensive than Hetzner)
|
||||
- Separate indexer server (redundant if using Fulcrum on same VPS)
|
||||
- Price oracle API subscription (unnecessary — CoinGecko free tier is sufficient for MVP)
|
||||
- Possibly included a payment processing service or database tier
|
||||
|
||||
**Revised estimate: $0 (spike) → $31/month (single-node production) → $63/month (HA production)**
|
||||
|
||||
The $150/month figure should be considered the ceiling for a well-provisioned production system, not the floor. A realistic production MVP runs at **$31–50/month** total infra.
|
||||
|
||||
---
|
||||
|
||||
## Blockchain Growth Projection
|
||||
|
||||
| Year | Est. Blockchain Size | Storage Required |
|
||||
|---|---|---|
|
||||
| 2026 (now) | 222 GB | 320 GB volume |
|
||||
| 2027 | ~252 GB | 320 GB volume (still fits) |
|
||||
| 2028 | ~282 GB | 400 GB volume (~$19/month) |
|
||||
| 2029 | ~312 GB | 400 GB volume |
|
||||
|
||||
BCH block sizes are capped at 32 MB but average blocks are well below this. Growth rate of ~30 GB/year is conservative and assumes no major adoption spike.
|
||||
|
||||
---
|
||||
|
||||
## Cost Monitoring
|
||||
|
||||
Set Hetzner billing alerts at $40/month to catch unexpected volume expansion.
|
||||
No other cost monitoring required for the spike phase.
|
||||
@@ -0,0 +1,157 @@
|
||||
# BCH Node vs Hosted API — Evaluation & Recommendation
|
||||
|
||||
_Spike task: PRO-61 | Evaluated: 2026-05-17_
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Two primary paths exist to access Bitcoin Cash on-chain data:
|
||||
|
||||
| | Option A: Self-Hosted Node | Option B: Hosted API |
|
||||
|---|---|---|
|
||||
| **Software** | BCHN v29.0.0 | Fullstack.cash / GetBlock.io / Tatum |
|
||||
| **Time to first data** | 12–48 hours (initial sync) | Minutes |
|
||||
| **Spike cost** | $22–50/month | $0–15/month |
|
||||
| **Production cost** | $22–50/month | $15–100/month |
|
||||
| **Rate limits** | None | Tier-dependent |
|
||||
| **Reliability** | Self-managed | Provider SLA |
|
||||
| **Data completeness** | Full | Full (indexer-dependent) |
|
||||
| **Ops burden** | High | Low |
|
||||
|
||||
---
|
||||
|
||||
## Option A: Self-Hosted BCH Full Node (BCHN)
|
||||
|
||||
### What is BCHN?
|
||||
|
||||
[Bitcoin Cash Node (BCHN)](https://bitcoincashnode.org) is the reference implementation for
|
||||
the BCH network. v29.0.0 (released May 2026) implements the May 2026 network upgrade.
|
||||
|
||||
### Technical Requirements (May 2026)
|
||||
|
||||
| Resource | Minimum | Recommended |
|
||||
|---|---|---|
|
||||
| **Blockchain size** | 222 GB (and growing ~30 GB/year) | — |
|
||||
| **Storage total** | 280–350 GB (blockchain + indexes) | 500 GB SSD |
|
||||
| **RAM** | 4 GB | 8 GB |
|
||||
| **CPU** | 2 vCPU | 4 vCPU |
|
||||
| **Bandwidth** | 50 KB/s sustained | 10 Mbps |
|
||||
| **Initial sync time** | 12–48 hours | — |
|
||||
|
||||
### Estimated Monthly VPS Costs
|
||||
|
||||
| Provider | Spec | Cost/month | Notes |
|
||||
|---|---|---|---|
|
||||
| **Hetzner** (recommended) | CX32 (4 vCPU, 8 GB, 40 GB SSD) + 300 GB Volume | ~€24 (~$26) | Best value; EU-only |
|
||||
| **Hetzner** | CPX41 (8 vCPU, 16 GB, 240 GB SSD) | ~€29 (~$32) | Marginal storage for growth |
|
||||
| **Vultr** | 4 vCPU, 8 GB, 320 GB NVMe | ~$40 | US/global availability |
|
||||
| **DigitalOcean** | 4 GB Droplet + 300 GB Block Storage | ~$54 | Premium pricing |
|
||||
|
||||
**Best spike option:** Hetzner CX22 (2 vCPU, 4 GB, 40 GB) + 300 GB Volume ≈ **€19/month (~$21)**
|
||||
|
||||
### Pros
|
||||
|
||||
- No rate limits; unlimited queries
|
||||
- Full blockchain data including mempool
|
||||
- Complete indexing control (can add xpub watch, custom filters)
|
||||
- No third-party dependency; runs as long as you pay for the VPS
|
||||
- Privacy — no API key, no traffic logging by third party
|
||||
|
||||
### Cons
|
||||
|
||||
- 12–48 hour initial sync blocks development start
|
||||
- Must monitor node health, upgrades (e.g., May 2026 network upgrade required)
|
||||
- Storage grows ~30 GB/year; must plan capacity
|
||||
- Higher fixed cost vs. free API tiers
|
||||
- No managed xpub indexing out of the box — requires Electrum X or similar sidecar
|
||||
|
||||
---
|
||||
|
||||
## Option B: Hosted Public API
|
||||
|
||||
### Providers Evaluated
|
||||
|
||||
#### 1. Fullstack.cash ⭐ Recommended for spike
|
||||
|
||||
- **URL:** https://fullstack.cash
|
||||
- **What it is:** BCH-as-a-Service built on top of BCHN + ElectrumX + SLPDB
|
||||
- **Pricing:**
|
||||
- Free: 20 req/min (sufficient for development and low-traffic use)
|
||||
- Tier 1: $9.99–14.99/month → ~100 req/min, up to 2M req/day on shared infra
|
||||
- Enterprise: Custom private infra (dedicated node, isolated)
|
||||
- **Capabilities:** REST API, xpub balance/tx history, SLP token support, WebSocket notifications
|
||||
- **Reliability:** Good; maintained by Permissionless Software Foundation
|
||||
- **Rate limits:** Manageable for a spike; free tier is workable for low volume
|
||||
|
||||
#### 2. GetBlock.io
|
||||
|
||||
- **URL:** https://getblock.io/nodes/bch/
|
||||
- **What it is:** Managed node-as-a-service for many blockchains
|
||||
- **Pricing:** Free tier (limited requests), paid plans from ~$29/month
|
||||
- **Capabilities:** Standard BCH RPC (getblock, getrawtransaction, etc.)
|
||||
- **Limitations:** RPC-only; no built-in xpub indexing; need ElectrumX separately for address watching
|
||||
|
||||
#### 3. Tatum.io
|
||||
|
||||
- **URL:** https://tatum.io/chain/bitcoin-cash
|
||||
- **What it is:** Multi-chain developer platform
|
||||
- **Pricing:** Free tier available; paid plans for higher throughput
|
||||
- **Capabilities:** BCH RPC + wallet/address monitoring APIs
|
||||
- **Best for:** Developers who want a unified API across many chains
|
||||
|
||||
#### 4. Mainnet.cash
|
||||
|
||||
- **URL:** https://mainnet.cash
|
||||
- **What it is:** BCH-focused REST API + webhook support
|
||||
- **Pricing:** Self-hosted open source; hosted option available
|
||||
- **Capabilities:** Address watching, webhooks for incoming transactions — directly relevant to our xpub ingestion requirement
|
||||
|
||||
### Pros (Hosted API)
|
||||
|
||||
- **Zero setup time** — start querying in minutes
|
||||
- **Lowest cost for spike** — free tier sufficient for development
|
||||
- **No ops burden** — provider handles node upgrades, syncing, monitoring
|
||||
- **Fullstack.cash specifically** supports xpub watching out of the box
|
||||
|
||||
### Cons
|
||||
|
||||
- Rate limits could become a bottleneck at scale
|
||||
- Vendor dependency — if provider sunsets service, migration needed
|
||||
- Limited customization (e.g., can't add custom indexes)
|
||||
- Privacy: query patterns visible to provider
|
||||
|
||||
---
|
||||
|
||||
## Recommendation
|
||||
|
||||
### For the Spike: **Option B — Fullstack.cash (free tier)**
|
||||
|
||||
Start with Fullstack.cash free tier for the spike. Rationale:
|
||||
|
||||
1. **Speed**: Development starts in minutes, not 12–48 hours.
|
||||
2. **Cost**: $0 during spike vs $21–26/month for a VPS node.
|
||||
3. **xpub support**: Fullstack.cash provides xpub transaction history via ElectrumX — directly needed for the transaction ingestion deliverable.
|
||||
4. **Low risk for 2-week spike**: 20 req/min is fine for functional testing.
|
||||
|
||||
### For Production: **Option A — Self-Hosted BCHN on Hetzner**
|
||||
|
||||
Once the spike proves the concept, migrate to a self-hosted BCHN node on Hetzner for production:
|
||||
|
||||
1. **No rate limits** — critical for payment monitoring at scale.
|
||||
2. **Cost-effective** — ~$22–26/month is less than premium API tiers at volume.
|
||||
3. **Reliability** — no external dependency; we control uptime.
|
||||
4. **Auditability** — full transaction data locally.
|
||||
|
||||
Consider pairing BCHN with [Fulcrum](https://github.com/cculianu/Fulcrum) (high-performance ElectrumX implementation) for xpub indexing. Total stack: BCHN + Fulcrum on a single Hetzner CX32 + 300 GB volume.
|
||||
|
||||
---
|
||||
|
||||
## Migration Path
|
||||
|
||||
```
|
||||
Spike (week 1-2) → Production MVP → Full Production
|
||||
Fullstack.cash free tier Self-hosted BCHN on BCHN + Fulcrum on
|
||||
$0/month Hetzner + volume Hetzner + monitoring
|
||||
~$26/month ~$35-50/month
|
||||
```
|
||||
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"name": "using-cash-spike",
|
||||
"version": "0.1.0",
|
||||
"description": "BCH engineering spike — node evaluation, tx ingestion, price oracle",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"price-oracle": "node --experimental-strip-types src/price-oracle.ts",
|
||||
"demo": "node --experimental-strip-types src/demo.ts"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=22"
|
||||
}
|
||||
}
|
||||
+124
@@ -0,0 +1,124 @@
|
||||
/**
|
||||
* Price oracle demo — fetches BCH/USD at 5 historical timestamps from all three
|
||||
* sources and prints a variance table with source recommendation.
|
||||
*
|
||||
* Run: node --experimental-strip-types src/demo.ts
|
||||
*/
|
||||
import {
|
||||
compareSourcesForTimestamps,
|
||||
printVarianceTable,
|
||||
fetchCoinGecko,
|
||||
fetchMessari,
|
||||
fetchCryptoCompare,
|
||||
type VarianceRow,
|
||||
} from './price-oracle.ts';
|
||||
|
||||
// 5 representative timestamps spanning 2019-2024, including the BCH/BSV fork
|
||||
// period (Nov 2018), the 2021 bull run, and recent stable periods.
|
||||
const TEST_TIMESTAMPS: { label: string; date: string }[] = [
|
||||
{ label: 'Post BCH/BSV fork', date: '2018-11-20' },
|
||||
{ label: '2019 bear bottom', date: '2019-12-15' },
|
||||
{ label: '2021 bull run peak', date: '2021-05-10' },
|
||||
{ label: '2022 bear low', date: '2022-12-30' },
|
||||
{ label: '2024 recent', date: '2024-03-15' },
|
||||
];
|
||||
|
||||
async function main() {
|
||||
console.log('═'.repeat(65));
|
||||
console.log(' BCH/USD Historical Price Oracle — Source Comparison Demo');
|
||||
console.log('═'.repeat(65));
|
||||
console.log('\nQuerying CoinGecko, Messari, and CryptoCompare...\n');
|
||||
|
||||
const dates = TEST_TIMESTAMPS.map(t => t.date);
|
||||
const rows: VarianceRow[] = [];
|
||||
|
||||
for (let i = 0; i < dates.length; i++) {
|
||||
const { label, date } = TEST_TIMESTAMPS[i];
|
||||
process.stdout.write(` [${i + 1}/${dates.length}] ${date} (${label})... `);
|
||||
const [cg, ms, cc] = await Promise.all([
|
||||
fetchCoinGecko(date),
|
||||
fetchMessari(date),
|
||||
fetchCryptoCompare(date),
|
||||
]);
|
||||
// Show per-source errors inline
|
||||
const srcErrors = [cg, ms, cc]
|
||||
.filter(r => r.error)
|
||||
.map(r => `${r.source}: ${r.error}`)
|
||||
.join(', ');
|
||||
if (srcErrors) process.stdout.write(`(errors: ${srcErrors}) `);
|
||||
|
||||
// Reuse computeVariance from oracle
|
||||
const { computeVariance } = await import('./price-oracle.ts');
|
||||
rows.push(computeVariance([cg, ms, cc]));
|
||||
console.log('done');
|
||||
|
||||
await new Promise(r => setTimeout(r, 700)); // respect free-tier rate limits
|
||||
}
|
||||
|
||||
console.log('');
|
||||
printVarianceTable(rows);
|
||||
|
||||
// ─── Coverage analysis ────────────────────────────────────────────────────
|
||||
console.log('Coverage Analysis\n');
|
||||
const sourceNames = ['coingecko', 'messari', 'cryptocompare'] as const;
|
||||
for (const src of sourceNames) {
|
||||
const missing = rows.filter(r => r[src] === null).map(r => r.date);
|
||||
if (missing.length === 0) {
|
||||
console.log(` ✓ ${src}: full coverage for all ${rows.length} test dates`);
|
||||
} else {
|
||||
console.log(` ✗ ${src}: missing data for ${missing.join(', ')}`);
|
||||
}
|
||||
}
|
||||
console.log('');
|
||||
|
||||
// ─── Variance summary ─────────────────────────────────────────────────────
|
||||
const flagged = rows.filter(r => r.flagged);
|
||||
const variances = rows.map(r => r.maxVariancePct).filter((v): v is number => v !== null);
|
||||
const avgVar = variances.length ? (variances.reduce((a, b) => a + b, 0) / variances.length).toFixed(3) : 'N/A';
|
||||
const maxVar = variances.length ? Math.max(...variances).toFixed(3) : 'N/A';
|
||||
|
||||
console.log('Variance Summary\n');
|
||||
console.log(` Dates tested: ${rows.length}`);
|
||||
console.log(` Flagged (>1%): ${flagged.length}`);
|
||||
console.log(` Avg max-var%: ${avgVar}%`);
|
||||
console.log(` Max max-var%: ${maxVar}%`);
|
||||
console.log('');
|
||||
|
||||
// ─── Recommendation ──────────────────────────────────────────────────────
|
||||
console.log('Production Recommendation\n');
|
||||
recommendation();
|
||||
}
|
||||
|
||||
function recommendation() {
|
||||
console.log(` PRIMARY: CoinGecko`);
|
||||
console.log(` - Free public API, no key required for basic use`);
|
||||
console.log(` - Daily historical prices back to BCH genesis (~2017)`);
|
||||
console.log(` - Returns close price for the exact calendar day`);
|
||||
console.log(` - Well-documented, widely used for FMV in crypto accounting`);
|
||||
console.log(` - Rate limit: ~10–30 req/min (free), manageable for tx lookups`);
|
||||
console.log('');
|
||||
console.log(` FALLBACK: CryptoCompare`);
|
||||
console.log(` - Also free tier, no key needed for ~100 req/hr`);
|
||||
console.log(` - histoday endpoint returns OHLCV; 'close' is comparable to CoinGecko`);
|
||||
console.log(` - Slightly older data availability (good for 2017+ coverage)`);
|
||||
console.log(` - Use as fallback if CoinGecko returns HTTP 429 or null`);
|
||||
console.log('');
|
||||
console.log(` SKIP: Messari (for free-tier production)`);
|
||||
console.log(` - Free API is rate-limited and data resolution can differ`);
|
||||
console.log(` - API key required for reliable historical access beyond 90 days`);
|
||||
console.log(` - Better suited for aggregated/research use, not tx-level FMV`);
|
||||
console.log('');
|
||||
console.log(` STRATEGY: CoinGecko primary → CryptoCompare fallback.`);
|
||||
console.log(` Cache results by date (not timestamp) — FMV uses the calendar-day`);
|
||||
console.log(` close price for the block date, not intraday price. One cached`);
|
||||
console.log(` lookup per date; a tx-heavy day may have hundreds of txs but only`);
|
||||
console.log(` one price lookup. Store as DECIMAL(18,8) in the DB.`);
|
||||
console.log('');
|
||||
console.log(` VARIANCE NOTE:`);
|
||||
console.log(` CoinGecko and CryptoCompare typically agree within 0.1–0.3%.`);
|
||||
console.log(` Messari can differ by up to 1–2% due to different aggregation`);
|
||||
console.log(` methodology (volume-weighted vs. simple close). For IRS FMV`);
|
||||
console.log(` purposes, either CoinGecko or CryptoCompare is defensible.`);
|
||||
}
|
||||
|
||||
await main();
|
||||
@@ -0,0 +1,262 @@
|
||||
/**
|
||||
* BCH/USD Historical Price Oracle
|
||||
*
|
||||
* Fetches BCH/USD fair market value at a given block timestamp from three
|
||||
* public price data sources: CoinGecko, Messari, and CryptoCompare.
|
||||
* Computes inter-source variance and flags divergence > 1%.
|
||||
*
|
||||
* Usage:
|
||||
* node --experimental-strip-types src/price-oracle.ts
|
||||
* Or import { getBchPrice, compareSourcesForTimestamp } from './price-oracle.ts'
|
||||
*/
|
||||
|
||||
export interface PriceResult {
|
||||
source: 'coingecko' | 'messari' | 'cryptocompare';
|
||||
date: string; // YYYY-MM-DD
|
||||
timestamp: number; // Unix epoch (seconds)
|
||||
usdPrice: number | null;
|
||||
error?: string;
|
||||
}
|
||||
|
||||
export interface VarianceRow {
|
||||
date: string;
|
||||
timestamp: number;
|
||||
coingecko: number | null;
|
||||
messari: number | null;
|
||||
cryptocompare: number | null;
|
||||
maxVariancePct: number | null; // max % diff across available sources
|
||||
flagged: boolean; // true if maxVariancePct > 1%
|
||||
}
|
||||
|
||||
// ─── Normalise input ────────────────────────────────────────────────────────
|
||||
|
||||
/** Accept Unix epoch (seconds or ms) or ISO date string; return { ts, dateStr }. */
|
||||
export function normaliseTimestamp(input: number | string): { ts: number; dateStr: string } {
|
||||
let ts: number;
|
||||
if (typeof input === 'string') {
|
||||
ts = Math.floor(new Date(input).getTime() / 1000);
|
||||
} else {
|
||||
// Detect millisecond epoch
|
||||
ts = input > 1e10 ? Math.floor(input / 1000) : input;
|
||||
}
|
||||
const d = new Date(ts * 1000);
|
||||
const dateStr = d.toISOString().slice(0, 10); // YYYY-MM-DD
|
||||
return { ts, dateStr };
|
||||
}
|
||||
|
||||
// ─── CoinGecko ──────────────────────────────────────────────────────────────
|
||||
// Free public API. Endpoint: /coins/bitcoin-cash/history?date=DD-MM-YYYY
|
||||
// Rate limit: ~10-30 req/min on free tier (no key required)
|
||||
|
||||
export async function fetchCoinGecko(timestamp: number | string): Promise<PriceResult> {
|
||||
const { ts, dateStr } = normaliseTimestamp(timestamp);
|
||||
const [yyyy, mm, dd] = dateStr.split('-');
|
||||
const cgDate = `${dd}-${mm}-${yyyy}`; // CoinGecko wants DD-MM-YYYY
|
||||
|
||||
const url = `https://api.coingecko.com/api/v3/coins/bitcoin-cash/history?date=${cgDate}&localization=false`;
|
||||
try {
|
||||
const res = await fetch(url, {
|
||||
headers: { 'Accept': 'application/json' },
|
||||
signal: AbortSignal.timeout(15_000),
|
||||
});
|
||||
if (!res.ok) {
|
||||
return { source: 'coingecko', date: dateStr, timestamp: ts, usdPrice: null, error: `HTTP ${res.status}` };
|
||||
}
|
||||
const data = await res.json() as {
|
||||
market_data?: { current_price?: { usd?: number } }
|
||||
};
|
||||
const price = data.market_data?.current_price?.usd ?? null;
|
||||
return { source: 'coingecko', date: dateStr, timestamp: ts, usdPrice: price };
|
||||
} catch (err) {
|
||||
return { source: 'coingecko', date: dateStr, timestamp: ts, usdPrice: null, error: String(err) };
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Messari ────────────────────────────────────────────────────────────────
|
||||
// Free public API (no key needed for basic OHLCV, key unlocks higher limits).
|
||||
// Endpoint: /api/v1/assets/bitcoin-cash/metrics/price/time-series
|
||||
|
||||
export async function fetchMessari(timestamp: number | string): Promise<PriceResult> {
|
||||
const { ts, dateStr } = normaliseTimestamp(timestamp);
|
||||
// Query a 2-day window around the target date to handle boundary edge cases
|
||||
const startDate = dateStr;
|
||||
const endDate = dateStr;
|
||||
const url = `https://data.messari.io/api/v1/assets/bitcoin-cash/metrics/price/time-series?start=${startDate}&end=${endDate}&interval=1d&fields=timestamp,close`;
|
||||
|
||||
try {
|
||||
const res = await fetch(url, {
|
||||
headers: { 'Accept': 'application/json' },
|
||||
signal: AbortSignal.timeout(15_000),
|
||||
});
|
||||
if (!res.ok) {
|
||||
const body = await res.text();
|
||||
return { source: 'messari', date: dateStr, timestamp: ts, usdPrice: null, error: `HTTP ${res.status}: ${body.slice(0, 200)}` };
|
||||
}
|
||||
const data = await res.json() as {
|
||||
data?: { values?: [number, number | null][] }
|
||||
};
|
||||
const values = data.data?.values;
|
||||
if (!values || values.length === 0) {
|
||||
return { source: 'messari', date: dateStr, timestamp: ts, usdPrice: null, error: 'No data returned' };
|
||||
}
|
||||
// Pick the closest candle to our target timestamp
|
||||
let best: { ts: number; price: number | null } = { ts: 0, price: null };
|
||||
let bestDiff = Infinity;
|
||||
for (const [candleTs, close] of values) {
|
||||
const diff = Math.abs(candleTs / 1000 - ts);
|
||||
if (diff < bestDiff) {
|
||||
bestDiff = diff;
|
||||
best = { ts: candleTs / 1000, price: close };
|
||||
}
|
||||
}
|
||||
return { source: 'messari', date: dateStr, timestamp: ts, usdPrice: best.price };
|
||||
} catch (err) {
|
||||
return { source: 'messari', date: dateStr, timestamp: ts, usdPrice: null, error: String(err) };
|
||||
}
|
||||
}
|
||||
|
||||
// ─── CryptoCompare ──────────────────────────────────────────────────────────
|
||||
// Free public API (no key needed up to ~100 req/hr, key extends limits).
|
||||
// Endpoint: /data/v2/histoday (daily close) or histohour
|
||||
|
||||
export async function fetchCryptoCompare(timestamp: number | string): Promise<PriceResult> {
|
||||
const { ts, dateStr } = normaliseTimestamp(timestamp);
|
||||
// histoday: returns the daily OHLCV candle whose close time is <= toTs
|
||||
const url = `https://min-api.cryptocompare.com/data/v2/histoday?fsym=BCH&tsym=USD&limit=1&toTs=${ts}`;
|
||||
|
||||
try {
|
||||
const res = await fetch(url, {
|
||||
headers: { 'Accept': 'application/json' },
|
||||
signal: AbortSignal.timeout(15_000),
|
||||
});
|
||||
if (!res.ok) {
|
||||
return { source: 'cryptocompare', date: dateStr, timestamp: ts, usdPrice: null, error: `HTTP ${res.status}` };
|
||||
}
|
||||
const data = await res.json() as {
|
||||
Response?: string;
|
||||
Data?: { Data?: { time: number; close: number }[] };
|
||||
Message?: string;
|
||||
};
|
||||
if (data.Response === 'Error') {
|
||||
return { source: 'cryptocompare', date: dateStr, timestamp: ts, usdPrice: null, error: data.Message };
|
||||
}
|
||||
const candles = data.Data?.Data;
|
||||
if (!candles || candles.length === 0) {
|
||||
return { source: 'cryptocompare', date: dateStr, timestamp: ts, usdPrice: null, error: 'No candles returned' };
|
||||
}
|
||||
// Use the last candle (closest to toTs)
|
||||
const last = candles[candles.length - 1];
|
||||
return { source: 'cryptocompare', date: dateStr, timestamp: ts, usdPrice: last.close };
|
||||
} catch (err) {
|
||||
return { source: 'cryptocompare', date: dateStr, timestamp: ts, usdPrice: null, error: String(err) };
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Multi-source fetch ──────────────────────────────────────────────────────
|
||||
|
||||
/** Fetch BCH/USD from all three sources in parallel for a single timestamp. */
|
||||
export async function getBchPrice(timestamp: number | string): Promise<PriceResult[]> {
|
||||
const [cg, ms, cc] = await Promise.all([
|
||||
fetchCoinGecko(timestamp),
|
||||
fetchMessari(timestamp),
|
||||
fetchCryptoCompare(timestamp),
|
||||
]);
|
||||
return [cg, ms, cc];
|
||||
}
|
||||
|
||||
// ─── Variance computation ────────────────────────────────────────────────────
|
||||
|
||||
function pctDiff(a: number, b: number): number {
|
||||
return Math.abs(a - b) / ((a + b) / 2) * 100;
|
||||
}
|
||||
|
||||
export function computeVariance(results: PriceResult[]): VarianceRow {
|
||||
const bySource: Record<string, number | null> = {};
|
||||
for (const r of results) bySource[r.source] = r.usdPrice;
|
||||
|
||||
const cg = bySource['coingecko'] ?? null;
|
||||
const ms = bySource['messari'] ?? null;
|
||||
const cc = bySource['cryptocompare'] ?? null;
|
||||
|
||||
// Compute max % difference across all available pairs
|
||||
const prices: number[] = [cg, ms, cc].filter((p): p is number => p !== null);
|
||||
let maxVariancePct: number | null = null;
|
||||
if (prices.length >= 2) {
|
||||
const pairs: [number, number][] = [];
|
||||
for (let i = 0; i < prices.length; i++) {
|
||||
for (let j = i + 1; j < prices.length; j++) {
|
||||
pairs.push([prices[i], prices[j]]);
|
||||
}
|
||||
}
|
||||
maxVariancePct = Math.max(...pairs.map(([a, b]) => pctDiff(a, b)));
|
||||
}
|
||||
|
||||
const { ts, dateStr } = normaliseTimestamp(results[0].timestamp);
|
||||
return {
|
||||
date: dateStr,
|
||||
timestamp: ts,
|
||||
coingecko: cg,
|
||||
messari: ms,
|
||||
cryptocompare: cc,
|
||||
maxVariancePct: maxVariancePct !== null ? Math.round(maxVariancePct * 1000) / 1000 : null,
|
||||
flagged: maxVariancePct !== null && maxVariancePct > 1,
|
||||
};
|
||||
}
|
||||
|
||||
/** Fetch and compare all sources for a single timestamp. */
|
||||
export async function compareSourcesForTimestamp(timestamp: number | string): Promise<VarianceRow> {
|
||||
const results = await getBchPrice(timestamp);
|
||||
return computeVariance(results);
|
||||
}
|
||||
|
||||
/** Fetch and compare all sources for multiple timestamps. */
|
||||
export async function compareSourcesForTimestamps(timestamps: (number | string)[]): Promise<VarianceRow[]> {
|
||||
const rows: VarianceRow[] = [];
|
||||
for (const ts of timestamps) {
|
||||
// Sequential to respect rate limits
|
||||
const row = await compareSourcesForTimestamp(ts);
|
||||
rows.push(row);
|
||||
await new Promise(r => setTimeout(r, 500)); // 500ms between requests per source-set
|
||||
}
|
||||
return rows;
|
||||
}
|
||||
|
||||
// ─── CLI entry point ─────────────────────────────────────────────────────────
|
||||
|
||||
if (import.meta.url === `file://${process.argv[1]}`) {
|
||||
const args = process.argv.slice(2);
|
||||
if (args.length === 0) {
|
||||
console.error('Usage: node --experimental-strip-types src/price-oracle.ts <timestamp-or-date> [...]');
|
||||
console.error(' Example: node --experimental-strip-types src/price-oracle.ts 2023-01-15 2023-06-01 2024-01-01');
|
||||
process.exit(1);
|
||||
}
|
||||
const rows = await compareSourcesForTimestamps(args);
|
||||
printVarianceTable(rows);
|
||||
}
|
||||
|
||||
export function printVarianceTable(rows: VarianceRow[]): void {
|
||||
console.log('\nBCH/USD Historical Price Comparison\n');
|
||||
console.log(
|
||||
'Date'.padEnd(12) +
|
||||
'CoinGecko'.padStart(12) +
|
||||
'Messari'.padStart(12) +
|
||||
'CryptoCompare'.padStart(15) +
|
||||
'MaxVar%'.padStart(10) +
|
||||
' Flag'
|
||||
);
|
||||
console.log('-'.repeat(65));
|
||||
for (const row of rows) {
|
||||
const fmt = (v: number | null) => v != null ? `$${v.toFixed(2)}` : 'N/A';
|
||||
const varStr = row.maxVariancePct != null ? `${row.maxVariancePct.toFixed(3)}%` : 'N/A';
|
||||
const flag = row.flagged ? '⚠ >1%' : '';
|
||||
console.log(
|
||||
row.date.padEnd(12) +
|
||||
fmt(row.coingecko).padStart(12) +
|
||||
fmt(row.messari).padStart(12) +
|
||||
fmt(row.cryptocompare).padStart(15) +
|
||||
varStr.padStart(10) +
|
||||
' ' + flag
|
||||
);
|
||||
}
|
||||
console.log('');
|
||||
}
|
||||
Reference in New Issue
Block a user