@openfinclaw/findoo-datahub-plugin 2026.3.2 → 2026.3.10

package/skills/crypto-funding-arb/skill.md

@@ -0,0 +1,158 @@
+---
+name: fin-crypto-funding-arb
+description: "Crypto funding rate arbitrage — perpetual funding rates, delta-neutral yield, cross-exchange rate spread, annualized return calculator. Use when: user asks about funding rate, delta-neutral strategy, basis trading, perpetual vs spot arb, or CeFi yield. NOT for: DeFi yields (use fin-crypto-defi-yield), spot trading (use fin-crypto), macro rates (use fin-macro)."
+metadata: { "openclaw": { "emoji": "🔄", "requires": { "extensions": ["findoo-datahub-plugin"] } } }
+---
+
+# Crypto Funding Rate Arbitrage
+
+永续合约资金费率套利分析 — Delta 中性策略的收益计算、风险监控与跨交易所利差发现。通过 `fin_crypto` 访问 funding rate / ticker / orderbook 数据。
+
+> **核心逻辑:** 永续合约每 8h 结算 funding rate。当 funding > 0 时，做多付费给做空方。Delta 中性策略 = 现货买入 + 永续做空，锁定 funding 收益，无方向性风险。
+
+## When to Use
+
+- "BTC 资金费率多少" / "BTC funding rate"
+- "哪些币 funding rate 最高" / "top funding rate coins"
+- "funding 套利能赚多少" / "funding arb yield"
+- "现在做 delta 中性策略合适吗" / "delta neutral strategy"
+- "Binance 和 OKX funding 差多少" / "cross-exchange funding spread"
+- "funding rate 历史高不高" / "is funding rate extreme"
+- "资金费率套利风险" / "funding arb risks"
+
+## When NOT to Use
+
+- DeFi 收益 / yield farming / Aave / Compound → use `/fin-crypto-defi-yield`
+- 现货价格 / 代币信息 / 全景分析 → use `/fin-crypto`
+- 宏观利率 / 美债收益率 → use `/fin-macro`
+- 合约爆仓计算 / 杠杆风险 → use `/fin-crypto` (Contract Risk Calculator)
+- 期货期权 / 传统衍生品 → use `/fin-derivatives`
+
+## Tools & Parameters
+
+### fin_crypto — Funding & Market Data
+
+| Parameter | Type   | Required | Format              | Default | Example             |
+| --------- | ------ | -------- | ------------------- | ------- | ------------------- |
+| endpoint  | string | Yes      | see endpoints below | —       | market/funding_rate |
+| symbol    | string | Depends  | pair format         | —       | BTC/USDT:USDT       |
+| limit     | number | No       | 1-250               | 100     | 20                  |
+
+#### Endpoints
+
+| endpoint              | Description                 | Example                                                              |
+| --------------------- | --------------------------- | -------------------------------------------------------------------- |
+| `market/funding_rate` | Perpetual funding rate + OI | `fin_crypto(endpoint="market/funding_rate", symbol="BTC/USDT:USDT")` |
+| `market/ticker`       | Spot price snapshot         | `fin_crypto(endpoint="market/ticker", symbol="BTC/USDT")`            |
+| `market/tickers`      | All tickers (scan)          | `fin_crypto(endpoint="market/tickers")`                              |
+| `market/orderbook`    | Order book depth            | `fin_crypto(endpoint="market/orderbook", symbol="BTC/USDT")`         |
+| `market/trades`       | Recent trades               | `fin_crypto(endpoint="market/trades", symbol="BTC/USDT")`            |
+
+### Auxiliary Tools
+
+| Tool              | Purpose                      | Example                                               |
+| ----------------- | ---------------------------- | ----------------------------------------------------- |
+| `fin_data_ohlcv`  | K-line for basis calculation | `fin_data_ohlcv(symbol="BTC/USDT", timeframe="1h")`   |
+| `fin_ta`          | Trend indicators             | `fin_ta(symbol="BTC/USDT", indicator="rsi")`          |
+| `fin_data_regime` | Market regime                | `fin_data_regime(symbol="BTC/USDT", market="crypto")` |
+
+## Funding Rate Arbitrage Analysis Pattern
+
+1. **Funding Rate Scan** `fin_crypto(market/funding_rate, symbol="BTC/USDT:USDT")` — 获取目标币种当前 funding rate + OI
+   - ⚠️ 如果 funding > +0.10%/8h → 多头极度拥挤，套利收益高但清算瀑布风险也高
+   - ⚠️ 如果 funding < -0.05%/8h → 空头拥挤，反向套利（现货做空 + 永续做多）但执行难度大
+   - 💡 关注 funding 持续性：连续 3+ 期 >0.05% = 稳定套利窗口；单期跳升可能是噪音
+
+2. **Spot Price Baseline** `fin_crypto(market/ticker, symbol="BTC/USDT")` — 现货价格基准
+   - 💡 计算 basis = (永续价 - 现货价) / 现货价 × 100%。正 basis + 正 funding = 做空端有利
+
+3. **Annualized Return Calculation** — 核心输出
+
+   ```
+   8h rate → Daily = rate × 3
+   Annual = rate × 3 × 365
+   Net annual = annual - (maker_fee × 2 × 365) - slippage_estimate
+   ```
+
+   - ⚠️ 如果年化 < 10% → 扣除手续费和滑点后可能不值得（DeFi 蓝筹 yield 通常 3-8%）
+   - 💡 对比 DeFi yield：切换 `/fin-crypto-defi-yield` 查 Aave/Compound 同期收益，做风险调整后对比
+
+4. **Liquidity Assessment** `fin_crypto(market/orderbook, symbol="BTC/USDT")` — 执行成本评估
+   - ⚠️ 如果 spread > 0.1% → 大仓位进出滑点显著，套利净收益打折
+   - ⚠️ 如果 orderbook depth < $500K within 0.1% → 流动性不足，不适合大额套利
+   - 💡 小币种 funding 高但流动性差 = 纸面收益陷阱
+
+5. **Risk Monitor** — 综合风险评估
+   - ⚠️ OI 突增 >20% + funding >0.15%/8h → "拥挤交易警报"，清算级联风险极高
+   - ⚠️ Basis 快速收敛 → 平仓窗口，套利收益可能归零
+   - 💡 用 `fin_data_regime` 判断市场体制：Volatile/Crisis 时 funding 波动剧烈，套利窗口短且风险高
+
+6. **Market Regime Context** `fin_data_regime(symbol="BTC/USDT", market="crypto")` — 体制对策略的影响
+   - Bull + 高 funding = 最佳套利环境（趋势性行情 funding 持续性强）
+   - Sideways + 低 funding = 收益不足以覆盖成本
+   - Volatile/Crisis = funding 剧烈波动，短期窗口但风险极高
+
+## Yield Comparison Framework
+
+| Source                | Typical Yield       | Risk Level               | Liquidity  |
+| --------------------- | ------------------- | ------------------------ | ---------- |
+| Funding Arb (BTC)     | 15-40% annualized   | Medium (basis risk)      | High (CEX) |
+| Funding Arb (Altcoin) | 30-100%+ annualized | High (liquidity + basis) | Low-Medium |
+| Aave USDC (ETH)       | 3-8%                | Low (smart contract)     | High       |
+| Compound USDC         | 3-6%                | Low                      | High       |
+| US Treasury           | 4-5%                | Risk-free                | High       |
+
+## Signal Quick-Reference
+
+### Funding Rate Signals
+
+| Funding Rate (8h) | Annualized | Signal        | Action                                     |
+| ----------------- | ---------- | ------------- | ------------------------------------------ |
+| > +0.15%          | > 55%      | Extreme long  | High yield but squeeze risk; size down     |
+| +0.05% ~ +0.15%   | 18-55%     | Sweet spot    | Best risk-adjusted arb window              |
+| +0.01% ~ +0.05%   | 4-18%      | Marginal      | Only worth it for large capital + low fees |
+| -0.01% ~ +0.01%   | < 4%       | Neutral       | Not actionable                             |
+| < -0.05%          | —          | Short squeeze | Consider reverse arb (risky)               |
+
+### Risk Alerts
+
+| Condition                      | Risk                    | Mitigation           |
+| ------------------------------ | ----------------------- | -------------------- |
+| OI surge >20% in 24h           | Liquidation cascade     | Reduce position size |
+| Funding >0.15% for >3 periods  | Mean reversion imminent | Take partial profit  |
+| Basis flips negative           | Funding may flip        | Close arb position   |
+| Exchange rate divergence >0.3% | Execution risk          | Avoid cross-exchange |
+
+## Data Notes
+
+- **Funding Rate**: Settlement cycle varies by exchange (Binance 8h, some exchanges 4h/1h); always note the period when calculating annualized yield
+- **OI Data**: Available via `market/funding_rate` response; cross-validate with volume
+- **Cross-Exchange**: DataHub may aggregate from primary exchange only; manual comparison needed for cross-exchange arb
+- **Historical Funding**: Current endpoint returns latest snapshot; historical funding time series may be limited
+- **Basis Calculation**: Use `fin_data_ohlcv` for perpetual vs spot price comparison; note that OHLCV symbol format differs (e.g., `BTC/USDT` for spot, `BTC/USDT:USDT` for perpetual)
+
+## Response Guidelines
+
+### Number Formatting
+
+- Funding rate: 4 decimal places per period (+0.0800%/8h)
+- Annualized yield: 1 decimal place (35.0% annualized)
+- BTC price: to integer ($67,432)
+- Altcoin price: 4 significant digits ($0.0034, $1.2345)
+- OI / Volume: $B/$M notation ($4.2B OI)
+- Basis: 2 decimal places (+0.12%)
+
+### Must Include
+
+- Funding rate period (8h/4h/1h) — never show rate without period
+- Net yield after fees (maker fee typically 0.02%, taker 0.05%)
+- Risk tier classification (low/medium/high/extreme)
+- Comparison benchmark (vs DeFi blue-chip yield or US Treasury)
+- Data timestamp ("funding rate as of 2026-03-07 08:00 UTC")
+
+### Display Format
+
+- Single coin funding analysis → structured narrative with yield calculator
+- Multi-coin funding scan → table (columns: symbol / rate / annualized / OI / duration / risk)
+- Risk assessment → bullet points with clear thresholds
+- Always end with: position sizing suggestion based on risk tier

