FastCoins Publisher-API
Dokumentation

FastCoins ist ein PTC-Netzwerk (Paid-To-Click) für Publisher. Binde unsere Werbung auf deiner Seite ein, deine Nutzer verdienen Token-Belohnungen beim Ansehen, und du erhältst automatisch einen Anteil der Einnahmen.

Erstelle ein Publisher-Konto, bestätige, dass die Domain dir gehört, und erhalte deine API-Zugangsdaten, sobald sie geprüft ist.

• 1
  Erstelle ein Publisher-Konto unter FastCoins.com/publisher_dashboard. Du brauchst einen Seitennamen und eine URL.
• 2
  Füge eine Domain hinzu im Tab „Domains“. Jede Domain hat ihren eigenen API Key, Secret Key, Bearer Token, Token-Konfiguration und Postback-URL.
• 3
  Lege deine Postback-URL fest — den Endpoint auf deinem Server, der Belohnungs-Benachrichtigungen empfängt (siehe Abschnitt Postback unten).
• 4
  Erzeuge einen Bearer Token im Tab „Domains“. Erforderlich, um PTC-API-Aufrufe zu authentifizieren.
• 5
  Sende einen Test-Postback aus dem Tab „Domains“, um zu prüfen, ob dein Endpoint korrekt antwortet, bevor du live gehst.

Eine Server-zu-Server-Benachrichtigung, die an deine Website gesendet wird, wenn ein Nutzer das Ansehen einer Werbung abgeschlossen hat — so kannst du Belohnungen automatisch gutschreiben, ganz ohne clientseitigen Code.

🔐 Sicherheitsanforderungen

• Autorisierte Server-IPs: 62.171.140.250, 2a02:c207:2329:8601::1 — prüfe das ausschließlich gegen $_SERVER['REMOTE_ADDR']. Das ist ein direkter Server-zu-Server-Aufruf, keine Browser-Anfrage, es liegt also kein Proxy/CDN von uns dazwischen; ein Header wie X-Forwarded-For wird vom Client geliefert und ist trivial zu fälschen — verlass dich dafür nicht darauf.
• userIp ist Pflicht, nicht nur informativ — weise den Callback zurück, wenn er fehlt oder keine gültige IP ist. Wir lösen immer die echte IP des Nutzers auf, der die Werbung abgeschlossen hat (über Cloudflare auf unserer Seite), und senden sie gerade deshalb, damit du dich bei Fraud-Erkennung, IP-Limits und Duplikatsprüfungen darauf verlassen kannst — ein Endpoint, der sie ignoriert, verliert dieses Signal komplett.
• Erforderliche HTTP-Antwort: exakt ok — Kleinbuchstaben, keine Leerzeichen, kein HTML, HTTP 200
• Signaturalgorithmus (empfohlen): signature_sha256 = HMAC-SHA256(subId + transId + reward, secret_key) — secret_key ist der HMAC-Schlüssel, er wird nicht an die Nachricht angehängt. userIp ist kein Bestandteil davon.
• Signaturalgorithmus (veraltet, wird bei jedem Callback weiterhin mitgesendet): signature = MD5(subId + transId + reward + secret_key) — Werte ohne Trennzeichen aneinandergereiht. Bleibt unbefristet funktionsfähig für Integrationen, die es vor signature_sha256 gab; nichts zu ändern, wenn du diese bereits prüfst.
• Mehr als 8 Dezimalstellen nötig? Jeder Callback trägt zusätzlich reward_precise (10 Dezimalstellen) mit seiner eigenen signature_sha256_precise = HMAC-SHA256(subId + transId + reward_precise, secret_key) — komplett optional und additiv, genauso berechnet, nur über die präzisere Zeichenkette. reward/signature_sha256/signature werden unabhängig davon genau wie bisher gesendet.
• Dublettenschutz: prüfe transId immer in deiner Datenbank, bevor du gutschreibst

📋 Postback-Parameter (GET)

Deine Postback-URL erhält diese Parameter per HTTP GET.

🧮 Beispiel: Aufbau und Prüfung einer signierten URL

