FastCoins पब्लिशर API
दस्तावेज़ीकरण

FastCoins एक PTC (Paid-To-Click) पब्लिशर नेटवर्क है। हमारे विज्ञापन अपनी साइट पर लगाएँ, आपके उपयोगकर्ता उन्हें देखने पर टोकन इनाम कमाते हैं, और आपको राजस्व का हिस्सा स्वतः मिलता है।

पब्लिशर अकाउंट बनाएँ, सत्यापित करें कि डोमेन आपका है, और समीक्षा के बाद अपने API क्रेडेंशियल प्राप्त करें।

• 1
  FastCoins.com/publisher_dashboard पर पब्लिशर अकाउंट बनाएँ। आपको साइट का नाम और URL चाहिए होगा।
• 2
  Domains टैब में डोमेन जोड़ें। हर डोमेन की अपनी API Key, Secret Key, Bearer Token, टोकन कॉन्फ़िगरेशन और postback URL होती है।
• 3
  अपना postback URL सेट करें — आपके सर्वर पर वह endpoint जो इनाम की सूचनाएँ प्राप्त करता है (नीचे Postback सेक्शन देखें)।
• 4
  Domains टैब से Bearer Token जनरेट करें। PTC API कॉल की प्रमाणीकरण के लिए ज़रूरी है।
• 5
  लाइव जाने से पहले यह जाँचने के लिए कि आपका endpoint सही जवाब देता है, Domains टैब से टेस्ट postback भेजें।

जब कोई उपयोगकर्ता विज्ञापन देखना पूरा करता है तो आपकी वेबसाइट को भेजी जाने वाली सर्वर-टू-सर्वर सूचना, ताकि आप बिना किसी क्लाइंट-साइड कोड के इनाम स्वतः क्रेडिट कर सकें।

🔐 सुरक्षा आवश्यकताएँ

• अधिकृत सर्वर IP: 62.171.140.250, 2a02:c207:2329:8601::1 — इसे केवल $_SERVER['REMOTE_ADDR'] से मिलाएँ। यह सीधा सर्वर-टू-सर्वर कॉल है, ब्राउज़र रिक्वेस्ट नहीं, हमारा कोई प्रॉक्सी/CDN बीच में नहीं होता; X-Forwarded-For जैसा हेडर क्लाइंट द्वारा भेजा जाता है और उसे बनाना आसान है, इसलिए इस जाँच के लिए उस पर भरोसा न करें।
• userIp अनिवार्य है, केवल जानकारी के लिए नहीं — यदि वह गायब है या मान्य IP नहीं है तो callback अस्वीकार कर दें। हम हमेशा विज्ञापन पूरा करने वाले दर्शक का असली IP रिज़ॉल्व करके भेजते हैं (हमारी ओर से Cloudflare के ज़रिए) — ठीक इसीलिए, ताकि आप फ़्रॉड डिटेक्शन, IP-आधारित लिमिट और डुप्लिकेट-यूज़र जाँचों के लिए उस पर भरोसा कर सकें — जो endpoint उसे नज़रअंदाज़ करता है वह यह सिग्नल पूरी तरह खो देता है।
• आवश्यक HTTP रिस्पॉन्स: बिल्कुल ok — लोअरकेस, बिना स्पेस, बिना HTML, HTTP 200
• सिग्नेचर एल्गोरिद्म (अनुशंसित): signature_sha256 = HMAC-SHA256(subId + transId + reward, secret_key) — secret_key HMAC की कुंजी है, मैसेज में जोड़ी नहीं जाती। userIp इसका हिस्सा नहीं है।
• सिग्नेचर एल्गोरिद्म (पुराना, हर callback में अब भी भेजा जाता है): signature = MD5(subId + transId + reward + secret_key) — मान बिना विभाजक के जोड़े जाते हैं। signature_sha256 आने से पहले बनी इंटीग्रेशन के लिए यह अनिश्चितकाल तक चालू रखा गया है; अगर आप पहले से यही वेरिफ़ाई करते हैं तो कुछ बदलने की ज़रूरत नहीं।
• 8 दशमलव से ज़्यादा चाहिए? हर callback में reward_precise (10 दशमलव) भी होता है, अपने signature_sha256_precise के साथ = HMAC-SHA256(subId + transId + reward_precise, secret_key) — पूरी तरह वैकल्पिक और अतिरिक्त, उसी तरह गणना, बस ज़्यादा सटीक स्ट्रिंग पर। reward/signature_sha256/signature आपके उपयोग से निरपेक्ष, पहले की तरह ही भेजे जाते रहते हैं।
• डुप्लिकेट रोकथाम: क्रेडिट करने से पहले हमेशा अपनी DB में transId जाँचें

📋 Postback पैरामीटर (GET)

आपका postback URL ये पैरामीटर HTTP GET से प्राप्त करता है।