package/skills/crypto-stablecoin-flow/skill.md

@@ -0,0 +1,149 @@
+---
+name: fin-crypto-stablecoin-flow
+description: "Stablecoin capital flow analysis — USDT/USDC/DAI market cap trends, 4-week rolling inflow as leading indicator, chain distribution (ETH/Tron/BSC), stablecoin-to-total-market ratio. Use when: user asks about stablecoin supply, capital inflow/outflow, OTC demand, USDT vs USDC comparison, or whether money is entering crypto. NOT for: individual coin analysis (use fin-crypto), DeFi yield farming (use fin-crypto), macro rates (use fin-macro)."
+metadata: { "openclaw": { "emoji": "💵", "requires": { "extensions": ["findoo-datahub-plugin"] } } }
+---
+
+# Stablecoin Capital Flow Analysis
+
+Stablecoins = crypto market's M2 money supply. Track stablecoin flows as a **2-4 week leading indicator** for BTC and altcoin price direction.
+
+> **Core thesis:** Capital enters crypto in three steps: fiat -> stablecoin -> BTC/altcoin. Stablecoin supply changes signal capital intent before price moves.
+
+## When to Use
+
+- "USDT 市值在增长吗" / "Is USDT market cap growing"
+- "稳定币总量是多少" / "Total stablecoin supply"
+- "场外资金在进场吗" / "Is money flowing into crypto"
+- "USDT 和 USDC 有什么区别" / "USDT vs USDC comparison"
+- "稳定币在哪条链上最多" / "Which chain has the most stablecoins"
+- "现在是入场好时机吗" / "Is this a good time to enter crypto"
+
+## When NOT to Use
+
+- Individual coin price/analysis (BTC/ETH/SOL) -> use `/fin-crypto`
+- DeFi protocol TVL/yields -> use `/fin-crypto`
+- CEX trading (orderbook/funding rate) -> use `/fin-crypto`
+- Macro interest rates/treasury yields -> use `/fin-macro`
+- A-share/US equity -> use `/fin-a-share` or `/fin-us-equity`
+
+## Tools & Parameters
+
+### fin_crypto
+
+| Parameter | Type   | Required | Format              | Default | Example          |
+| --------- | ------ | -------- | ------------------- | ------- | ---------------- |
+| endpoint  | string | Yes      | see endpoints below | —       | defi/stablecoins |
+| symbol    | string | Depends  | coin ID / pair      | —       | bitcoin          |
+| limit     | number | No       | 1-250               | 100     | 20               |
+
+#### Key Endpoints
+
+| endpoint            | Description                                      | Example                                        |
+| ------------------- | ------------------------------------------------ | ---------------------------------------------- |
+| `defi/stablecoins`  | All stablecoins: market cap + chain distribution | `fin_crypto(endpoint="defi/stablecoins")`      |
+| `coin/global_stats` | Total crypto market cap (for ratio calc)         | `fin_crypto(endpoint="coin/global_stats")`     |
+| `coin/market`       | Top coins by market cap (BTC price ref)          | `fin_crypto(endpoint="coin/market", limit=10)` |
+| `defi/chains`       | Per-chain TVL (cross-validate fund flow)         | `fin_crypto(endpoint="defi/chains")`           |
+| `defi/bridges`      | Cross-chain bridge volumes (migration)           | `fin_crypto(endpoint="defi/bridges")`          |
+
+### Auxiliary Tools
+
+| tool              | use case                              |
+| ----------------- | ------------------------------------- |
+| `fin_data_ohlcv`  | BTC/ETH price overlay for correlation |
+| `fin_data_regime` | Current market regime context         |
+| `fin_ta`          | BTC trend confirmation                |
+
+## Stablecoin Flow Analysis Pattern
+
+1. **Stablecoin Supply Snapshot** `fin_crypto(endpoint="defi/stablecoins")` — Total supply + per-coin breakdown
+   - Key fields: total mcap, USDT mcap, USDC mcap, DAI mcap, chain distribution per coin
+   - ⚠️ If total stablecoin mcap < previous known value -> capital outflow signal, check severity
+   - 💡 USDT growth = primarily Asian retail/OTC inflow; USDC growth = institutional/DeFi allocation
+
+2. **Total Market Context** `fin_crypto(endpoint="coin/global_stats")` — Crypto total market cap + BTC dominance
+   - Calculate: stablecoin_ratio = total_stablecoin_mcap / total_crypto_mcap
+   - ⚠️ Ratio rising (e.g., 9% -> 12%) = capital retreating to sidelines (defensive)
+   - ⚠️ Ratio falling (e.g., 12% -> 9%) = capital deploying into risk assets (offensive)
+   - 💡 Cross-validate with BTC dominance: stablecoin ratio down + BTC dom down = broad risk-on (altseason fuel)
+
+3. **Chain Distribution Analysis** `fin_crypto(endpoint="defi/stablecoins")` — Per-chain stablecoin breakdown
+   - Ethereum = institutional DeFi + lending protocols
+   - Tron = Asian OTC + cross-border remittance + retail
+   - BSC = retail DeFi + gaming
+   - Arbitrum/Base = L2 DeFi migration
+   - ⚠️ If Tron USDT growing fastest -> Asian retail surge (historically bullish for BTC in 2-4 weeks)
+   - ⚠️ If Ethereum USDC growing -> institutional positioning (larger but slower capital)
+   - 💡 Bridge data (`defi/bridges`) cross-validates: net inflow to a chain confirms stablecoin migration direction
+
+4. **BTC Price Correlation** `fin_crypto(endpoint="coin/market", limit=5)` + `fin_data_ohlcv(symbol="BTC/USDT")`
+   - Compare stablecoin supply trend vs BTC 30-day price trend
+   - ⚠️ Stablecoin supply rising + BTC flat/declining = accumulation phase (bullish setup)
+   - ⚠️ Stablecoin supply declining + BTC rising = distribution/leverage-driven rally (fragile)
+   - 💡 Historical pattern: stablecoin 4-week increase > $2B precedes BTC 30-day average gain of +12%
+
+5. **USDT vs USDC Structural Analysis** — Derive from `defi/stablecoins` data
+   - USDT/USDC ratio trend: rising = retail dominance; falling = institutional shift
+   - ⚠️ USDT market share dropping below 60% = potential regulatory pressure signal
+   - 💡 After major regulatory events (e.g., SEC actions), watch for USDT->USDC rotation
+
+6. **Capital Flow Verdict** — Synthesize all signals
+   - Strong inflow: 4w total increase > $2B + ratio declining + Tron USDT growing
+   - Neutral: 4w change < $1B absolute, ratio stable
+   - Outflow warning: 4w decrease > $1B + ratio rising + BTC price declining
+
+## Leading Indicator Framework
+
+### 4-Week Rolling Change Thresholds
+
+| 4-Week Change | Signal           | Historical BTC 30d Avg | Action                        |
+| ------------- | ---------------- | ---------------------- | ----------------------------- |
+| > +$3B        | Strong inflow    | +15%                   | Bullish positioning warranted |
+| +$1B to +$3B  | Moderate inflow  | +8%                    | Cautiously optimistic         |
+| -$1B to +$1B  | Neutral          | +2%                    | No directional signal         |
+| -$3B to -$1B  | Moderate outflow | -5%                    | Reduce leverage, raise cash   |
+| < -$3B        | Capital flight   | -12%                   | Defensive mode, max caution   |
+
+### Stablecoin/Market Cap Ratio Interpretation
+
+| Ratio Range | State        | Meaning                              |
+| ----------- | ------------ | ------------------------------------ |
+| > 15%       | Max defense  | Heavy sideline capital, fear extreme |
+| 10-15%      | Cautious     | Significant dry powder available     |
+| 7-10%       | Balanced     | Capital actively deployed            |
+| < 7%        | Full risk-on | Almost all capital in risk assets    |
+
+## Data Notes
+
+- **DefiLlama stablecoins**: No auth required, ~10min refresh cycle. Covers USDT/USDC/DAI/BUSD/TUSD and 20+ minor stablecoins
+- **Chain distribution**: Per-coin per-chain breakdown available. Some smaller chains may have incomplete coverage
+- **Missing data**: Mint/burn event stream (requires on-chain data — Tether Treasury/Circle), USDT OTC premium/discount (requires OTC desk quotes), historical time-series per chain (snapshot only, no built-in 4-week rolling — must compare against previous observation)
+- **4-week rolling calculation**: Since `defi/stablecoins` returns a current snapshot, 4-week change requires comparing against a prior data point. If unavailable, state current absolute values and note the limitation
+- **CoinGecko rate limit**: ~30 req/min for `coin/global_stats` and `coin/market`
+
+## Response Guidelines
+
+### Number Formats
+
+- Stablecoin market cap: $168.2B (use $B for billions, $M for millions)
+- Supply changes: +$1.8B / -$500M (always show +/- sign)
+- Ratios: 9.8% (1 decimal place)
+- BTC price: to nearest dollar ($67,432)
+- Chain distribution: percentages with 1 decimal (Ethereum 45.2%, Tron 31.8%)
+
+### Must Include
+
+- Data timestamp ("Data as of YYYY-MM-DD")
+- Top 3 stablecoins by market cap with individual figures
+- Stablecoin/total crypto market cap ratio
+- Chain distribution for at least top 3 chains
+- Explicit note when 4-week rolling data is unavailable (snapshot limitation)
+
+### Display Format
+
+- Overview query -> summary paragraph + key metrics table
+- USDT vs USDC comparison -> side-by-side table (market cap, growth, chain distribution, user profile)
+- Capital flow analysis -> bullet-point signals with strength indicators
+- Always end with a directional verdict: bullish / neutral / bearish with confidence level
+- Include caveat: "Stablecoin flow is a leading indicator, not a guarantee. Always combine with price action and on-chain data for confirmation."

