Fansly API Schnellstart: Authentifizierung, Endpoints und HMAC-Webhook-Verifizierung

Die Creator Economy hat sich von isolierten Social-Media-Profilen zu digitalen Unternehmen mit hohem Durchsatz entwickelt. Auf Plattformen mit mehr als 130 Millionen registrierten Nutzern ist es für Agenturen und Anbieter von Enterprise-Tools keine tragfähige Strategie mehr, mehrere Creator-Accounts von Hand oder über fragile, per Reverse Engineering gebaute Scraping-Skripte zu verwalten. Dieser Schnellstart-Leitfaden dient als umfassende API-Dokumentation für Entwickler, die skalierbare CRMs, Tools für Massennachrichten und Umsatz-Dashboards bauen wollen.

Ob du nativ integrierst oder Workflow-Orchestratoren nutzt: Für einen produktionsreifen Einsatz musst du wissen, wie du API-Keys verwaltest, ganzzahlige Währungsformate verarbeitest und Webhooks einer Echtzeit-API sicher verifizierst.

Was ist die Fansly API?

Die Fansly API ist eine Entwicklerplattform auf Enterprise-Niveau, entwickelt von Fans Holdings OÜ, die Headless-Browser-Automatisierung durch offizielle, stabile Infrastruktur ersetzt. Sie ist für Creator-Management-Agenturen und SaaS-Plattformen gebaut und stellt über 200 aktive REST-API-Endpoints für Messaging, CRM-Profile, Transaktionen und Media-Vaults bereit.

Mit einer Produktionsbilanz von über 5.000 verbundenen Creator-Accounts und mehr als 150 Millionen verarbeiteten Requests ohne eine einzige Plattform-Sperre bietet die Fansly API eine sichere Umgebung, um Accounts zu skalieren. Dazu kommt eine Push-Architektur in Echtzeit über kryptografisch signierte Webhooks, die das Credit-intensive Dauer-Polling überflüssig macht.

Schritt 1: API-Authentifizierung und Verwaltung der API-Keys

Eine sichere API-Authentifizierung ist das Fundament deiner Integration. Die Plattform nutzt Bearer-Token-Authentifizierung: Entwickler übergeben bei jedem Request ein sicheres Token in den HTTP-Headern.

API-Keys erzeugen und eingrenzen

Um mit der Plattform zu arbeiten, musst du deine HTTP-Clients mit API-Keys authentifizieren, die du in deinem Entwickler-Dashboard erzeugst. Laut dem Fansly API Integrationsleitfaden gehst du so vor:

1. Account registrieren: Lege einen Account auf der Fansly API-Plattform an. Neue Entwickler erhalten ein Sandbox-Kontingent von 100 kostenlosen Willkommens-Credits, um Live-Verbindungen zu testen.
2. API-Key erstellen: Öffne app.onlyfansapi.com/api-keys und erzeuge einen Key. Keys sind nicht eingegrenzt: Jeder Key kann jeden Endpoint für jeden Account aufrufen, der mit deinem Team verbunden ist. Erstelle deshalb einen Key pro Integration und rotiere jeden Key, den du an einen externen Entwickler weitergibst.
3. Secrets schützen: Speichere deine API-Keys in einer sicheren Laufzeitumgebung, etwa im AWS Secrets Manager oder in verschlüsselten .env-Dateien. Committe sie niemals in eine öffentliche Versionsverwaltung.

Standard-Request-Header

Jeder eingehende Request braucht bestimmte HTTP-Header, die den Payload-Typ festlegen, den Client authentifizieren und gezielt einzelne Creator-Accounts ansprechen.

cURL-Beispiel zur Authentifizierung:

curl -X GET "https://app.onlyfansapi.com/api/fansly/fansly_acct_XXXXXXXXXXXXXXX/chats" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Schritt 2: Die zentralen API-Endpoints

Nach der Authentifizierung haben Entwickler Zugriff auf über 200 aktive API-Endpoints in sechs Hauptbereichen. Mit diesen Endpoints steuerst du komplexe Agentur-Workflows programmatisch.

• Accounts & Sessions: Endpoints wie /api/v1/accounts verbinden Creator-Accounts per 2FA und prüfen den Zustand der Proxy-Sessions.
• Messaging: Mit /api/v1/chats und /api/v1/messages/mass liest du Direktnachrichten, schickst Chatbot-Antworten in Echtzeit oder stellst PPV-Massenversände in die Warteschlange.
• Fans & CRM: Frage über /api/v1/fans die Ausgabenhistorie, Abo-Daten und Engagement-Stufen deiner Fans ab.
• Finanzen: Gleiche Bruttoumsatz, Plattformanteil, Netto-Auszahlungen und Conversions von Tracking-Links mit /api/v1/earnings/summary ab.
• Media & Vault: Lade Mediendateien hoch (bis zu 1 GB per Remote-URL) und veröffentliche über /api/v1/vault/media Feed-Posts, die an eine Abo-Stufe gebunden sind.

Schritt 3: Integrität von Finanzdaten (das Millidollar-Format)

