FastCoins Yayıncı API'si
Dokümantasyon

FastCoins, yayıncılara yönelik bir PTC (Paid-To-Click) ağıdır. Reklamlarımızı sitenize yerleştirin, kullanıcılarınız onları izlediği için token ödül kazansın, gelir payını ise otomatik olarak alın.

Bir yayıncı hesabı oluşturun, alan adının size ait olduğunu doğrulayın ve incelemesi tamamlanınca API kimlik bilgilerinizi alın.

• 1
  Bir yayıncı hesabı oluşturun — FastCoins.com/publisher_dashboard adresinden. Bir site adı ve URL gereklidir.
• 2
  Domains sekmesinden bir alan adı ekleyin. Her alan adının kendi API Key'i, Secret Key'i, Bearer Token'ı, token yapılandırması ve postback URL'si vardır.
• 3
  Postback URL'nizi ayarlayın — sunucunuzda ödül bildirimlerini alan endpoint (aşağıdaki Postback bölümüne bakın).
• 4
  PTC API çağrılarının kimliğini doğrulamak için Domains sekmesinden bir Bearer Token oluşturun.
• 5
  Yayına girmeden önce endpoint'inizin doğru yanıt verdiğini doğrulamak için Domains sekmesinden bir test postback gönderin.

Bir kullanıcı reklam izlemeyi tamamladığında web sitenize gönderilen sunucudan sunucuya bildirim; böylece istemci tarafı kod olmadan ödülleri otomatik yansıtabilirsiniz.

🔐 Güvenlik Gereksinimleri

