API & ウェブフック

概要

TruthPushは、センチメント、署名付きスコア、ティッカー、キーワードなどのリッチな投稿イベントを、2つの統合パスを通じて配信します：

• 監視対象のプロファイルが投稿した際、ウェブフックがリアルタイムであなたのURLにJSONをプッシュします（Businessプラン以上）。
• RESTキャッチアップは、見逃したイベントのバックフィルや復元が必要な場合、カーソルページネーションを使用して時系列の投稿をポーリングします（Businessプラン以上）。
• Businessにアップグレード後、TruthTerminalでAPIトークンを生成し、ウェブフックURLを設定します。

Telegramおよびメールアラートは別チャネルを使用します。このリファレンスはプログラムによるアクセスのみを対象としています。

認証

RESTリクエストにはBearerトークンを使用します。同じシークレットがウェブフックのペイロードにも署名されます。

1. BusinessまたはEnterpriseにアップグレードします。
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トークンはパスワードと同様に扱ってください。再生成すると、以前のトークンとウェブフックの署名は即座に無効になります。

ウェブフック

APIトークンを生成したうえで、TruthTerminalでウェブフック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 = 強いシグナルのみ）。

配信スピード

条件を満たす投稿ごとに、ウェブフックはちょうど1回配信されます — 元の投稿内容と、AIによるセンチメント分析が完了した時点（通常は数秒以内）で送信される結果を合わせたものです。配信は専用キューで処理されるため、他ユーザーへのTelegramやメール配信によって遅延することはありません。

リトライ

一時的な失敗（ネットワークエラー、5xx、408、429）は、60秒後、次に5分後、さらに15分後に自動リトライされます（最大3回）。恒久的なクライアントエラー（その他の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 が含まれます — null が返るまで cursor パラメータとして渡してください。

# 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

イベントオブジェクト

ウェブフックとRESTは同じエンリッチメントフィールド（sentiment、signed_score、score、tickers、keywords、reasoning、media）を共有します。エンベロープは異なります: ウェブフックは event_id、target、post_id、url を使用し、REST catch-up は id と user_handle（および表示用メタデータ）を使用します。ウェブフックでは 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

bullish | bearish | neutral

signed_score

−1から+1までの方向性スコア

tickers

抽出されたティッカー（例: DJT）— トレーディングシグナル商品ではありません

keywords

投稿コンテンツから検出されたキーワード

ai_analysis

旧仕様のネストされたオブジェクト — 同一データ、後方互換性のために保持

レートリミット

制限はAPIトークンごとに適用されます。超過した場合、Retry-Afterを伴うHTTP 429が返されます。

• Business: 60リクエスト/分 · 10,000回/日
• Enterprise: 300リクエスト/分 · 500,000回/日
• レスポンスには X-RateLimit-* ヘッダーが含まれます。

プランとアクセス

APIおよびウェブフックは、ObserverまたはProfessionalでは利用できません。TruthTerminalのライブフィードはProfessionalから利用可能。プログラムによるアクセスはBusinessから開始されます。

エラー

一般的なAPIレスポンス:

• 401 — Bearerトークンの欠落または無効
• 403 — プランにAPIアクセスが含まれていません
• 429 — レートリミット超過。Retry-Afterに従ってください
• 400 — 無効なカーソル、またはアーカイブウィンドウからの upgrade_required_*