package/skills/data-query/skill.md

@@ -1,56 +1,150 @@
 ---
 name: fin-data-query
-description: "Generic DataHub query — directly call any of 172 financial data endpoints by path. Fallback when specialized tools don't cover the data need."
+description: "Generic DataHub query fallback — access any of 168+ financial data endpoints by path. Also provides OHLCV candle data with caching, market regime detection, and supported markets listing. Use when: specialized tools (fin_stock/fin_crypto/fin_macro/etc.) don't cover the data need, or querying uncommon endpoints like company news or coverage metadata. NOT for: common queries covered by fin-a-share/fin-us-equity/fin-hk-stock, fin-macro, fin-crypto, fin-derivatives, fin-a-share-radar, fin-etf-fund."
 metadata: { "openclaw": { "emoji": "🔍", "requires": { "extensions": ["findoo-datahub-plugin"] } } }
 ---
 
 # Data Query (Fallback)
 
-Use the **fin_query** tool as a generic fallback to access any of the 172 DataHub endpoints directly (works out of the box).
+Use **fin_query** as a generic fallback to access any of the 168+ DataHub endpoints directly. Also use **fin_data_ohlcv** for K-line data, **fin_data_markets** for supported markets, and **fin_data_regime** for market regime detection.
 
-## When to Use
+The datahub has **8 specialized query tools** (fin_stock, fin_index, fin_macro, fin_crypto, fin_derivatives, fin_market, fin_etf, fin_currency) plus fin_ta — prefer those for common queries. Use fin_query only when no specialized tool covers the endpoint.
 