• Yetkili sunucu IP adresleri: 62.171.140.250, 2a02:c207:2329:8601::1 — bunu yalnızca $_SERVER['REMOTE_ADDR'] ile karşılaştırın. Bu doğrudan sunucudan sunucuya bir çağrıdır, tarayıcı isteği değildir; arada bizim proxy/CDN'imiz yoktur. X-Forwarded-For gibi bir başlık istemci tarafından gönderilir ve taklit edilmesi çok kolaydır, bu kontrol için ona güvenmeyin.
• userIp zorunludur, yalnızca bilgilendirme amaçlı değildir — eksikse veya geçerli bir IP değilse callback'i reddedin. Reklamı tamamlayan kullanıcının gerçek IP'sini (bizim tarafımızda Cloudflare üzerinden) her zaman çözümleyip gönderiyoruz; tam da bu yüzden dolandırıcılık tespiti, IP tabanlı limitler ve mükerrer kullanıcı kontrollerinde buna güvenebilirsiniz — onu yok sayan bir endpoint bu sinyali tamamen kaybeder.
• Zorunlu HTTP yanıtı: tam olarak ok — küçük harflerle, boşluksuz, HTML'siz, HTTP 200
• İmza algoritması (önerilen): signature_sha256 = HMAC-SHA256(subId + transId + reward, secret_key) — secret_key HMAC anahtarıdır, mesaja eklenmez. userIp bunun bir parçası değildir.
• İmza algoritması (eski, her callback'te hâlâ gönderilir): signature = MD5(subId + transId + reward + secret_key) — değerler ayırıcısız birleştirilir. signature_sha256 ortaya çıkmadan önce kurulmuş entegrasyonlar için süresiz çalışır durumda tutulur; zaten bunu doğruluyorsanız değiştirmeniz gereken bir şey yok.
• 8 ondalıktan fazlasına mı ihtiyacınız var? Her callback ayrıca kendi signature_sha256_precise değeriyle birlikte reward_precise (10 ondalık) taşır: HMAC-SHA256(subId + transId + reward_precise, secret_key) — tamamen isteğe bağlı ve eklentidir, aynı şekilde hesaplanır, sadece daha hassas metin üzerinden. reward/signature_sha256/signature kullanıp kullanmadığınızdan bağımsız olarak aynen eski gibi gönderilmeye devam eder.
• Mükerrer önleme: ödül yansıtmadan önce her zaman veritabanınızda transId değerini kontrol edin

📋 Postback Parametreleri (GET)

Postback URL'niz bu parametreleri HTTP GET ile alır.

🧮 Örnek: İmzalı Bir URL Oluşturma ve Doğrulama

Yayına girmeden önce kendi imza hesabınızı bizimkiyle karşılaştırabilmeniz için baştan sona işlenmiş bir örnek. Kullanılan gizli anahtar tamamen uydurmadır, yalnızca gösterim amaçlıdır.

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

📐 İsteğe bağlı: 10 Ondalık Hassasiyet (reward_precise)

Aynı gizli anahtar, aynı callback — sadece reward değerinin 8 ondalığının barındırabileceğinden daha fazla kesirli hassasiyete sahip bir ödül. Tamamen eklentidir: 8 ondalık senaryonuzu zaten karşılıyorsa bunu atlayın.

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 Uygulaması — postback.php

Bunu sunucunuza kaydedin, Domains sekmesinden Secret Key'inizi ayarlayın, sonra tam URL'yi alan adınızın Postback URL alanına yapıştırın.

// ── 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

🕓 Eski Doğrulama — 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 Akışı

• 1
  Callback alındı
• 2
  REMOTE_ADDR değerini IP beyaz listesiyle karşılaştırın
• 3
  userIp dahil parametreleri okuyun
• 4
  userIp değerini doğrulayın — eksikse veya geçerli bir IP değilse reddedin
• 5
  Diğer zorunlu parametreleri doğrulayın
• 6
  İmzayı doğrulayın
• 7
  status değerini kontrol edin — 2 ise chargeback olarak uygulayın
• 8
  test=1 ise hiçbir şey yansıtmadan ok döndürün
• 9
  Mükerrer yansıtmaları önlemek için transId değerini veritabanınızla karşılaştırın
• 10
  Ödülü yansıtın ya da geri alın ve dönüşümle birlikte userIp değerini saklayın
• 11
  ok döndürün

Olası yanıtlar:

• ok — callback işlendi (veya test callback'i olarak doğrulandı)
• ERROR: Invalid source IP
• ERROR: Invalid user IP
• ERROR: Missing parameters
• ERROR: Signature mismatch

Mevcut PTC reklamlarını bir REST API üzerinden sorgulayın ve kendi arayüzünüzle render edin. Widget yerleştirmek gerekmez.

🌐 Endpoint

🔑 Kimlik Doğrulama — Bearer Token

💻 PHP Örneği

// ── 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.';
}

📦 Yanıt Formatı

Başarılı yanıtlar şu JSON yapısıyla HTTP 200 döndürür:

⚠️ Hata Kodları

Hata yanıtları, 200 olmayan bir status alanıyla aynı JSON yapısını paylaşır.

API çağrısından sitenizde ödül yansıtmasına kadar baştan sona akış.

📡 API + Postback Akışı

🧩 Widget Yerleştirme (alternatif)

API'yi kullanmak istemiyorsanız widget'ı iframe olarak yerleştirin — her şeyi otomatik halleder, stilleri sayfanın geri kalanından izole tutulur.

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

Bir görev oluşturun (ör. "siteme kaydol"), N tamamlanma için bakiye yükleyin ve her birini imzalı bir sunucudan sunucuya postback ile onaylayın. Kullanıcı, postback'iniz geldiği anda otomatik olarak ödüllendirilir — manuel onay yok, platform bekletmesi yok.

📡 Nasıl çalışır

1) Postback URL'si

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

• cka_cid — kullanıcı başladığında hedef URL'nize eklediğimiz click id (your-url?cka_cid=…). Değiştirmeden geri gönderin.
• sign — hash_hmac('sha256', $cka_cid, $task_secret) (küçük harf hex). Göreve özel secret, Create Task → My Tasks bölümünde gösterilir.

2) İmza

// 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) İsteğe bağlı analitik pikseli

Kendi analitiğiniz için bunu dönüşüm sayfanıza yerleştirin. Asla ödül yansıtmaz — ödülü yansıtan tek şey yukarıdaki postback'tir.

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

