API & Webhooks

Überblick

TruthPush liefert angereicherte Post-Events — Sentiment, signierter Score, Ticker und Keywords — über zwei Integrationspfade:

• Webhooks senden JSON in Echtzeit an Ihre URL, sobald ein überwachtes Profil postet (Business+).
• REST Catch-up liefert chronologische Posts mit Cursor-Pagination zum Nachziehen verpasster Events (Business+).
• API-Token erzeugen und Webhook-URL im TruthTerminal einrichten — nach Upgrade auf Business.

Telegram- und E-Mail-Alerts nutzen separate Kanäle; diese Referenz beschreibt nur den programmatischen Zugang.

Authentifizierung

REST-Anfragen nutzen ein Bearer-Token. Dasselbe Secret signiert Webhook-Payloads.

1. Auf Business oder Enterprise upgraden.
2. TruthTerminal öffnen → Developer Hub → API Key generieren.
3. Bei jeder REST-Anfrage Authorization: Bearer YOUR_API_TOKEN mitsenden.

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

API-Token wie ein Passwort behandeln. Regenerieren macht das alte Token und alle Webhook-Signaturen sofort ungültig.

Webhooks

Webhook-URL im TruthTerminal konfigurieren — nachdem ein API-Token erzeugt wurde. Jeder qualifizierende Post löst einen HTTP POST mit JSON-Body und TruthPush-Signatur-Headern aus. Das API-Token ist Pflicht — Zustellungen sind immer signiert.

Request-Header

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)

Signatur verifizieren (Python)

Referenz-Implementierung für Empfänger — prüft das Replay-Fenster und vergleicht die Signatur in konstanter Zeit.

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)

Signal-Filter

Mindest-|signed_score| im TruthTerminal setzen (0 = alle Events, 0,7 = nur starke Signale) — reduziert Rauschen in Trading-Pipelines.

Zustellgeschwindigkeit

Jeder qualifizierende Post löst genau eine Webhook-Zustellung aus — den Rohtext plus fertiges Sentiment, gesendet sobald die KI-Anreicherung abgeschlossen ist (meist innerhalb von wenigen Sekunden). Die Zustellung läuft über eine eigene Queue und wird nie durch Telegram- oder E-Mail-Zustellung an andere Nutzer verzögert.

Wiederholungen

Temporäre Fehler (Netzwerk, 5xx, 408, 429) werden automatisch nach 60 Sekunden, dann 5 Minuten, dann 15 Minuten erneut versucht (bis zu drei Retries). Permanente Client-Fehler (andere 4xx) werden nicht wiederholt — Endpoint korrigieren und auf das nächste Event warten oder REST Catch-up nutzen.

REST API

GET /api/v1/posts/catch-up

Liefert Posts eines Handles in aufsteigender chronologischer Reihenfolge mit Cursor-Pagination. Antworten sind kurz gecacht (~7 s) und unterstützen ETag / If-None-Match für effizientes Polling.

Query-Parameter

• handle — Truth-Social-Username ohne @ (Pflicht). all (oder ohne sinnvolle Handles) liefert die volle Watchlist. Handles außerhalb der Watchlist ergeben eine leere Liste — sie werden nie auf andere Profile ausgeweitet.
• since — ISO-8601-Anker für den ersten Abruf (optional)
• cursor — opaker Wert aus meta.next_cursor (optional)
• limit — 1–200, Standard 100

Pagination-Beispiel

Bei der ersten Anfrage ohne cursor beginnen. Jede Antwort enthält meta.next_cursor — diesen Wert unverändert in die nächste Anfrage übernehmen, bis er null ist.

# 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

Event-Objekt

Webhook und REST teilen dieselben Anreicherungsfelder (sentiment, signed_score, score, tickers, keywords, reasoning, media). Das Envelope unterscheidet sich: Webhooks nutzen event_id, target, post_id und url; REST Catch-up nutzt id und user_handle (plus Anzeige-Metadaten). Bei Webhooks entspricht event_id der post_id — für idempotente Verarbeitung auf Empfängerseite.

{
  "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

Stabile Event-ID — für idempotente Verarbeitung

target

Überwachtes Truth-Social-Handle

sentiment

bullish | bearish | neutral

signed_score

Richtungs-Score von −1 bis +1

tickers

Extrahierte Ticker (z. B. DJT) — kein eigenes Trading-Signal-Produkt

keywords

Erkannte Keywords aus dem Post-Text

ai_analysis

Legacy verschachteltes Objekt — gleiche Daten, Rückwärtskompatibilität

Rate-Limits

Limits gelten pro API-Token. Überschreitung liefert HTTP 429 mit Retry-After.

• Business: 60 Anfragen/Minute · 10.000/Tag
• Enterprise: 300 Anfragen/Minute · 500.000/Tag
• Antworten enthalten X-RateLimit-*-Header.

Tarife & Zugang

API und Webhooks sind auf Observer und Professional nicht verfügbar. TruthTerminal-Live-Feed ab Professional; programmatischer Zugang ab Business.

Fehler

Häufige API-Antworten:

• 401 — fehlendes oder ungültiges Bearer-Token
• 403 — Tarif ohne API-Zugang
• 429 — Rate-Limit überschritten; Retry-After beachten
• 400 — ungültiger Cursor oder upgrade_required_* aus Archiv-Fenster