開発者向けリファレンス

API & ウェブフック

Truth SocialのアラートをトレーディングBot、ダッシュボード、自動化パイプラインに統合します。ウェブフックおよびRESTアクセスにはBusinessプラン以上が必要です。

Business+

Getting started

Programmatic access works differently from Telegram and email alerts: instead of reading a notification, your own application processes the events. Here's how to set it up.

  1. 1 Upgrade to Business or Enterprise — API and webhooks are included from Business.
  2. 2 Open TruthTerminal and generate an API token in the Developer Hub section.
  3. 3 Set your webhook URL in TruthTerminal, or start sending REST requests with the token directly.

Telegram and email alerts remain available on every plan independent of this — this section covers programmatic access (webhook/REST) only.

Use case: Trading → Truth Social API alternative → Compare plans → Back to overview →

概要

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

ウェブフック

TruthTerminalでウェブフックURLを設定します。条件を満たす各投稿が、JSONボディとTruthPush署名ヘッダーを含むHTTP POSTをトリガーします。

リクエストヘッダー 

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)

Verify the signature (Python)

Reference implementation for receivers — checks the replay window and compares the signature in constant time. 

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やメール配信によって遅延することはありません。

REST API

GET /api/v1/posts/catch-up

カーソルページネーションを使用して、ハンドル名に対する投稿を時系列の昇順で返します。レスポンスは短時間キャッシュされ（約7秒）、効率的なポーリングのためにETag / If-None-Matchをサポートします。

クエリパラメータ

  • handle — handle — @なしのTruth Socialユーザー名 (必須)
  • since — since — 最初のリクエスト用のISO 8601アンカー (任意)
  • cursor — cursor — meta.next_cursorからの不透明な値 (任意)
  • limit — limit — 1–200、デフォルト100

Pagination example

Start with the first request without a cursor. Every response includes meta.next_cursor — pass it unchanged into the next request until it is 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

イベントオブジェクト

ウェブフックのペイロードとRESTの投稿オブジェクトは、同じエンリッチメントフィールドを共有します。クライアント側での重複排除のため、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_*