diff --git a/README.md b/README.md
index e551e8b..23fea36 100644
--- a/README.md
+++ b/README.md
@@ -337,6 +337,7 @@ Canvas方式：**代码 ⇄ 白板 ⇄ AI ⇄ 人类**，白板成为单一真
 *   [**通用项目架构模板**](./assets/documents/principles/fundamentals/通用项目架构模板.md): 多种项目类型的标准目录结构。
 *   [**Augment MCP 配置文档**](./assets/documents/guides/playbook/auggie-mcp配置文档.md): Augment 上下文引擎配置说明。
 *   [**系统提示词集合**](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203): AI 开发的系统提示词，含多版本开发规范（云端表格）。
+*   [**TradeCat Sheets API 使用说明**](./assets/documents/guides/playbook/tradecat-sheets-api-usage.md): 把公开 Google Sheet 当作 API 注册表与数据面（Data Plane），供 Agent/服务端消费结构化 JSON。
 *   [**外部资源（在线表格）**](./assets/README.md): 外部资源的唯一真相源（按类型分表），本地 Markdown 保留为历史参考。
 
 ---
diff --git a/assets/documents/guides/playbook/README.md b/assets/documents/guides/playbook/README.md
index a3edf72..acf214d 100644
--- a/assets/documents/guides/playbook/README.md
+++ b/assets/documents/guides/playbook/README.md
@@ -13,6 +13,7 @@
 - [LazyVim 快捷键大全](./LazyVim快捷键大全.md) - Neovim 配置框架
 - [Augment MCP 配置](./auggie-mcp配置文档.md) - 上下文引擎配置
 - [ProxyCast 配置](./ProxyCast配置文档.md) - AI 凭证代理服务配置
+- [TradeCat Sheets API 使用说明](./tradecat-sheets-api-usage.md) - 把公开 Google Sheet 当作 API 注册表与数据面（Data Plane）
 - [手机远程 Vibe Coding](./关于手机ssh任意位置链接本地计算机，基于frp实现的方法.md) - 基于 frp 的远程开发
 - [VS Code Remote Tunnel（WSL）](./REMOTE_TUNNEL_GUIDE.md) - 在 WSL 内开通 VS Code Tunnel 供远程访问
 - [GEMINI-HEADLESS](./GEMINI-HEADLESS.md) - Gemini 无头模式配置