Ein vollständig durchgerechnetes Beispiel, damit du deine eigene Signaturberechnung vor dem Live-Gang mit unserer abgleichen kannst. Der verwendete Secret Key ist ausgedacht und dient rein der Veranschaulichung.

Secret Key (example only, never a real one): demo_secret_do_not_use_9f8e7d6c

Parameters for this conversion:
  subId   = user_12345
  transId = txn_987654321
  reward  = 0.50
  status  = 1
  userIp  = 127.0.0.1

signature_sha256 = HMAC-SHA256(subId + transId + reward, secret_key)
                  = HMAC-SHA256("user_12345" . "txn_987654321" . "0.50", demo_secret_do_not_use_9f8e7d6c)
                  = HMAC-SHA256("user_12345txn_9876543210.50", demo_secret_do_not_use_9f8e7d6c)
                  = df3eafaa3e8cf4fe8fb40c7bed633f34bc7b964bca58d2d691314771a042d59c

signature (legacy) = MD5(subId + transId + reward + secret_key)
                    = MD5("user_12345" . "txn_987654321" . "0.50" . "demo_secret_do_not_use_9f8e7d6c")
                    = MD5("user_12345txn_9876543210.50demo_secret_do_not_use_9f8e7d6c")
                    = d1eb68e41cbd5770de9384c5be8ebb39

Resulting callback URL:
https://yoursite.com/postback.php?subId=user_12345&transId=txn_987654321&reward=0.50&status=1&userIp=127.0.0.1&signature=d1eb68e41cbd5770de9384c5be8ebb39&signature_sha256=df3eafaa3e8cf4fe8fb40c7bed633f34bc7b964bca58d2d691314771a042d59c

📐 Optional: 10-Dezimalstellen-Präzision (reward_precise)

Gleicher Secret Key, gleicher Callback — nur eine Belohnung mit mehr Nachkommastellen, als die 8 Dezimalstellen von reward fassen können. Rein additiv: überspringe das, wenn 8 Dezimalstellen für deinen Fall genügen.

Same secret key and subId/transId as above, but the underlying reward this
time carries more precision:

  reward          = 0.12345679   (8 decimals, rounded)
  reward_precise  = 0.1234567890 (10 decimals)

signature_sha256_precise = HMAC-SHA256(subId + transId + reward_precise, secret_key)
                          = HMAC-SHA256("user_12345" . "txn_987654321" . "0.1234567890", demo_secret_do_not_use_9f8e7d6c)
                          = 219d2101a528b8585161bd26c3bb80c5de8a6741d60d2f1778eb805a05f7a707

💻 PHP-Implementierung — postback.php

Speichere das auf deinem Server, hinterlege deinen Secret Key aus dem Tab „Domains“ und füge die vollständige URL ins Feld Postback URL deiner Domain ein.

// ── 1. YOUR SECRET KEY (from Domains tab → Secret Key) ─────
$secret = "";  // ← paste your secret key here

// ── 2. IP VALIDATION (callback source) ──────────────────────
// REMOTE_ADDR only — this call comes straight from our server to
// yours, no browser and no proxy of ours in between, so it's the
// one value here that can't be spoofed by whoever is calling you.
// X-Forwarded-For (or any other header) is attacker-controlled and
// must never be trusted for this check.
$allowed_ips = ['62.171.140.250', '2a02:c207:2329:8601::1'];
$ip = $_SERVER['REMOTE_ADDR'] ?? '';
if (!in_array($ip, $allowed_ips, true)) {
    echo "ERROR: Invalid source IP";
    exit;
}

// ── 3. COLLECT PARAMETERS ───────────────────────────────────
$userId    = $_GET['subId']     ?? null;
$transId   = $_GET['transId']   ?? null;
$status    = $_GET['status']    ?? null;
$isTest    = isset($_GET['test']) && $_GET['test'] == 1;
$userIp    = $_GET['userIp']   ?? null;  // real IP of the ad viewer — required, see step 4