Güvenilir, güvenli ve yüksek gelirli bir entegrasyon için öneriler.

⚡ Performans

• API yanıtlarını kullanıcı başına en az 60 saniye önbelleğe alın. Her sayfa yüklemesinde API'yi çağırmayın — reklamlar en hızlı birkaç dakikada bir değişir.
• Kullanıcının gerçek IP'sini iletin. Varsayılan olarak REMOTE_ADDR kullanın — ziyaretçinin taklit edemeyeceği tek değer budur. Yalnızca kendi sunucunuz kontrol ettiğiniz ve güvendiğiniz bir reverse proxy arkasındaysa bunun yerine bir proxy başlığı okuyun (ör. CF-Connecting-IP); X-Forwarded-For gibi istemci kaynaklı bir başlığa asla güvenmeyin. Yanlış IP'ler reklam hedefleme kalitesini düşürür.
• API'miz geçici olarak yavaşsa sayfa yüklemelerinin yavaşlamasını önlemek için cURL çağrılarınızda 10 saniyelik bir timeout ayarlayın.

🔒 Güvenlik

• Secret Key'inizi istemci tarafı kodda veya herkese açık depolarda asla ifşa etmeyin. Yalnızca sunucu tarafında imza doğrulaması için kullanılır.
• Ödül yansıtmadan önce veritabanınızla her zaman transId kontrolü yapın — bu, yanlışlıkla tekrar gönderilen postback'lerden kaynaklanan mükerrer ödülleri önler.
• Herhangi bir postback'i işlemeden önce kaynak IP'yi doğrulayın. İstekleri yalnızca şunlardan kabul edin: 62.171.140.250 veya 2a02:c207:2329:8601::1.
• Postback endpoint'iniz için HTTPS kullanın. HTTP endpoint'ler engellenebilir.
• Her gerçek kullanıcı için tek bir benzersiz sub_id gönderin. Bir temel id'ye sayısal ekler yapmayın (123-1/123-2, ABC_1/ABC_2, order.1/order.2) — herhangi bir ayırıcı (- _ .) dolandırıcılık olarak tespit edilir ve ödül yansıtılmadan reddedilir. Yukarıdaki kurala bakın.

💰 Gelir

• Güçlendirilmiş reklamlar (boosted_campaign: true) daha fazla öder — tıklama oranlarını artırmak için arayüzünüzde öne çıkarın.
• Uzun reklamlar (60 sn), kısa reklamlardan (2 sn) önemli ölçüde fazla öder. Kullanıcı etkileşimi yüksekken bunlara öncelik verin.
• Kullanıcı payınızı dengeleyin — yüksek ödeme daha fazla aktif kullanıcı çeker; düşük ödeme kendi marjınızı artırır.
• Çekimler her ayın 1'inden 3'üne kadar açıktır — takviminize işaretleyin.

🐛 Hata Ayıklama

• Endpoint'inizin HTTP 200 ile tam olarak ok döndürdüğünü doğrulamak için Domains sekmesindeki Test Postback düğmesini kullanın.
• Her postback denemesinin tam HTTP yanıtları için Postback Logs sekmesine bakın — durum kodlarını ve sunucu yanıtlarını gösterir.
• Başarısız postback'ler Logs sekmesinden tek tek veya toplu olarak yeniden gönderilebilir. Hiçbir veri kalıcı olarak kaybolmaz.
• İmza her seferinde başarısız oluyorsa: signature_sha256 için secret_key değerinin HMAC anahtarı olarak verildiğini (mesaja eklenmediğini) ve subId + transId + reward değerini ayırıcısız hash'lediğinizi doğrulayın; eski signature için subId + transId + reward + secret değerlerini ayırıcısız birleştirdiğinizi doğrulayın. Her iki durumda da reward değerinin GET parametresindeki metinle tam olarak eşleştiğinden (yuvarlanmamış) emin olun.
• signature_sha256_precise doğruluyorsanız: hash reward_precise üzerinden hesaplanır, reward üzerinden değil — alanları yanlış imzayla karıştırmak burada en sık yapılan hatadır.