5.3 KiB

Raw Blame History

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）

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` 里解析）

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

5.3 KiB Raw Blame History Unescape Escape