Ein häufiger Integrationsfehler bei Plattformen der Creator Economy ist der falsche Umgang mit Währungen. Normale Gleitkommaoperationen nach IEEE 754 (etwa 0.1 + 0.2 in JavaScript) erzeugen Rundungsabweichungen, die sich über Tausende PPV-Freischaltungen und Trinkgelder zu spürbaren Buchhaltungsfehlern aufsummieren.

Um die Integrität der Finanzdaten zu sichern, stellt Fansly Währungsbeträge in Tausendstel Dollar (Millidollar) dar.

• $1,00 USD = 1000
• $5,00 USD = 5000
• $15,50 USD = 15500
• $0,05 USD (5 Cent) = 50

Umrechnungsbeispiel in TypeScript

Wenn du Dashboards baust, runde deine Umrechnungen immer, um Anomalien in der Zwischendarstellung zu vermeiden:

export class FanslyCurrency {
  public static toMillidollars(dollars: number | string): number {
    const parsed = typeof dollars === 'string' ? parseFloat(dollars) : dollars;
    if (isNaN(parsed) || !isFinite(parsed)) throw new TypeError('Invalid amount');
    return Math.round(parsed * 1000);
  }
 
  public static toFormattedUSD(millidollars: number): string {
    return new Intl.NumberFormat('en-US', {
      style: 'currency',
      currency: 'USD',
    }).format(millidollars / 1000);
  }
}

Schritt 4: HTTP-Statuscodes und Fehlerbehandlung

Die Plattform hält sich an die Standard-HTTP-Antwortcodes nach RFC 7231. Laut Preisen und RPM-Architektur der Fansly API ist der Umgang mit Rate-Limits (429) je nach Plan besonders wichtig (1.000 RPM bei Basic gegenüber 5.000 RPM bei Pro).

Schritt 5: Eine Echtzeit-API mit HMAC-Webhooks umsetzen

Der Wechsel vom Dauer-Polling zu einer Push-Architektur in Echtzeit bringt deutliche finanzielle und technische Vorteile. Laut dem Fansly-Webhooks-Leitfaden verbrennt das minütliche Polling eines aktiven Creator-Portfolios mit 20 Creators rund 28.800 Credits pro Tag. Webhooks dagegen kosten nur 1 Credit pro 100 Events und liefern Daten mit Latenzen unter einer Sekunde.

Webhook-Sicherheit und Signaturprüfung

Wenn ein Webhook-Event (etwa tip.received oder message.received) ausgelöst wird, geht der Payload per POST-Request an deine registrierte HTTPS-URL. Als Nachweis, dass das Event von Fansly stammt, enthält er einen X-Fansly-Signature-Header, der per HMAC-SHA256 berechnet wird.

Sicherheitspflicht: Du musst den HMAC-Hash gegen den rohen, ungeparsten String-Buffer des Request-Bodys prüfen. Außerdem muss der Vergleich in konstanter Zeit laufen, um Timing-Angriffe zu verhindern, wie in RFC 2104 beschrieben.

Referenz zur Verifizierung mit Node.js / Express

import express, { Request, Response } from 'express';
import { createHmac, timingSafeEqual } from 'crypto';
 
const app = express();
 
// Rohen Body-Buffer für die Verifizierung erfassen
app.use(express.json({
  verify: (req: any, _res, buf) => {
    req.rawBody = buf;
  }
}));
 
const WEBHOOK_SECRET = process.env.FANSLY_WEBHOOK_SECRET;
const processedEvents = new Set<string>();
 
app.post('/api/fansly/webhook', (req: Request, res: Response): any => {
  const signature = req.headers['x-fansly-signature'] as string;
  const rawBody = (req as any).rawBody;
 
  if (!signature || !rawBody) return res.status(400).send('Missing signature');
 
  // 1. Erwarteten HMAC-SHA256-Hash berechnen
  const computedHash = createHmac('sha256', WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');
 
  // 2. Signatur in konstanter Zeit prüfen
  const signatureBuffer = Buffer.from(signature, 'utf8');
  const computedBuffer = Buffer.from(computedHash, 'utf8');
 
  if (signatureBuffer.length !== computedBuffer.length || !timingSafeEqual(signatureBuffer, computedBuffer)) {
    return res.status(401).send('Signature verification failed');
  }
 
  // 3. Replay-Angriffe über Idempotency-Keys verhindern
  const event = req.body;
  const idempotencyKey = event.idempotencyKey || event.id;
 
  if (processedEvents.has(idempotencyKey)) {
    return res.status(200).json({ status: 'duplicate_ignored' });
  }
  processedEvents.add(idempotencyKey);
 
  // Event verarbeiten und schnell bestätigen
  return res.status(200).json({ received: true });
});

Fazit

Leistungsstarke Creator-Management-Tools brauchen eine solide API-Dokumentation und sichere Abläufe. Wenn du API-Keys richtig eingrenzt, dich bei Finanzdaten an den Millidollar-Standard hältst und eine sichere Echtzeit-API-Verbindung mit HMAC-Webhook-Verifizierung aufbaust, umgehst du die Unzuverlässigkeit von Scraping-Skripten. Mit der umfangreichen Bibliothek an API-Endpoints, die die Fansly-Plattform bereitstellt, skaliert deine Agentur-Infrastruktur effizient, sicher und profitabel.