// ── 3b. DYNAMIC PRECISION ────────────────────────────────────
// Prefer reward_precise (10 decimals) when the callback carries it;
// fall back to the standard reward (8 decimals) otherwise. Whichever
// pair is picked, it's verified against its own matching signature in
// step 6 — if that signature is valid, the postback is accepted.
$hasPrecise = isset($_GET['reward_precise'], $_GET['signature_sha256_precise']);
$reward    = $hasPrecise ? $_GET['reward_precise']           : ($_GET['reward'] ?? null);
$signature = $hasPrecise ? $_GET['signature_sha256_precise'] : ($_GET['signature_sha256'] ?? null);

// ── 4. VALIDATE USER IP (required) ──────────────────────────
// userIp is mandatory — this is the real IP of the person who
// completed the offer, already resolved through Cloudflare on our
// end. Reject the callback outright rather than silently accepting
// one without it, since your fraud detection / IP-limit / duplicate-
// user checks depend on this value actually being present and valid.
if (!$userIp || !filter_var($userIp, FILTER_VALIDATE_IP)) {
    echo "ERROR: Invalid user IP";
    exit;
}

// ── 5. VALIDATE REQUIRED PARAMS ─────────────────────────────
if (!$userId || !$transId || $reward === null || !$signature) {
    echo "ERROR: Missing parameters";
    exit;
}

// ── 6. VERIFY SIGNATURE ─────────────────────────────────────
// Only subId + transId + reward go into this hash — userIp is NOT
// part of it. $secret is the HMAC key, not concatenated into the
// message. Don't add userIp here unless a different provider's docs
// explicitly say their signature scheme includes it.
$expected = hash_hmac('sha256', $userId . $transId . $reward, $secret);
if (!hash_equals($expected, $signature)) {
    echo "ERROR: Signature mismatch";
    exit;
}

// ── 7. HANDLE CHARGEBACK (status = 2) ───────────────────────
if ((int)$status === 2) {
    $reward = -abs((float)$reward);  // negative = deduct
}

// ── 8. TEST CALLBACK ─────────────────────────────────────────
// Authenticated and validated like any other callback, but must not
// touch a real balance.
if ($isTest) {
    echo "ok";
    exit;
}

// ── 9. PREVENT DUPLICATES, CREDIT REWARD & STORE USER IP ──────
// Replace with your actual DB logic.
if (!isTransactionProcessed($transId)) {
    creditUserReward($userId, $reward, $transId);
    // If your credit function only takes these 3 args, store $userIp
    // with the conversion separately, e.g.:
    //   saveConversionIp($transId, $userId, $userIp);
}

// ── 10. REQUIRED RESPONSE ───────────────────────────────────
echo "ok";  // MUST return exactly this, nothing else

🕓 Veraltete Prüfung — MD5

$signature = $_GET['signature'] ?? null;
$expected  = md5($userId . $transId . $reward . $secret);
if (!hash_equals($expected, $signature)) {
    echo "ERROR: Signature mismatch";
    exit;
}
// ...same IP check, userIp check, and crediting logic as the main example above.

🔀 Callback-Ablauf

• 1
  Callback empfangen
• 2
  Prüfe REMOTE_ADDR gegen die IP-Whitelist
• 3
  Lies die Parameter, einschließlich userIp
• 4
  Validiere userIp — zurückweisen, wenn er fehlt oder keine gültige IP ist
• 5
  Validiere die übrigen Pflichtparameter
• 6
  Prüfe die Signatur
• 7
  Prüfe status — als Chargeback buchen, wenn 2
• 8
  Wenn test=1, gib ok zurück, ohne etwas gutzuschreiben
• 9
  Prüfe transId gegen deine Datenbank, um doppelte Gutschriften zu verhindern
• 10
  Schreibe die Belohnung gut oder storniere sie, und speichere userIp zusammen mit der Konversion
• 11
  Gib ok zurück

Mögliche Antworten:

• ok — Callback verarbeitet (oder als Test-Callback validiert)
• ERROR: Invalid source IP
• ERROR: Invalid user IP
• ERROR: Missing parameters
• ERROR: Signature mismatch

Frage verfügbare PTC-Werbung über eine REST-API ab und rendere sie mit deiner eigenen Oberfläche. Kein Widget-Einbau nötig.

🌐 Endpoint

🔑 Authentifizierung — Bearer Token

💻 PHP-Beispiel

