开发者：公开 API 与 Webhook

认证

在请求头里带上 X-API-Key: gl_…（也可以用 Authorization: Bearer gl_…）。密钥只在创建时显示一次，服务器只保存它的哈希。

curl -H "X-API-Key: gl_your_key" "https://<host>/api/v1/signals?timeframe=4h&limit=20"

频率限制

按密钥计：60 秒滑动窗口 + 每日额度（UTC 0 点重置）。响应头会返回 X-RateLimit-Limit / -Remaining / -Reset 和 X-RateLimit-Day-Remaining；超限返回 429 和 Retry-After。连续用错密钥的来源会被暂时限流。

数据口径：免费密钥看上一轮扫描（和网页免费版一致），Pro 看最新一轮。每条返回都带免责声明字段。

接口

• GET /api/v1/me

  当前密钥对应的套餐与额度

• GET /api/v1/lists

  三个榜单（强势、弱势、观察）

• GET /api/v1/signals

  当前轮的信号

  参数: timeframe, signal_type, bucket, symbol, intersect（逗号分隔，同时满足）, limit ≤ 400

• GET /api/v1/symbols/{symbol}

  单个合约：快照、信号、形态、已收盘 K 线

  参数: timeframe（默认 4h）, candles 0–1000（默认 200）

• GET /api/v1/performance

  信号表现与分级

  参数: days 7–365（默认 90）

• GET /api/v1/derivatives/{symbol}

  资金费率、持仓、多空比等合约数据

示例

curl -s -H "X-API-Key: gl_your_key" "https://<host>/api/v1/symbols/BTCUSDT?timeframe=1d&candles=50"

错误

401 密钥缺失或无效 · 404 合约或周期没有数据 · 429 超过频率或每日额度 · 400 参数不对。

Webhook

给开启了提醒的自选合约配置。每轮扫描如果有新信号，就向你的地址发送一次 POST，把这一轮所有新提醒合并在一起。只接受公网 http/https 地址，不跟随跳转，6 秒超时；连续失败 8 次会自动暂停；测试发送每小时 10 次。

格式：json（下面的结构）、discord（content 字段）、slack（text 字段）。

签名校验

请求头带 X-Guanlan-Timestamp 和 X-Guanlan-Signature = "sha256=" + HMAC_SHA256(密钥, 时间戳 + "." + 原始请求体)。请用原始字节计算，并拒绝 5 分钟以前的时间戳。

import hashlib, hmac, time

def verify(secret: str, headers: dict, raw_body: bytes) -> bool:
    ts = headers["X-Guanlan-Timestamp"]
    if abs(time.time() - int(ts)) > 300:
        return False
    expected = "sha256=" + hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, headers["X-Guanlan-Signature"])

其他请求头：X-Guanlan-Event（alert 或 test）、X-Guanlan-Delivery（每次投递的唯一 ID）。

JSON 结构

{
  "event": "alert",
  "sent_at": "2026-09-26T13:04:40+00:00",
  "scan_id": "scan_20260926_130404",
  "site": "https://…",
  "alerts": [
    {
      "symbol": "ETHUSDT",
      "title_zh": "ETHUSDT 有 2 条新的结构观察",
      "title_en": "ETHUSDT: 2 new structure notes",
      "lines_zh": ["4h 双顶：确认", "1h RSI 顶背离"],
      "lines_en": ["4h Double top: confirmed", "1h RSI bearish divergence"],
      "signals": [{ "timeframe": "4h", "signal_type": "double_top", "direction": "bearish" }],
      "url": "https://…/chart/ETHUSDT"
    }
  ],
  "note_zh": "…", "note_en": "…", "disclaimer_zh": "…", "disclaimer_en": "…"
}