168 lines
5.3 KiB
Markdown
168 lines
5.3 KiB
Markdown
# 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（本表为公开资产，不应包含密钥；但消费方也不应添加敏感头部到公开日志里）。
|
||
|