OwlX · Signals API

Signals API 接线文件

把 OwlX 的结构信号接进你自己的交易机器人。这份文件写清楚怎麽拿 key、怎麽呼叫、每次扣多少、以及哪些事这支 API 不做。

⚠️ 这支 API 不会帮你下单

它只回传信号资料。它不连接你的交易所、不持有你的 API key、不下任何单、也不碰你的钱。

要自动交易，是你自己写程式：读我们的信号 → 用你自己的交易所 API key 送单。下单的决定与执行全部在你那一侧，风险与责任也是。

OwlX 提供的是市场结构的教育性资讯，不是投资建议，也不代客操作。

谁能用 · 怎麽计费

目前只开放给节点／创始席。

项目内容
开放对象节点／创始席（founding seat）。其他方案呼叫会收到 403 node_tier_required。
计费1 Token ／次呼叫。一次最多带 8 个币，所以把币合在一起打比较省。
节点内含10,000 次／月（节点月配 10,000 Token）。用完可到账户页加购 Token 包。
呼叫上限2,000 次／天，MYT 午夜重置。超过回 429。这只是防滥用的保险丝 —— 真正会先用完的是 Token。
其他端点news · movers · derivatives · macro · fundamentals · track-record 全部免费，不扣 Token。

用量参考：8 个币每 5 分钟轮询一次 = 8,640 次／月，约当月配的 86%。要盯更多币或打更密，就要加购。

一、拿到 API Key

  1. 到账户页owlx.app/account → 找到「API Key」那张卡
  2. 按「重新生成」完整 key 只显示这一次，先复制存好
  3. 怀疑外洩就再生一次旧 key 立刻失效，不用等

Key 放伺服器端的环境变数，绝对不要写进前端网页或公开的 repo —— 任何人拿到它就能花你的 Token。

二、呼叫

GET https://owlx.app/api/v1/signals
Header: x-api-key: owlx_live_xxxxxxxx
参数预设说明
symbolsBTC,ETH,SOL,BNB,XRP逗号分隔的币种，一次最多 8 个，超过的会被忽略。只写主体代号（BTC，不是 BTCUSDT）。
tf4h周期：15m 30m 1h 4h 1d。填错会退回 4h，不会报错。

三、回应

{
  "ok": true, "tf": "4h", "ts": 1756540000000,
  "signals": [
    {
      "symbol": "BTC", "tf": "4h", "ok": true,
      "price": 111234.5,
      "signal": "LONG",
      "confirmed": true,
      "defense": 108900,
      "arming": { "dir": 1, "score": 7, "trigger": 112000, "invalidation": 108900 },
      "atr_pct": 1.8
    }
  ],
  "tier": "node",
  "billing": "1 energy credit per call (node / founding seats only)",
  "credits_left": 9834
}
栏位意思
signalSTRONG_LONG · LONG · SHORT · STRONG_SHORT · NONE已经触发的信号。跟会员收到的 Telegram 提醒是同一个、同一时刻。
confirmed信号是否已在 K 线收盘确认。只在 true 时才该动作 —— 未收盘的信号会变。
defense防守位。信号失效的价格，一般拿来当止损。
arming还在酝酿中、尚未触发的那一笔：dir 方向、score 结构分 0–10、trigger 触发价、invalidation 失效价。用来提前布局，不是进场讯号。
atr_pct波动度（ATR 占价格的百分比）。常拿来算仓位大小。
credits_left这次扣完之後你还剩多少 Token。建议把它记进 log，快见底时才不会突然断线。
ok（单币）false 代表那个币这次读不到资料（新币、下架、上游暂时没回）。不要当成 NONE，跳过就好。

为什麽没有历史信号与回测

API 只提供「现在」。历史信号列表、胜率、回测结果不会经由 API 提供 —— 那些请在网站的图表页看。这是刻意的产品决定，不是漏了。

四、错误码

HTTPerror怎麽处理
401api_key_required
invalid_api_key		Header 没带 key，或 key 已被重新生成作废。重拿一把。
403node_tier_required这个帐号不是节点／创始席。重试没有用。
402insufficient_creditsToken 用完了。重试没有用 —— 要加购或等每月 1 号发放。程式该停下来并通知你，不要空转重打。
429rate_limited超过每日呼叫上限，MYT 午夜重置。降低轮询频率或把币合批。
403subscription_inactive订阅过期了，续订後 key 立刻恢复，不用重拿。

五、范例

curl -H "x-api-key: $OWLX_KEY" \
  "https://owlx.app/api/v1/signals?symbols=BTC,ETH,SOL,BNB,XRP,DOGE,ADA,LINK&tf=4h"

# 8 个币写在同一次 = 扣 1 Token
# 分成 8 次打  = 扣 8 Token
import os, requests

r = requests.get(
    "https://owlx.app/api/v1/signals",
    headers={"x-api-key": os.environ["OWLX_KEY"]},
    params={"symbols": "BTC,ETH,SOL", "tf": "4h"},
    timeout=20,
)

if r.status_code in (402, 403):
    # 重试没有用 —— 停下来通知自己
    raise SystemExit(r.json().get("message"))
r.raise_for_status()
d = r.json()

for s in d["signals"]:
    if not s.get("ok"):
        continue                      # 这个币这次没资料，跳过
    if s["signal"] != "NONE" and s["confirmed"]:
        print(s["symbol"], s["signal"], "stop:", s["defense"])
        # ↓ 这里换成【你自己的】交易所 API 下单

print("credits left:", d.get("credits_left"))
const r = await fetch(
  "https://owlx.app/api/v1/signals?symbols=BTC,ETH,SOL&tf=4h",
  { headers: { "x-api-key": process.env.OWLX_KEY } }
);

if (r.status === 402 || r.status === 403) {
  // 重试没有用 —— 停下来通知自己
  throw new Error((await r.json()).message);
}
const d = await r.json();

for (const s of d.signals) {
  if (!s.ok) continue;                // 这个币这次没资料
  if (s.signal !== "NONE" && s.confirmed) {
    console.log(s.symbol, s.signal, "stop:", s.defense);
    // ↓ 这里换成【你自己的】交易所 API 下单
  }
}
console.log("credits left:", d.credits_left);

六、几个实务建议

  1. 1–5 分钟轮询一次就够信号在 K 线收盘才确认。4h 周期打得比 5 分钟更密，只是烧自己的 Token，不会更早拿到东西。
  2. 把币合批一次 8 个币 = 1 Token；分 8 次 = 8 Token。同样的资料，八倍的价钱。
  3. 402 和 403 不要重试这两个重打一百次结果一样，只会把 log 洗掉。停下来发通知给自己。
  4. 盯着 credits_leftToken 归零机器人就断线。低於一天用量时先告警。（Token 掉到月配 15% 以下，我们也会主动 Telegram 通知你。）
  5. 只在 confirmed 为 true 时动作未收盘的信号会变。这一条不遵守，回测和实盘一定对不上。
  6. 别把它当唯一的风控上游资料可能暂时读不到（ok:false）。你的机器人要能处理「这一轮没拿到信号」，而不是把它当成平仓讯号。