-- When specialized tools (fin_stock, fin_index, fin_macro, fin_derivatives, fin_crypto, fin_market) don't cover the specific data need
-- When querying less common endpoints
+## Skill Routing Quick-Check
 
-## DataHub Categories
+Before proceeding, check if a specialized skill handles this query better:
+
+| User Intent (keywords)         | Route to            |
+| ------------------------------ | ------------------- |
+| A 股 / 茅台 / 沪深             | `fin-a-share`       |
+| AAPL / US earnings / S&P 500   | `fin-us-equity`     |
+| 00700.HK / 港股                | `fin-hk-stock`      |
+| BTC / DeFi / CEX               | `fin-crypto`        |
+| GDP / CPI / 宏观               | `fin-macro`         |
+| 期货 / 期权 / 可转债           | `fin-derivatives`   |
+| 基金 / ETF / NAV               | `fin-etf-fund`      |
+| 市场复盘 / 涨跌排行            | `fin-a-share-radar` |
+| 选股 / 因子筛选                | `fin-factor-screen` |
+| 资产配置 / 跨市场              | `fin-cross-asset`   |
+| 风险评估 / VaR                 | `fin-risk-monitor`  |
+| **None match** → proceed below | `fin-data-query`    |
+
+## Tools & Parameters
+
+### fin_query — Generic Query
+
+| Parameter | Type   | Required | Format                        | Default | Example           |
+| --------- | ------ | -------- | ----------------------------- | ------- | ----------------- |
+| path      | string | Yes      | category/endpoint (see below) | —       | news/company      |
+| params    | object | No       | key-value query params        | {}      | {"symbol":"AAPL"} |
+
+### fin_data_ohlcv — K-line (OHLCV)
+
+| Parameter | Type   | Required | Format                      | Default | Example  |
+| --------- | ------ | -------- | --------------------------- | ------- | -------- |
+| symbol    | string | Yes      | trading pair or stock code  | —       | BTC/USDT |
+| market    | string | No       | crypto / equity / commodity | crypto  | equity   |
+| timeframe | string | No       | 1m / 5m / 1h / 4h / 1d      | 1h      | 1d       |
+| since     | number | No       | Unix timestamp in ms        | —       | —        |
+| limit     | number | No       | 1-1000                      | 200     | 100      |
+
+### fin_data_regime — Market Regime Detection
+
+| Parameter | Type   | Required | Format                      | Default | Example   |
+| --------- | ------ | -------- | --------------------------- | ------- | --------- |
+| symbol    | string | Yes      | trading pair or stock code  | —       | 600519.SH |
+| market    | string | No       | crypto / equity / commodity | crypto  | equity    |
+| timeframe | string | No       | 1m / 5m / 1h / 4h / 1d      | 4h      | 1d        |
+
+Returns: `bull` / `bear` / `sideways` / `volatile` / `crisis`
+
+### fin_data_markets — Supported Markets
+
+No parameters. Returns supported markets, data categories, and total endpoint count.
+
+## DataHub Categories (168+ endpoints)
 
 | Category        | Endpoints | Coverage                                                      |
 | --------------- | --------- | ------------------------------------------------------------- |
 | `equity/*`      | 83        | A-share, HK, US — prices, fundamentals, ownership, money flow |
 | `crypto/*`      | 23        | CEX market data, CoinGecko, DeFi via DefiLlama                |