🧮 उदाहरण: साइन किया हुआ URL बनाना और सत्यापित करना

पूरा हल किया हुआ उदाहरण, ताकि लाइव जाने से पहले आप अपनी सिग्नेचर गणना को हमारे साथ मिलाकर जाँच सकें। यहाँ इस्तेमाल हुआ सीक्रेट की काल्पनिक है, केवल उदाहरण के लिए।

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

📐 वैकल्पिक: 10-दशमलव सटीकता (reward_precise)

वही सीक्रेट, वही callback — बस reward के 8 दशमलवों से ज़्यादा सटीक इनाम। पूरी तरह अतिरिक्त: अगर 8 दशमलव आपके काम के लिए काफ़ी हैं तो इसे छोड़ दें।

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 कार्यान्वयन — postback.php

इसे अपने सर्वर पर सेव करें, Domains टैब से अपनी Secret Key सेट करें, फिर पूरा URL अपने डोमेन के Postback URL फ़ील्ड में पेस्ट करें।

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

🕓 पुराना सत्यापन — 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 फ़्लो

• 1
  Callback प्राप्त हुआ
• 2
  REMOTE_ADDR को IP व्हाइटलिस्ट से मिलाएँ
• 3
  पैरामीटर पढ़ें, userIp सहित
• 4
  userIp सत्यापित करें — गायब हो या मान्य IP न हो तो अस्वीकार करें
• 5
  बाकी आवश्यक पैरामीटर सत्यापित करें
• 6
  सिग्नेचर वेरिफ़ाई करें
• 7
  status जाँचें — 2 होने पर चार्जबैक के रूप में लागू करें
• 8
  यदि test=1 है तो कुछ क्रेडिट किए बिना ok लौटाएँ
• 9
  डुप्लिकेट क्रेडिट रोकने के लिए transId को अपनी DB से मिलाएँ
• 10
  इनाम क्रेडिट या रिवर्स करें और कन्वर्ज़न के साथ userIp सेव करें
• 11
  ok लौटाएँ

संभावित रिस्पॉन्स:

• ok — callback संसाधित (या टेस्ट callback के रूप में मान्य)
• ERROR: Invalid source IP
• ERROR: Invalid user IP
• ERROR: Missing parameters
• ERROR: Signature mismatch

उपलब्ध PTC विज्ञापनों को REST API से क्वेरी करें और अपने स्वयं के यूज़र इंटरफ़ेस से रेंडर करें। किसी विजेट को एम्बेड करने की ज़रूरत नहीं।

🌐 Endpoint

🔑 प्रमाणीकरण — Bearer Token

💻 PHP उदाहरण

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

📦 रिस्पॉन्स फ़ॉर्मैट

सफल रिस्पॉन्स इस JSON संरचना के साथ HTTP 200 लौटाते हैं:

⚠️ एरर कोड

एरर रिस्पॉन्स वही JSON संरचना साझा करते हैं, बस status फ़ील्ड 200 के अलावा होता है।

API कॉल से लेकर आपकी साइट पर इनाम क्रेडिट होने तक का पूरा फ़्लो।

📡 API + Postback फ़्लो

🧩 विजेट एम्बेड (विकल्प)

अगर आप API का उपयोग नहीं करना चाहते तो विजेट को iframe के रूप में एम्बेड करें — यह सब कुछ स्वतः संभाल लेता है, और इसकी स्टाइल आपके पेज के बाकी हिस्सों से अलग-थलग रहती है।

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

एक टास्क बनाएँ (जैसे "मेरी साइट पर रजिस्टर करें"), N पूर्णताओं के लिए फंड डालें, और हर एक की पुष्टि साइन किए हुए सर्वर-टू-सर्वर postback से करें। आपका postback आते ही उपयोगकर्ता को स्वतः क्रेडिट मिल जाता है — कोई मैन्युअल मंज़ूरी नहीं, कोई प्लेटफ़ॉर्म रोक नहीं।

📡 यह कैसे काम करता है

1) Postback URL

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

• cka_cid — वह click id जो हमने उपयोगकर्ता के शुरू करते समय आपकी डेस्टिनेशन URL में जोड़ा था (your-url?cka_cid=…)। इसे बिना बदले वापस भेजें।
• sign — hash_hmac('sha256', $cka_cid, $task_secret) (लोअरकेस हेक्स)। हर टास्क का सीक्रेट Create Task → My Tasks में दिखता है।

2) सिग्नेचर

// 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) वैकल्पिक एनालिटिक्स पिक्सेल

अपने खुद के एनालिटिक्स के लिए इसे अपने कन्वर्ज़न पेज पर लगाएँ। यह कभी क्रेडिट नहीं करता — क्रेडिट करने वाली एकमात्र चीज़ ऊपर वाला postback है।

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

एक विश्वसनीय, सुरक्षित और अधिक आय देने वाले इंटीग्रेशन के लिए सुझाव।

