API 文件

Base URL：https://quantchaogu.duckdns.org/api · 認證用 X-API-Key header。

認證

把 API key 放在 X-API-Key header 或 Bearer token 都行。Repo 裡內建了 demo key 可以直接試。

# X-API-Key header
curl -H "X-API-Key: qcg_demo_free_0001" \
     https://quantchaogu.duckdns.org/api/v1/data/TaiwanStockPrice?stock_id=2330&limit=5

# Authorization: Bearer
curl -H "Authorization: Bearer qcg_demo_free_0001" ...

每個回應都會帶 X-RateLimit-* 系列 header，方便你抓 quota。

資料集

MVP 共 9 個。前 4 個 Free 可用，後 5 個需要 Lite。

名稱	方案	說明
TaiwanStockPrice	Free	日 K 線（TWSE STOCK_DAY）
TaiwanStockInstitutionalInvestorsBuySell	Free	三大法人買賣超（TWSE T86）
TaiwanStockMonthRevenue	Free	月營收（MOPS）
TaiwanStockFinancialStatement	Free	綜合損益表（MOPS）
TaiwanStockPriceAdj	Lite	還原股價 — Spark 批次計算
TaiwanStockWeekPrice	Lite	週 K — 由日 K 聚合
TaiwanStockMonthPrice	Lite	月 K — 由日 K 聚合
TaiwanStock10Year	Lite	十年線
TaiwanStockMarketValue	Lite	市值表

GET /v1/data/{dataset}

Query 參數：stock_id、start、end、limit（≤10 000，預設 1 000）。

curl -H "X-API-Key: qcg_demo_free_0001" \
  "https://quantchaogu.duckdns.org/api/v1/data/TaiwanStockPrice?stock_id=2330&start=2026-04-01&end=2026-04-30"

# 200 OK
{
  "dataset": "TaiwanStockPrice",
  "tier_used": "free",
  "count": 20,
  "data": [
    { "stock_id": "2330", "trade_date": "2026-04-30",
      "open": "2205.0000", "high": "2215.0000", "low": "2135.0000",
      "close": "2135.0000", "volume": 59584011, ... }
  ]
}

POST /v1/ask · 僅 Plus

自然語言 → Postgres SQL，背後 DeepSeek 翻譯，read-only 執行後回 JSON。中英文都可。

curl -X POST -H "X-API-Key: qcg_demo_plus_0003" \
     -H "Content-Type: application/json" \
     -d '{"question": "2330 在 2026 年 4 月最高收盤價是哪天"}' \
     https://quantchaogu.duckdns.org/api/v1/ask

# 200 OK
{
  "question": "2330 在 2026 年 4 月最高收盤價是哪天",
  "sql": "SELECT trade_date, close FROM taiwan_stock_price
          WHERE stock_id = '2330' AND trade_date BETWEEN '2026-04-01' AND '2026-04-30'
          ORDER BY close DESC LIMIT 1",
  "provider": "deepseek",
  "model": "deepseek-chat",
  "count": 1,
  "data": [{ "trade_date": "2026-04-27", "close": "2265.0000" }]
}

速率限制

· Free — 600 req/hour
· Lite — 3 000 req/hour
· Plus — 10 000 req/hour

429 回應同樣帶 X-RateLimit-* header 跟清楚的錯誤內容。

服務狀態

公開健康檢查在 /healthz。 /healthz