From 19c8f86862a034b459c9ee6fc922ad13cc60730f Mon Sep 17 00:00:00 2001
From: jackyu66git <jackyu66@gmail.com>
Date: Thu, 2 Jul 2026 15:19:45 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20API=20=E6=89=8B=E5=86=8C=E6=96=B0?=
 =?UTF-8?q?=E5=A2=9E=20Onchain=20Metrics=20=E4=B8=93=E9=A2=98=20+=20endpoi?=
 =?UTF-8?q?nts=20=E8=A1=A8=E6=9B=B4=E6=96=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 data_provider/main.py | 115 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 115 insertions(+)

diff --git a/data_provider/main.py b/data_provider/main.py
index dc09328..7360107 100644
--- a/data_provider/main.py
+++ b/data_provider/main.py
@@ -1366,6 +1366,7 @@ def create_app(provider: DataProvider) -> FastAPI:
     <ul class="nav nav-pills mb-4" id="manualTabs" role="tablist">
         <li class="nav-item"><button class="nav-link active" data-section="overview">Overview</button></li>
         <li class="nav-item"><button class="nav-link" data-section="rest">REST API</button></li>
+        <li class="nav-item"><button class="nav-link" data-section="onchain">Onchain Metrics</button></li>
         <li class="nav-item"><button class="nav-link" data-section="ws">WebSocket</button></li>
         <li class="nav-item"><button class="nav-link" data-section="timeframes">Timeframes</button></li>
         <li class="nav-item"><button class="nav-link" data-section="config">Configuration</button></li>
@@ -1440,6 +1441,9 @@ def create_app(provider: DataProvider) -> FastAPI:
                         <tr><td><span class="method-badge method-GET">GET</span></td><td class="endpoint-path">/health</td><td>Structured health check (JSON)</td></tr>
                         <tr><td><span class="method-badge method-GET">GET</span></td><td class="endpoint-path">/timeframes</td><td>List available base &amp; derived timeframes</td></tr>
                         <tr><td><span class="method-badge method-GET">GET</span></td><td class="endpoint-path">/api/candles</td><td>Fetch OHLCV candles</td></tr>
+                        <tr><td><span class="method-badge method-GET">GET</span></td><td class="endpoint-path">/api/derivatives</td><td>Funding rate, OI, basis</td></tr>
+                        <tr><td><span class="method-badge method-GET">GET</span></td><td class="endpoint-path">/api/onchain/metrics</td><td>On-chain metric time series</td></tr>
+                        <tr><td><span class="method-badge method-GET">GET</span></td><td class="endpoint-path">/api/onchain/latest</td><td>Latest on-chain snapshot</td></tr>
                         <tr><td><span class="method-badge method-WS">WS</span></td><td class="endpoint-path">/ws</td><td>Real-time K-line streaming</td></tr>
                         <tr><td><span class="method-badge method-GET">GET</span></td><td class="endpoint-path">/api-manual</td><td>This page</td></tr>
                     </tbody>
@@ -1539,6 +1543,117 @@ def create_app(provider: DataProvider) -> FastAPI:
         </div>
     </div>
 