// ── YOUR CREDENTIALS (from Domains tab) ─────────────────────
$apiKey      = 'YOUR_API_KEY';
$bearerToken = 'YOUR_BEARER_TOKEN';

// ── USER DATA ────────────────────────────────────────────────
$userId = $_SESSION['user_id'];  // your user's unique ID
// REMOTE_ADDR by default — it's the one value here that can't be
// spoofed by the visitor. Only read a proxy header instead (e.g.
// CF-Connecting-IP) if your own server sits behind a reverse proxy
// you control and trust — never a client-supplied header like
// X-Forwarded-For, which the visitor's own browser can set to
// anything.
$userIp = $_SERVER['REMOTE_ADDR'] ?? '';

// Required once any advertiser runs a device-targeted campaign — this
// script call happens during the visitor's own page load, so THIS
// server's incoming User-Agent is theirs. Don't skip this: a call from a
// background job/cron with no real visitor attached has no correct value
// to send here.
$userAgent = $_SERVER['HTTP_USER_AGENT'] ?? '';
$device    = preg_match('/Mobi|Android|iPhone|iPod|iPad|BlackBerry|IEMobile|Opera Mini/i', $userAgent)
    ? 'mobile' : 'desktop';

// ── BUILD URL ────────────────────────────────────────────────
$url = 'https://FastCoins.com/api/' . $apiKey
     . '/' . urlencode($userId)
     . '/' . urlencode($userIp)
     . '/' . $device;

// ── CURL REQUEST ─────────────────────────────────────────────
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $bearerToken,
        'Accept: application/json',
    ],
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

// ── HANDLE RESPONSE ──────────────────────────────────────────
if ($httpCode === 200 && $data['status'] === '200') {
    foreach ($data['data'] as $ad) {
        // $ad['url'] already contains the user subId encoded
        echo '<a href="' . htmlspecialchars($ad['url']) . '" target="_blank">';
        echo htmlspecialchars($ad['title']);
        echo ' — ' . $ad['reward'] . ' ' . $ad['currency_name'];
        echo '</a><br>';
    }
} else {
    echo 'No ads available.';
}

📦 Antwortformat

Erfolgreiche Antworten liefern HTTP 200 mit dieser JSON-Struktur:

⚠️ Fehlercodes

Fehlerantworten teilen dieselbe JSON-Struktur mit einem Statusfeld ungleich 200.

Der Ablauf von Anfang bis Ende: vom API-Aufruf bis zur Belohnungsgutschrift auf deiner Seite.

📡 API + Postback-Ablauf

🧩 Widget-Einbau (Alternative)

Wenn du die API nicht nutzen willst, binde das Widget als iframe ein — es erledigt alles automatisch, stilistisch isoliert vom Rest deiner Seite.

<iframe src="https://fastcoins.click/widget-embed.php?api_key=YOUR_API_KEY&sub_id={USER_ID}"
    style="width:100%;height:640px;border:none;" loading="lazy"></iframe>

Erstelle eine Aufgabe (z. B. "registriere dich auf meiner Seite"), hinterlege Geld für N Abschlüsse und bestätige jeden mit einem signierten Server-zu-Server-Postback. Der Nutzer wird automatisch gutgeschrieben, sobald dein Postback ankommt — keine manuelle Freigabe, keine Plattform-Rücklage.

📡 So funktioniert es

1) Die Postback-URL

GET https://fastcoins.click/webhooks/task-postback.php?cka_cid={CLICK_ID}&sign={SIGN}

• cka_cid — die Click-ID, die wir an deine Ziel-URL angehängt haben, als der Nutzer startete (your-url?cka_cid=…). Gib sie unverändert zurück.
• sign — hash_hmac('sha256', $cka_cid, $task_secret) (Hex in Kleinbuchstaben). Das aufgabenspezifische Secret wird unter Create Task → My Tasks angezeigt.

2) Signatur

// PHP
$sign = hash_hmac('sha256', $cka_cid, $task_secret);

// Node.js
const sign = crypto.createHmac('sha256', taskSecret).update(ckaCid).digest('hex');

# Python
import hmac, hashlib
sign = hmac.new(task_secret.encode(), cka_cid.encode(), hashlib.sha256).hexdigest()

3) Optionales Analytics-Pixel