-| `economy/*`     | 21        | China macro, rates, FX, World Bank                            |
-| `derivatives/*` | 13        | Futures, options, convertible bonds                           |
-| `index/*`       | 12        | Index data, thematic indices                                  |
-| `etf/*`         | 9         | ETF prices, NAV, fund data                                    |
-| `currency/*`    | 3         | FX historical, search, snapshots                              |
+| `economy/*`     | 23        | China macro, rates, FX, World Bank, Shibor quote, WZ index    |
+| `derivatives/*` | 13        | Futures (incl. curve), options, convertible bonds             |
+| `index/*`       | 10        | Index data, thematic indices                                  |
+| `etf/*`         | 9         | ETF prices, NAV, fund portfolio/manager/dividends/share/adj   |
+| `currency/*`    | 4         | FX historical, search, snapshots, news                        |
 | `news/*`        | 1         | Company news                                                  |
+| `coverage/*`    | 2+        | Provider list, endpoint discovery                             |
 
-## Example Calls
+## Removed / Dead Endpoints
 
-```
-# ETF fund manager info
-fin_query(path="etf/fund/manager", params={"symbol": "110011"})
+以下端点已移除，请勿使用:
+
+| 端点              | 状态                | 替代方案                  |
+| ----------------- | ------------------- | ------------------------- |
+| `index/members`   | 已移除 (始终返回 0) | 使用 `index/constituents` |
+| `index/snapshots` | 已移除 (404 错误)   | 使用 `index/daily_basic`  |
+| `flow/ggt_top10`  | 已移除 (超时)       | 使用 `flow/ggt_daily`     |
+
+## Endpoint Discovery Pattern
+
+1. `fin_query(path="coverage/providers")` — see all 38+ data providers
+2. `fin_query(path="coverage/commands")` — browse all 168+ endpoints with descriptions
+3. Use category prefix to narrow down (equity/, crypto/, economy/, etc.)
 
-# Currency historical
-fin_query(path="currency/price/historical", params={"symbol": "USDCNH"})
+## Common Queries (only via fin_query)
 
+```
 # Company news
 fin_query(path="news/company", params={"symbol": "AAPL"})
 