diff --git a/assets/documents/guides/playbook/tradecat-sheets-api-usage.md b/assets/documents/guides/playbook/tradecat-sheets-api-usage.md
new file mode 100644
index 0000000..8949723
--- /dev/null
+++ b/assets/documents/guides/playbook/tradecat-sheets-api-usage.md
@@ -0,0 +1,167 @@
+# TradeCat Sheets API 使用说明（公开表格 + API 注册表）
+
+本文档用于把 TradeCat 的公开 Google Sheet 当作 **Agent 可消费的数据面（Data Plane）**：通过 `API` 表（注册表）发现端点，并用表内提供的请求命令拉取结构化 JSON（行情/指标/预测市场/实时新闻）。
+
+> 更新时间：2026-03-17（以 `API` 表导出时间为准）
+
+---
+
+## 1. 公共链接
+
+- 在线表格（含 `API` 注册表页）：  
+  `https://docs.google.com/spreadsheets/d/1q-2sXGsFYsKf3nV5u5golTVrLH5sfc0doiWwz_kavE4/edit?usp=sharing`
+
+---
+
+## 2. 你得到的是什么
+
+### 2.1 `API` 表 = Endpoint Registry（端点注册表）
+
+`API` 表每一行对应一个端点，包含三列：
+
+- `jsonl`：端点返回的 JSON（通常包含压缩 payload）
+- `说明`：端点用途/结构（人读）
+- `请求命令`：可复制执行的命令（机器读/人也可直接复制）
+
+### 2.2 推荐用法：直接复制 `请求命令`
+
+表中 `请求命令` 通常是 `curl ... | python3 -c ...`：
+
+- `curl` 从 Google Sheets gviz 接口取出该行 `jsonl`
+- `python3 -c` 负责解析 JSON、解压 `gzip_b64`（如存在）并输出最终结构化 JSON
+
+这样做的好处：
+- 不需要你自己实现 gzip_base64 解码逻辑
+- 输出格式相对稳定（以表内命令为准）
+
+---
+
+## 3. 快速开始
+
+### 3.1 拉取 API 注册表（CSV）
+
+```bash
+SHEET_ID="1q-2sXGsFYsKf3nV5u5golTVrLH5sfc0doiWwz_kavE4"
+curl -fsSL "https://docs.google.com/spreadsheets/d/${SHEET_ID}/gviz/tq?tqx=out:csv&sheet=API&headers=0" > api.csv
+```
+
+### 3.2 列出端点标题（从 `jsonl` 里解析）
+
+```bash
+python3 - <<'PY'
+import csv, io, json, sys
+raw=open("api.csv","r",encoding="utf-8",errors="replace").read()
+rows=list(csv.reader(io.StringIO(raw)))
+for r in rows[3:]:  # 跳过 banner/导出信息/表头
+    if len(r) < 1 or not r[0].strip().startswith("{"):
+        continue
+    try:
+        obj=json.loads(r[0])
+    except Exception:
+        continue
+    sheet=(obj.get("data") or {}).get("sheet") or {}
+    title=sheet.get("title")
+    gid=sheet.get("gid")
+    payload=(obj.get("data") or {}).get("payload") or {}
+    schema=payload.get("schema") or payload.get("facts_schema") or ""
+    if title:
+        print(f"- {title} (gid={gid} schema={schema})")
+PY
+```
+
+### 3.3 拉取某个端点（推荐）
+
+到表格 `API` 页，找到目标端点行，复制其 `请求命令` 直接执行即可。
+
+---
+
+## 4. 返回格式（Envelope）
+
+端点 JSON 通常遵循如下“信封”结构（字段名以实际返回为准）：
+
+- `code` / `msg` / `success`：状态
+- `data.banner`：公告/广告位等文本（消费方可选择忽略）
+- `data.meta`：生成时间、生产者、语言等
+- `data.sheet`：来源表格信息（`spreadsheet_id/gid/title`）
+- `data.payload`：**真正的数据**（可能包含压缩编码或已解码后的事实列表）
+
+强烈建议消费方至少校验：
+- `data.payload.schema`（或 `facts_schema`）是否是预期的 schema
+- `data.meta.generated_at` / `export_time` 是否足够新鲜
+
+---
+
+## 5. Schema 说明（当前已观察到）
+
+> 以 `API` 表当前内容为准；未来可能新增 schema。
+
+### 5.1 `table_rows_v2`
+
+用于“表格快照”类数据（看板/Polymarket/新闻）。
+
+典型用途：
+- 看板总览、Top 列表、统计表、新闻流
+
+消费建议：
+- 以 `facts[]`（如存在）为单一事实来源
+- 每条 fact 通常包含维度（dims）与字段（fields_text/fields_num）等
+
+### 5.2 `symbol_query_v2`
+
+用于“单币种多周期指标面板”类数据（BTC/ETH/BNB/SOL）。
+
+典型用途：
+- 单币画像、指标诊断、策略特征输入、AI 分析上下文
+
+消费建议：
+- 以 `facts[]`（如存在）为单一事实来源
+- 不要依赖 UI 文案；依赖结构化指标字段
+
+---
+
+## 6. 端点清单（2026-03-17 快照）
+
+以下端点来自 `API` 表当前解析结果（title/gid/schema）：
+
+### 市场总览（table_rows_v2）
+
+- 加密货币看板（gid=1277788455, schema=table_rows_v2）
+- 宏观大宗看板（gid=1931661963, schema=table_rows_v2）
+
+### 单币画像（symbol_query_v2）
+
+- 币种查询_BTCUSDT（gid=1325757221, schema=symbol_query_v2）
+- 币种查询_ETHUSDT（gid=904473439, schema=symbol_query_v2）
+- 币种查询_BNBUSDT（gid=78880380, schema=symbol_query_v2）
+- 币种查询_SOLUSDT（gid=208400041, schema=symbol_query_v2）
+
+### 预测市场（table_rows_v2）
+
+- PolymarketTop15（gid=1715937602, schema=table_rows_v2）
+- Polymarket时段分布（gid=333189916, schema=table_rows_v2）
+- Polymarket类别偏好（gid=1923964075, schema=table_rows_v2）
+
+### 实时新闻（table_rows_v2）
+
+- 实时新闻（gid=1419246950, schema=table_rows_v2）
+
+---
+
+## 7. 可靠性与调用建议（给 Agent/服务端）
+
+由于底层是公开 Google Sheet：
+
+- 建议做 **缓存**（例如 5～60 秒，按业务容忍度）
+- 建议做 **退避重试**（遇到 429/5xx 时指数退避）
+- 建议做 **降级策略**
+  - 表不可用：降级为“只读旧缓存”
+  - 新闻不可用：只跑行情/指标
+  - schema 不匹配：拒绝消费该批数据
+
+---
+
+## 8. 合规与安全边界
+
+- 本接口与本文档不构成投资建议；仅用于研究与协作交流。
+- 不要在任何公开场合贴出内部密钥/Token（本表为公开资产，不应包含密钥；但消费方也不应添加敏感头部到公开日志里）。
+