Platziere das auf deiner Konversionsseite für dein eigenes Analytics. Es schreibt niemals gut — das Postback oben ist das Einzige, das gutschreibt.

<img src="https://fastcoins.click/task-pixel.php?cid={CLICK_ID}" width="1" height="1" alt="">

Empfehlungen für eine zuverlässige, sichere und umsatzstarke Integration.

⚡ Leistung

• Cache API-Antworten mindestens 60 Sekunden pro Nutzer. Rufe die API nicht bei jedem Seitenaufruf auf — Werbungen ändern sich höchstens alle paar Minuten.
• Übergib die echte Nutzer-IP. Nutze standardmäßig REMOTE_ADDR — es ist der einzige Wert, den der Besucher nicht fälschen kann. Lies nur dann stattdessen einen Proxy-Header (z. B. CF-Connecting-IP), wenn dein eigener Server hinter einem Reverse-Proxy sitzt, den du kontrollierst und dem du vertraust; niemals ein clientseitiger Header wie X-Forwarded-For. Falsche IPs verschlechtern die Targeting-Qualität.
• Setze ein 10-Sekunden-Timeout für deine cURL-Aufrufe, um langsame Seitenladezeiten zu vermeiden, falls unsere API vorübergehend langsam ist.

🔒 Sicherheit

• Gebe deinen Secret Key niemals preis — nicht in clientseitigem Code und nicht in öffentlichen Repositories. Er wird ausschließlich serverseitig zur Signaturprüfung verwendet.
• Prüfe transId immer gegen deine Datenbank, bevor du gutschreibst — das verhindert doppelte Belohnungen durch versehentlich erneut gesendete Postbacks.
• Validiere die Quell-IP, bevor du ein Postback verarbeitest. Akzeptiere Anfragen nur von 62.171.140.250 oder 2a02:c207:2329:8601::1.
• Verwende HTTPS für deinen Postback-Endpoint. HTTP-Endpoints können blockiert werden.
• Sende genau einen eindeutigen sub_id pro echtem Nutzer. Hänge keine numerischen Suffixe an eine Basis-ID an (123-1/123-2, ABC_1/ABC_2, order.1/order.2) — jedes Trennzeichen (- _ .) wird als Betrug erkannt und ohne Gutschrift abgelehnt. Siehe die Regel oben.

💰 Umsatz

• Boostete Werbungen (boosted_campaign: true) zahlen mehr — hebe sie in deiner Oberfläche hervor, um die Klickraten zu steigern.
• Längere Werbungen (60 s) zahlen deutlich mehr als kurze (2 s). Priorisiere sie, wenn die Nutzeraktivierung hoch ist.
• Balanciere deinen Nutzeranteil — eine höhere Auszahlung zieht mehr aktive Nutzer an; eine niedrigere erhöht deine eigene Marge.
• Auszahlungen sind vom 1. bis 3. jedes Monats möglich — trag es in deinen Kalender ein.

🐛 Fehlerbehebung

• Nutze die Schaltfläche Test Postback im Tab „Domains“, um zu prüfen, ob dein Endpoint exakt ok mit HTTP 200 zurückgibt.
• Sieh im Tab Postback Logs nach, um vollständige HTTP-Antworten jedes Postback-Versuchs zu sehen — dort stehen Statuscodes und Serverantworten.
• Fehlgeschlagene Postbacks können einzeln oder in Sammelaktion erneut gesendet werden — keine Daten gehen je dauerhaft verloren.
• Wenn die Signatur immer fehlschlägt: Prüfe bei signature_sha256, dass secret_key als HMAC-Schlüssel übergeben wird (nicht an die Nachricht angehängt) und dass du subId + transId + reward ohne Trennzeichen hashst; beim veralteten signature, prüfe, dass du subId + transId + reward + secret ohne Trennzeichen aneinanderreihst. Stelle in beiden Fällen sicher, dass reward exakt der Zeichenkette aus dem GET-Parameter entspricht (nicht gerundet).
• Wenn du signature_sha256_precise prüfst: gehasht wird über reward_precise, nicht über reward — die beiden Felder mit der falschen Signatur zu vermischen ist hier der häufigste Fehler.