API Token 使用指南

如何生成 Token

登录后进入 Trade → 开发者工具 → 集成中心 → API Token，在页面上创建 Token。

系统只会在创建成功时返回一次明文 Token；后端仅存储 hash。

如何携带 Token 调用 API

你可以用以下任意一种方式传 Token：

• Authorization: Bearer tc_xxx
• X-API-Token: tc_xxx

# 示例 1：读取 dashboard
curl -X GET "https://<YOUR_API_BASE>/trade/dashboard" \
  -H "Authorization: Bearer tc_xxx"

# 示例 2：读取今日闪卡新增统计
curl -X GET "https://<YOUR_API_BASE>/flashcard/cards/today-summary?timezone=Asia/Shanghai" \
  -H "Authorization: Bearer tc_xxx"

权限范围与限制

• 默认仅允许 /trade/*
• 额外开放只读接口：GET /flashcard/cards/today-summary
• 允许创建/更新/查询交易
• 禁止删除交易

最小可执行闭环（交易详情→图片解析→下载）

推荐先按下面 3 步跑通，再接入你自己的 agent / 脚本。

可选补充：查询今天是否新增闪卡

curl -X GET "https://<YOUR_API_BASE>/flashcard/cards/today-summary?timezone=Asia/Shanghai" \
  -H "Authorization: Bearer tc_xxx"

返回 hasNewCardsToday、newCardsCount、latestCreatedAt，适合脚本/Agent 做日更轮询。

Step 1：获取交易详情（拿到图片 refs）

curl -X GET "https://<YOUR_API_BASE>/trade/<transactionId>"   -H "Authorization: Bearer tc_xxx"

从返回 data 里收集图片字段中的 key/ref（如marketStructureAnalysisImages[*].key）。

Step 2：解析图片引用为短时下载 URL

curl -X POST "https://<YOUR_API_BASE>/trade/image/resolve"   -H "Authorization: Bearer tc_xxx"   -H "Content-Type: application/json"   -d '{
    "transactionId": "<transactionId>",
    "refs": [
      "uploads/<userId>/<transactionId>/2026-02-19/xxx.png"
    ]
  }'

返回 items[].url 为短时签名 URL（默认约 300s）。

Step 3：下载图片

curl -L "<signedUrlFromResolve>" -o trade-image.png

JavaScript（fetch）版本

const apiBase = "https://<YOUR_API_BASE>";
const token = "tc_xxx";
const transactionId = "<transactionId>";

// 1) 读取交易详情
const tradeRes = await fetch(apiBase + "/trade/" + transactionId, {
  headers: { Authorization: "Bearer " + token },
});
const tradeJson = await tradeRes.json();

const refs = (tradeJson?.data?.marketStructureAnalysisImages || [])
  .map((x) => x?.key)
  .filter(Boolean);

// 2) 解析 refs -> 短时 URL
const resolveRes = await fetch(apiBase + "/trade/image/resolve", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + token,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ transactionId, refs }),
});
const resolveJson = await resolveRes.json();

// 3) 下载第一张图
const firstUrl = resolveJson?.data?.items?.[0]?.url || resolveJson?.items?.[0]?.url;
if (!firstUrl) throw new Error("no downloadable image url");

const fileRes = await fetch(firstUrl);
const blob = await fileRes.blob();
console.log("downloaded bytes:", blob.size);

可选：获取交易域上传 URL（API Token 可用）

curl -X POST "https://<YOUR_API_BASE>/trade/image/upload-url"   -H "Authorization: Bearer tc_xxx"   -H "Content-Type: application/json"   -d '{
    "transactionId": "<transactionId>",
    "fileName": "chart.png",
    "fileType": "image/png",
    "date": "2026-02-19",
    "contentLength": 245678,
    "source": "trade"
  }'

注意：API Token 不开放 /image/*，请使用/trade/image/*。

常见错误与排查

• 401 Unauthorized：Token 无效/过期。确认是否使用tc_ 前缀且请求头正确。
• 403 Forbidden：越权访问（例如访问未开放给 API Token 的接口， 或解析非本人图片 key）。
• 429 Too Many Requests：触发限流或配额（每日次数/字节、分钟签发速率）。
• 400 Bad Request：参数不完整（最常见是 upload-url 缺transactionId 或字段类型不合法）。

对应 Skill（外部 Agent 可下载）

我们新增了一个可直接给外部 Agent 使用的 Skill：trade-api-token-agent（包含“查询交易 + 编辑交易”API Token 调用模板）。

下载地址：下载 SKILL.md

机器建议运行时拼接 origin：/downloads/trade-api-token-agent-SKILL.md

说明：此 SKILL.md 已内嵌 MACHINE_JSON + STRICT_SCHEMA_JSON（v2）。

结合 Telegram Webhook：让你的 Clawbot 自动分析

推荐做法：让 webhook 把提醒推到 Telegram 群，然后由你自己的 clawbot 监听群消息，解析其中的META_JSON（包含 transactionId），再用 API Token 拉取 trade 的分析字段：

# 1) clawbot 从群消息 META_JSON 解析出 transactionId
# 2) 用 API token 拉取交易详情（包含计划、关键位、风控等）
curl -X GET "https://<YOUR_API_BASE>/trade/<transactionId>"   -H "Authorization: Bearer tc_xxx"

然后 clawbot 把 webhook message + trade 详情一起喂给你的分析 prompt/agent，即可生成报告并回发群。