From 48e69179b31f692bbea45083b303cca507946444 Mon Sep 17 00:00:00 2001
From: jackyu66git <jackyu666@icloud.com>
Date: Wed, 24 Jun 2026 17:47:42 +0800
Subject: [PATCH] data_provider: add /api/derivatives endpoint documentation

---
 data_provider/api_docs.html | 53 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 52 insertions(+), 1 deletion(-)

diff --git a/data_provider/api_docs.html b/data_provider/api_docs.html
index 2c1c33a..3e6899b 100644
--- a/data_provider/api_docs.html
+++ b/data_provider/api_docs.html
@@ -208,7 +208,7 @@
 
 <header>
   <h1><span>Chan</span> 数据提供商</h1>
-  <p class="subtitle">加密货币 K 线数据 HTTP + WebSocket API</p>
+  <p class="subtitle">加密货币 K 线 + 衍生品数据 HTTP + WebSocket API</p>
   <div class="badge">v1.0.0 &nbsp;|&nbsp; <span>binance</span> &nbsp;|&nbsp; port 9009</div>
 </header>
 
@@ -217,6 +217,7 @@
   <a href="#health">GET /health</a>
   <a href="#timeframes">GET /timeframes</a>
   <a href="#candles">GET /api/candles</a>
+  <a href="#derivatives">GET /api/derivatives</a>
   <a href="#websocket">WebSocket /ws</a>
   <a href="#timeframes-ref">时间周期参考</a>
 </nav>
@@ -378,6 +379,56 @@ GET /api/candles?symbol=SOL/USDT:USDT&tf=4h&limit=50</pre>
 </div>
 </section>
 
+<!-- ============ GET /api/derivatives ============ -->
+<section id="derivatives">
+<h2>查询衍生品数据</h2>
+<div class="endpoint open">
+  <div class="endpoint-header" onclick="this.parentElement.classList.toggle('open')">
+    <span class="method get">GET</span>
+    <span class="endpoint-path">/api/derivatives</span>
+    <span class="endpoint-desc">获取资金费率、持仓量、基差</span>
+  </div>
+  <div class="endpoint-body">
+
+    <table>
+      <tr><th>参数</th><th>类型</th><th>必填</th><th>说明</th></tr>
+      <tr>
+        <td>symbol</td>
+        <td><span class="type">string</span></td>
+        <td>否</td>
+        <td>交易对，默认 <code>BTC/USDT:USDT</code></td>
+      </tr>
+    </table>
+
+    <div class="note">数据每 60 秒自动刷新，落盘到 <code>data/derivatives/</code> 目录。</div>
+
+    <h3>请求示例</h3>
+    <pre><span class="comment"># 获取 BTC 衍生品数据</span>
+GET /api/derivatives?symbol=BTC/USDT:USDT</pre>
+
+    <h3>响应</h3>
+    <pre>{
+  <span class="key">"symbol"</span>:          <span class="string">"BTC/USDT:USDT"</span>,
+  <span class="key">"timestamp"</span>:       <span class="num">1719705600000</span>,
+  <span class="key">"datetime"</span>:        <span class="string">"2024-06-30T00:00:00Z"</span>,
+  <span class="key">"funding_rate"</span>:    <span class="num">0.0001</span>,
+  <span class="key">"open_interest"</span>:   <span class="num">35120000000.0</span>,
+  <span class="key">"oi_change_pct"</span>:   <span class="num">3.52</span>,
+  <span class="key">"basis"</span>:           <span class="num">8.5</span>
+}</pre>
+
+    <h3>字段说明</h3>
+    <table>
+      <tr><th>字段</th><th>类型</th><th>说明</th></tr>
+      <tr><td>funding_rate</td><td>float</td><td>当前资金费率（每 8 小时）</td></tr>
+      <tr><td>open_interest</td><td>float</td><td>当前持仓量（USD）</td></tr>
+      <tr><td>oi_change_pct</td><td>float</td><td>24 小时持仓量变化百分比</td></tr>
+      <tr><td>basis</td><td>float</td><td>期货-现货年化基差（%）</td></tr>
+    </table>
+  </div>
+</div>
+</section>
+
 <!-- ============ WebSocket ============ -->
 <section id="websocket">
 <h2>WebSocket 实时推送</h2>