把我们的信号，接进你自己的地方

内测期请先读这段

接口、鉴权、额度、Webhook 都已经可用，但信号事件流还没有对外开放—— 现在调 /v1/signals 拿到的是空集，响应里的 notice 字段会写明这一点， /v1/health 的 dataStream 会是 not_open_yet。

这样安排是想让你先把链路接完、把字段结构落实到代码里。 现在返回的字段结构就是正式结构，数据开放后你不需要改代码。开放时间我们会提前通知。

三分钟接上

1. 拿到密钥：形如 sv_live_xxxxxx.xxxxxxxx。它只会给你看一次，请自己存好。
2. 验证连通：调 /openapi/v1/me，能看到自己的档位与今日用量就通了。
3. 拉信号：调 /openapi/v1/signals。第一次不带参数拿最新一批，之后带上 since_id 做增量，不重不漏。

# 验证连通
curl -H "Authorization: Bearer $SV_API_KEY" \
     https://stock.tanggestock.com/openapi/v1/me

# 拉最近 50 条 4 小时级别的比特币信号
curl -H "Authorization: Bearer $SV_API_KEY" \
     "https://stock.tanggestock.com/openapi/v1/signals?symbol=BTC&interval=4h&limit=50"

# 增量:把上次响应里的 paging.nextSinceId 传回来
curl -H "Authorization: Bearer $SV_API_KEY" \
     "https://stock.tanggestock.com/openapi/v1/signals?since_id=10432"

端点

信号长什么样

{
  "signals": [
    {
      "id": 10433,
      "engine": "bull-bear",
      "market": "crypto",
      "symbol": "BTC",
      "interval": "4h",
      "signalTime": "2026-08-10T04:00:00.000Z",
      "tone": "bull",          // bull 看多 / bear 看空 / neutral 中性
      "kind": "多",             // 多 / 空 / 空转多 / 多转空
      "level": "normal",        // normal / important
      "price": 65132.13,        // 信号发生时的价格
      "text": "多头开始"
    }
  ],
  "paging": { "count": 1, "limit": 100, "nextSinceId": 10433, "hasMore": false }
}

我们只给信号本身：什么品种、什么周期、什么时候、看多还是看空、当时什么价。 自研引擎的计算方式属于平台核心资产，不在接口范围内 —— 这点在商务沟通里也是同样的口径。

Webhook：让信号自己找上门

不想轮询就用这个：把你的回调地址给我们，信号入库后几秒内我们主动 POST 给你。 省掉轮询，也省掉你的调用额度。

POST https://你的地址/hook
Content-Type: application/json
X-SV-Signature: sha256=<hmac>      # 必须验签
X-SV-Delivery:  7-10433              # 投递 id,用它去重
X-SV-Timestamp: 1786311537           # 秒级时间戳,可用于防重放

{
  "type": "signal.created",
  "deliveredAt": "2026-08-10T04:00:03.120Z",
  "signal": { "id": 10433, "engine": "bull-bear", "symbol": "BTC", "interval": "4h",
              "tone": "bull", "kind": "多", "price": 65132.13, "text": "多头开始" }
}

验签（务必做，否则任何人都能往你的接口灌假信号）：

// Node.js:注意要用**原始请求体**算,不能先 JSON.parse 再 stringify
const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-sv-signature']));

• 回调地址必须是 https。明文回调会让签名失去意义，我们直接拒收。
• 返回 2xx 视为成功；其它状态或超时（8 秒）算失败。
• 失败按 30s → 1m → 2m … 最长 1 小时退避重试，停在失败那条不跳过，所以你不会漏信号。
• 连续失败 20 次自动熔断，我们会联系你；修好后恢复，从熔断那条继续推。
• 可以只订阅一部分：按市场、品种、周期、引擎过滤，或者只要「重要」级别。

额度与限流

每把密钥有两个上限：每分钟调用数与每日调用数，具体数值按你的档位。每次响应都会带上：

X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset
X-Quota-Limit / X-Quota-Used

建议按 X-RateLimit-Remaining 自适应节奏；触发 429 时按 Retry-After 退避即可，不必重试风暴。

档位

Webhook 推送包含在所有付费档里，不另外收费——它省的是你的额度，不该再让你多花钱。 用量超了不会偷偷扣费，只会返回 429，你自己决定要不要升档。

错误码