+    <!-- ==================== ONCHAIN METRICS ==================== -->
+    <div class="section" id="section-onchain">
+
+        <h5 class="mb-3"><span class="method-badge method-GET">GET</span> /api/onchain/latest</h5>
+        <div class="card endpoint-card">
+            <div class="card-body">
+                <p class="small">获取全部链上指标最新快照。</p>
+                <p><strong>Response</strong> <span class="text-muted small">200 OK</span></p>
+                <pre><code>{{
+  "timestamp": 1704067200000,
+  "btc_netflow": {{
+    "timestamp": 1704067200000,
+    "datetime": "2024-01-01T00:00:00Z",
+    "value": -33361122.64,
+    "sub_value": 1366105343.72,
+    "extra": {{ "inflow_usd": 1366105343.72, "outflow_usd": 1399466466.36 }}
+  }},
+  "stablecoin_supply": {{
+    "timestamp": 1704067200000,
+    "datetime": "2024-01-01T00:00:00Z",
+    "value": 276932114785,
+    "sub_value": 276.93,
+    "extra": {{ "USDT": 184419658464, "USDC": 73258860594, "DAI": 4625356465 }}
+  }},
+  "etf_flow": {{
+    "timestamp": 1704067200000,
+    "datetime": "2024-01-01T00:00:00Z",
+    "value": -296.0,
+    "sub_value": -296000000.0,
+    "extra": {{ "total_million_usd": -296.0, "breakdown": {{ "IBIT": -219.4, "GBTC": -62.8 }} }}
+  }},
+  "mvrv_zscore": {{
+    "timestamp": 1704067200000,
+    "datetime": "2024-01-01T00:00:00Z",
+    "value": -1.3895,
+    "sub_value": 1.1321,
+    "extra": {{ "mvrv_ratio": 1.1321, "rolling_mean": 1.6787, "rolling_stddev": 0.3934 }}
+  }},
+  "sopr": null
+}}</code></pre>
+                <p class="small text-muted">4个免费指标 (netflow/stablecoin/etf/mvrv) 每5分钟自动刷新。SOPR 需 Glassnode API key。</p>
+                <button class="btn btn-sm btn-outline-secondary" onclick="fetch('/api/onchain/latest').then(r=>r.json()).then(d=>alert(JSON.stringify(d,null,2)))">Try it</button>
+            </div>
+        </div>
+
+        <h5 class="mb-3 mt-4"><span class="method-badge method-GET">GET</span> /api/onchain/metrics</h5>
+        <div class="card endpoint-card">
+            <div class="card-body">
+                <p class="small">获取单个链上指标的时间序列。</p>
+                <p><strong>Query Parameters</strong></p>
+                <table class="table table-bordered table-sm">
+                    <thead class="table-light"><tr><th>Param</th><th>Type</th><th>Required</th><th>Default</th><th>Description</th></tr></thead>
+                    <tbody>
+                        <tr><td><code>metric</code></td><td>string</td><td><span class="param-required">Yes</span></td><td>—</td><td>指标: btc_netflow, stablecoin_supply, etf_flow, mvrv_zscore, sopr</td></tr>
+                        <tr><td><code>limit</code></td><td>int</td><td>No</td><td><code>100</code></td><td>返回条数上限 (1-5000)</td></tr>
+                        <tr><td><code>start</code></td><td>int</td><td>No</td><td>—</td><td>起始时间戳(ms)</td></tr>
+                        <tr><td><code>end</code></td><td>int</td><td>No</td><td>—</td><td>结束时间戳(ms)</td></tr>
+                    </tbody>
+                </table>
+                <p><strong>cURL Example</strong></p>
+                <pre><code>curl "http://localhost:80/api/onchain/metrics?metric=btc_netflow&limit=10"
+curl "http://localhost:80/api/onchain/metrics?metric=mvrv_zscore&start=1704067200000&end=1711929600000"</code></pre>
+            </div>
+        </div>
+
+        <h5 class="mb-3 mt-4"><span class="method-badge method-GET">GET</span> /api/onchain/available</h5>
+        <div class="card endpoint-card">
+            <div class="card-body">
+                <p class="small">列出所有指标及其数据量、时间范围。</p>
+                <pre><code>{{
+  "btc_netflow": {{"count": 4015, "has_data": true, "first_ts": "2024-01-01T00:00:00Z", "last_ts": "2026-07-01T00:00:00Z"}},
+  "stablecoin_supply": {{"count": 2, "has_data": true, ...}},
+  "etf_flow": {{"count": 12, "has_data": true, ...}},
+  "mvrv_zscore": {{"count": 4036, "has_data": true, ...}},
+  "sopr": {{"count": 0, "has_data": false, ...}}
+}}</code></pre>
+            </div>
+        </div>
+
+        <h5 class="mb-3 mt-4">指标说明</h5>
+        <div class="card">
+            <div class="card-body p-0">
+                <table class="table table-hover mb-0">
+                    <thead class="table-light"><tr><th>Metric</th><th>来源</th><th>value 含义</th><th>sub_value</th><th>费用</th></tr></thead>
+                    <tbody>
+                        <tr><td><code>btc_netflow</code></td><td>CoinMetrics</td><td>净流量 (USD)</td><td>流入 (USD)</td><td><span class="badge bg-success">免费</span></td></tr>
+                        <tr><td><code>stablecoin_supply</code></td><td>CoinGecko</td><td>总市值 (USD)</td><td>总市值 (B)</td><td><span class="badge bg-success">免费</span></td></tr>
+                        <tr><td><code>etf_flow</code></td><td>Farside</td><td>净流入 (M USD)</td><td>净流入 (USD)</td><td><span class="badge bg-success">免费</span></td></tr>
+                        <tr><td><code>mvrv_zscore</code></td><td>CoinMetrics</td><td>Z-Score</td><td>MVRV Ratio</td><td><span class="badge bg-success">免费</span></td></tr>
+                        <tr><td><code>sopr</code></td><td>Glassnode</td><td>SOPR 值</td><td>—</td><td><span class="badge bg-warning text-dark">需 key</span></td></tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+
+        <h5 class="mb-3 mt-4">CSV 存储</h5>
+        <div class="card">
+            <div class="card-body">
+                <p class="small">数据落盘在 <code>data/onchain/</code> 下，每个指标一个 CSV 文件：</p>
+                <ul class="small">
+                    <li><code>btc_netflow.csv</code> — 交易所净流量 (timestamp, datetime, value, sub_value, extra)</li>
+                    <li><code>stablecoin_supply.csv</code> — 稳定币供应</li>
+                    <li><code>etf_flow.csv</code> — ETF 净流入</li>
+                    <li><code>mvrv_zscore.csv</code> — MVRV Z-Score</li>
+                    <li><code>sopr.csv</code> — SOPR</li>
+                </ul>
+                <p class="small text-muted">每5分钟自动刷新并写盘。extra 字段存 JSON (明细/分解数据)。</p>
+            </div>
+        </div>
+    </div>
+
     <!-- ==================== WEBSOCKET ==================== -->
     <div class="section" id="section-ws">