⚡ परफ़ॉर्मेंस

• API रिस्पॉन्स को प्रति उपयोगकर्ता कम से कम 60 सेकंड कैश करें। हर पेज लोड पर API कॉल न करें — विज्ञापन अधिकतम कुछ मिनट में एक बार बदलते हैं।
• उपयोगकर्ता का असली IP भेजें। डिफ़ॉल्ट रूप से REMOTE_ADDR उपयोग करें — यही एकमात्र मान है जिसे विज़िटर बना नहीं सकता। प्रॉक्सी हेडर (जैसे CF-Connecting-IP) तभी पढ़ें जब आपका सर्वर खुद उस रिवर्स प्रॉक्सी के पीछे हो जिसे आप नियंत्रित करते और भरोसा करते हैं; क्लाइंट-सप्लाइड हेडर जैसे X-Forwarded-For कभी नहीं। ग़लत IP विज्ञापन टारगेटिंग की गुणवत्ता घटाते हैं।
• अगर हमारी API कभी धीमी हो जाए तो धीमे पेज लोड रोकने के लिए अपने cURL कॉल पर 10 सेकंड का टाइमआउट सेट करें।

🔒 सुरक्षा

• अपनी Secret Key क्लाइंट-साइड कोड या सार्वजनिक रिपॉज़िटरी में कभी उजागर न करें। वह केवल सर्वर-साइड पर सिग्नेचर सत्यापन के लिए उपयोग होती है।
• क्रेडिट करने से पहले अपनी डेटाबेस से हमेशा transId जाँचें — इससे गलती से दोबारा भेजे गए postback से होने वाले डुप्लिकेट इनाम रुक जाते हैं।
• कोई भी postback संसाधित करने से पहले सोर्स IP सत्यापित करें। रिक्वेस्ट केवल इनसे स्वीकार करें: 62.171.140.250 या 2a02:c207:2329:8601::1.
• अपने postback endpoint के लिए HTTPS उपयोग करें। HTTP endpoint ब्लॉक हो सकते हैं।
• हर असली उपयोगकर्ता के लिए एक ही अद्वितीय sub_id भेजें। किसी बेस id पर संख्यात्मक सफ़िक्स न जोड़ें (123-1/123-2, ABC_1/ABC_2, order.1/order.2) — कोई भी सेपरेटर (- _ .) फ़्रॉड माना जाता है और बिना इनाम अस्वीकार हो जाता है। ऊपर दिया नियम देखें।

💰 राजस्व

• बूस्टेड विज्ञापन (boosted_campaign: true) ज़्यादा देते हैं — क्लिक दर बढ़ाने के लिए अपने यूज़र इंटरफ़ेस में इन्हें हाइलाइट करें।
• लंबे विज्ञापन (60 सेकंड) छोटे विज्ञापनों (2 सेकंड) से काफ़ी ज़्यादा देते हैं। जब उपयोगकर्ता जुड़ाव अधिक हो तो इन्हें प्राथमिकता दें।
• उपयोगकर्ता हिस्सा संतुलित रखें — ज़्यादा भुगतान ज़्यादा सक्रिय उपयोगकर्ता खींचता है; कम भुगतान आपका अपना मार्जिन बढ़ाता है।
• निकासी हर महीने की 1 से 3 तारीख़ तक खुली रहती है — अपने कैलेंडर में नोट करें।

🐛 डिबगिंग

• यह जाँचने के लिए कि आपका endpoint HTTP 200 के साथ बिल्कुल ok लौटाता है, Domains टैब के Test Postback बटन का उपयोग करें।
• हर postback कोशिश के पूरे HTTP रिस्पॉन्स के लिए Postback Logs टैब देखें — उसमें स्टेटस कोड और सर्वर के जवाब दिखते हैं।
• फ़ेल हुए postback Logs टैब से एक-एक करके या बैच में दोबारा भेजे जा सकते हैं। कोई डेटा कभी स्थायी रूप से नहीं खोता।
• अगर सिग्नेचर हमेशा फ़ेल हो: signature_sha256 के लिए जाँचें कि secret_key HMAC कुंजी के रूप में दी गई है (मैसेज में नहीं जुड़ी) और आप subId + transId + reward को बिना विभाजक हैश करते हैं; पुराने signature के लिए जाँचें कि आप subId + transId + reward + secret को बिना विभाजक जोड़ते हैं। दोनों ही स्थिति में सुनिश्चित करें कि reward GET पैरामीटर वाली सटीक स्ट्रिंग से मेल खाता है (बिना राउंडिंग)।
• यदि आप signature_sha256_precise वेरिफ़ाई कर रहे हैं: उसका हैश reward_precise पर होता है, reward पर नहीं — दोनों फ़ील्ड को ग़लत सिग्नेचर से मिलाना यहाँ की सबसे आम गलती है।