API 与Webhook

概览

TruthPush 通过两种集成路径提供丰富的帖子事件（情绪、带符号的得分、交易代码和关键词）：

• 当受监控的个人资料发布内容时，Webhook (Webhooks) 会实时将 JSON 推送到您的 URL（商业版及以上）。
• 当您需要回填或恢复错过的事件时，REST 历史数据追溯可使用游标分页轮询按时间顺序排列的帖子（商业版及以上）。
• 升级到商业版后，在 TruthTerminal 中生成您的 API 令牌并配置您的Webhook URL。

Telegram 和电子邮件警报使用单独的频道；本参考仅涵盖程序化访问。

身份验证

REST 请求使用 Bearer 令牌。相同的密钥会对Webhook负载进行签名。

1. 升级到商业版或企业版。
2. 打开 TruthTerminal → 开发者中心 (Developer Hub) → 生成 API 密钥。
3. 在每个 REST 请求中发送 Authorization: Bearer YOUR_API_TOKEN。

curl "https://truthpush.com/api/v1/posts/catch-up?handle=realDonaldTrump&limit=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

请像对待密码一样对待您的 API 令牌。重新生成会立即使之前的令牌和Webhook签名失效。

Webhook

在 TruthTerminal 中生成 API 令牌后配置您的 Webhook URL。每个符合条件的帖子都会触发一个带有 JSON 正文和 TruthPush 签名标头的 HTTP POST 请求。必须先有 API 令牌 — 投递始终带签名。

请求标头

POST https://your-server.com/hooks/truthpush
Content-Type: application/json
X-TruthPush-Signature: t=<unix>,v1=<hmac_sha256_hex>
X-TruthPush-Event-Id: <post_id>

v1 = HMAC_SHA256(api_token, "<t>." + raw_body)

验证签名（Python）

接收方参考实现 — 检查重放窗口并在恒定时间内比较签名。

import hmac
import hashlib
import time

TOLERANCE_SECONDS = 300  # reject requests older than 5 minutes

def verify_signature(payload: bytes, secret: str, header: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    timestamp, signature = int(parts["t"]), parts["v1"]

    if abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False  # possible replay attack

    signed_payload = f"{timestamp}.".encode() + payload
    expected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

# Flask example
# signature_header = request.headers["X-TruthPush-Signature"]
# if not verify_signature(request.get_data(), API_TOKEN, signature_header):
#     abort(401)

信号过滤器

在 TruthTerminal 中设置最低绝对 signed_score（0 = 所有事件，0.7 = 仅强信号）以减少交易管道中的噪音。

投递速度

每个符合条件的帖子只会触发一次 Webhook 投递——包含原始帖子内容和分析完成后的情绪判断，会在 AI 情绪分析完成后立即发送（通常在几秒钟内）。投递使用独立队列，绝不会因为向其他用户发送 Telegram 或邮件通知而延迟。

重试

临时失败（网络错误、5xx、408、429）会在 60 秒、然后 5 分钟、再然后 15 分钟自动重试（最多三次）。永久的客户端错误（其他 4xx）不会重试 — 请修复端点并等待下一事件，或使用 REST catch-up。

REST API

GET /api/v1/posts/catch-up

使用游标分页按时间升序返回句柄的帖子。响应会被短暂缓存（约7秒），并支持 ETag / If-None-Match 以实现高效轮询。

查询参数

• handle — 不带 @ 的 Truth Social 用户名（必填）。使用 all（或未指定有效句柄）可获取完整关注列表。不在关注列表中的句柄返回空列表 — 绝不会扩展到其他资料。
• since — 用于第一次请求的 ISO 8601 锚点 (可选)
• cursor — 来自 meta.next_cursor 的不透明值 (可选)
• limit — 1–200，默认 100

分页示例

首次请求无需游标。每个响应都包含 meta.next_cursor — 将其作为 cursor 参数传入，直到返回 null。

# 1) First request — no cursor yet
curl "https://truthpush.com/api/v1/posts/catch-up?handle=realDonaldTrump&limit=100" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Response (truncated):
# { "posts": [ … 100 items … ],
#   "meta": { "next_cursor": "eyJpZCI6MTIzNDU2fQ==" } }

# 2) Follow-up request — pass the cursor from meta.next_cursor
curl "https://truthpush.com/api/v1/posts/catch-up?handle=realDonaldTrump&cursor=eyJpZCI6MTIzNDU2fQ%3D%3D&limit=100" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# meta.next_cursor is null once you've reached the latest post

事件对象

Webhook 与 REST 共享相同的丰富字段（sentiment、signed_score、score、tickers、keywords、reasoning、media）。信封结构不同：Webhook 使用 event_id、target、post_id 和 url；REST catch-up 使用 id 和 user_handle（以及展示元数据）。Webhook 中 event_id 等于 post_id — 供您在系统端做幂等去重。

{
  "event_id": "1234567890",
  "target": "realdonaldtrump",
  "post_id": "1234567890",
  "content": "Post text…",
  "url": "https://truthsocial.com/@realdonaldtrump/posts/1234567890",
  "media": [],
  "sentiment": "bullish",
  "signed_score": 0.89,
  "score": 0.89,
  "tickers": ["$DJT"],
  "keywords": ["tariffs", "trade"],
  "reasoning": "Direct market impact via trade policy.",
  "ai_analysis": { … }
}

event_id

稳定的事件 ID — 用于幂等处理

target

受监控的 Truth Social 句柄

sentiment

看涨 | 看跌 | 中性

signed_score

从 −1 到 +1 的方向性得分

tickers

提取的交易代码（例如 DJT）— 并非交易信号产品

keywords

从帖子内容中检测到的关键词

ai_analysis

旧版嵌套对象 — 数据相同，为向后兼容而保留

速率限制

限制适用于每个 API 令牌。超出限制将返回 HTTP 429 和 Retry-After。

• 商业版：60 次请求/分钟 · 10,000 次/天
• 企业版：300 次请求/分钟 · 500,000 次/天
• 响应包含 X-RateLimit-* 标头。

计划与访问权限

观察者或专业版不提供 API 和Webhook功能。TruthTerminal 实时动态从专业版开始提供；程序化访问从商业版开始。

错误

常见 API 响应：

• 401 — 缺少或无效的 Bearer 令牌
• 403 — 计划不包含 API 访问权限
• 429 — 超过速率限制；请遵守 Retry-After
• 400 — 游标无效或在归档窗口出现 upgrade_required_*