-# Coverage metadata — see all available endpoints
-fin_query(path="coverage/providers")
+# Discover all available endpoints
 fin_query(path="coverage/commands")
+
+# List all data providers
+fin_query(path="coverage/providers")
 ```
 
-## When to Prefer Specialized Tools
-
-| Data Need                   | Use Instead       |
-| --------------------------- | ----------------- |
-| Stock quote / financials    | `fin_stock`       |
-| Index / ETF / Fund          | `fin_index`       |
-| GDP / CPI / interest rates  | `fin_macro`       |
-| Futures / options / CB      | `fin_derivatives` |
-| Crypto / DeFi               | `fin_crypto`      |
-| Dragon-tiger / market radar | `fin_market`      |
-| Simple OHLCV (CCXT/Yahoo)   | `fin_data_ohlcv`  |
+## Market Regime Usage
+
+```
+# Detect if market is bullish/bearish
+fin_data_regime(symbol="000300.SH", market="equity", timeframe="1d")
+# Returns: "bull" / "bear" / "sideways" / "volatile" / "crisis"
+
+# Crypto regime
+fin_data_regime(symbol="BTC/USDT", market="crypto", timeframe="4h")
+```
+
+- Uses SMA crossover + ATR analysis on 200+ bars
+- Needs 200+ bars of historical data; defaults to "sideways" if insufficient
+- Useful as input for strategy decisions or risk assessment
+
+## Data Notes
+
+- **fin_query**: 万能后备，任何 DataHub endpoint 都可通过 path + params 调用
+- **fin_data_ohlcv**: 带 SQLite 本地缓存，重复查询更快
+- **fin_data_regime**: 需要 200+ 根 K 线，数据不足返回 "sideways"
+- **coverage/commands**: 全量 endpoint 列表，最可靠的发现方式
+- 查询失败时，建议用 coverage/commands 确认 endpoint 是否存在
+- fin_query 返回原始 JSON，大数据量 (>20 行) 只展示 Top 10 + 总数
+
+### 端点参数特殊说明
+
+| 端点                  | 特殊参数                  | 说明                              |
+| --------------------- | ------------------------- | --------------------------------- |
+| `flow/hsgt_top10`     | 需 `date` (非 trade_date) | 北向 Top10 持股，必须传 date 参数 |
+| `flow/hs_const`       | 需 `hs_type` (SH 或 SZ)   | 互联互通成分股，hs_type 必填      |
+| `market/stock_limit`  | 需 `symbol`               | 个股涨跌停价，不支持按日期批量    |
+| `estimates/consensus` | 仅 yfinance 美股          | A 股不支持，有频率限制            |
+| `fixedincome/rate/*`  | 通过 fin_macro 调用       | LIBOR/HIBOR 数据截止 2020-06      |
+
+## Troubleshooting
+
+| Symptom               | Fix                                                       |
+| --------------------- | --------------------------------------------------------- |
+| "endpoint not found"  | 用 `coverage/commands` 确认 path 拼写和存在性             |
+| 返回空数组            | 检查 params 格式 (symbol 大小写、日期格式 YYYYMMDD)       |
+| Rate limit / 429      | CoinGecko ~30 req/min, tushare ~200 req/min; 降低请求频率 |
+| 数据截断              | 所有 endpoint 返回 JSON 数组; 大结果集自动截断 Top 10     |
+| World Bank 自定义指标 | `fin_macro` + path `worldbank/indicator` + 自定义 code    |