FastCoins API de Publisher
Documentação

O FastCoins é uma rede de publishers PTC (Paid-To-Click). Incorpore nossos anúncios no seu site, seus usuários ganham recompensas em tokens por visualizá-los e você recebe uma parcela da receita automaticamente.

Crie uma conta de publisher, verifique que o domínio é seu e receba suas credenciais de API assim que ele for revisado.

• 1
  Crie uma conta de publisher em FastCoins.com/publisher_dashboard. Você vai precisar de um nome de site e uma URL.
• 2
  Adicione um domínio na aba Domains. Cada domínio tem a própria API Key, Secret Key, Bearer Token, configuração de token e URL de postback.
• 3
  Defina sua URL de postback — o endpoint no seu servidor que recebe as notificações de recompensa (veja a seção de Postback abaixo).
• 4
  Gere um Bearer Token na aba Domains. É necessário para autenticar as chamadas à API PTC.
• 5
  Envie um postback de teste na aba Domains para verificar que seu endpoint responde corretamente antes de entrar em produção.

Uma notificação de servidor para servidor enviada ao seu site quando um usuário termina de visualizar um anúncio, para que você possa creditar recompensas automaticamente sem código no lado do cliente.

🔐 Requisitos de segurança

• IP do servidor autorizados: 62.171.140.250, 2a02:c207:2329:8601::1 — verifique isso apenas contra $_SERVER['REMOTE_ADDR']. É uma chamada direta de servidor para servidor, não uma requisição de navegador, então não há proxy/CDN nosso no meio; um header como X-Forwarded-For é fornecido pelo cliente e trivial de falsificar, então não confie nele para essa verificação.
• userIp é obrigatório, não é apenas informativo — rejeite o callback se estiver ausente ou não for um IP válido. Sempre resolvemos e enviamos o IP real do usuário que concluiu o anúncio (via Cloudflare no nosso lado) justamente para que você possa confiar nele na detecção de fraude, limites por IP e checagens de usuários duplicados — um endpoint que o ignora perde totalmente esse sinal.
• Resposta HTTP obrigatória: exatamente ok — em minúsculas, sem espaços, sem HTML, HTTP 200
• Algoritmo de assinatura (recomendado): signature_sha256 = HMAC-SHA256(subId + transId + reward, secret_key) — secret_key é a chave do HMAC, não é concatenada na mensagem. userIp não faz parte dela.
• Algoritmo de assinatura (antigo, ainda enviado em todo callback): signature = MD5(subId + transId + reward + secret_key) — valores concatenados sem separadores. Mantido funcionando indefinidamente para integrações criadas antes de signature_sha256 existir; nada a mudar se você já valida essa.
• Precisa de mais de 8 decimais? Todo callback também traz reward_precise (10 decimais) com o seu próprio signature_sha256_precise = HMAC-SHA256(subId + transId + reward_precise, secret_key) — totalmente opcional e aditivo, calculado da mesma forma, só que sobre a string de maior precisão. reward/signature_sha256/signature continuam sendo enviados exatamente como antes, quer você use isso ou não.
• Prevenção de duplicados: verifique sempre transId no seu banco de dados antes de creditar

📋 Parâmetros do postback (GET)

Sua URL de postback recebe estes parâmetros via HTTP GET.

🧮 Exemplo: construção e verificação de uma URL assinada

Um exemplo completo resolvido para você conferir o seu próprio cálculo de assinatura contra o nosso antes de entrar em produção. A chave secreta usada é inventada, apenas para ilustração.

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

📐 Opcional: precisão de 10 decimais (reward_precise)

Mesma chave secreta, mesmo callback — apenas uma recompensa com mais precisão decimal do que os 8 decimais de reward conseguem guardar. Totalmente aditivo: ignore se 8 decimais já atendem o seu caso.

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

💻 Implementação em PHP — postback.php

Salve isto no seu servidor, defina sua Secret Key da aba Domains e cole a URL completa no campo Postback URL do seu domínio.

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

🕓 Validação antiga — 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.

🔀 Fluxo do callback

• 1
  Callback recebido
• 2
  Confira REMOTE_ADDR contra a whitelist de IPs
• 3
  Leia os parâmetros, incluindo userIp
• 4
  Valide userIp — rejeite se estiver ausente ou não for um IP válido
• 5
  Valide os demais parâmetros obrigatórios
• 6
  Verifique a assinatura
• 7
  Confira status — aplique como chargeback se for 2
• 8
  Se test=1, retorne ok sem creditar nada
• 9
  Confira transId no seu banco de dados para evitar créditos duplicados
• 10
  Credite ou reverta a recompensa, e armazene userIp junto com a conversão
• 11
  Retorne ok

Respostas possíveis:

• ok — callback processado (ou validado como callback de teste)
• ERROR: Invalid source IP
• ERROR: Invalid user IP
• ERROR: Missing parameters
• ERROR: Signature mismatch

Consulte os anúncios PTC disponíveis via API REST e renderize-os com a sua própria interface. Não é preciso incorporar nenhum widget.

🌐 Endpoint

🔑 Autenticação — Bearer Token

💻 Exemplo em 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.';
}

📦 Formato da resposta

Respostas bem-sucedidas retornam HTTP 200 com esta estrutura JSON:

⚠️ Códigos de erro

Respostas de erro compartilham a mesma estrutura JSON com um campo de status diferente de 200.

O fluxo completo, da chamada de API ao crédito da recompensa no seu site.

📡 Fluxo de API + Postback

🧩 Widget incorporado (alternativa)

Se preferir não usar a API, incorpore o widget como um iframe — ele cuida de tudo automaticamente, com estilos isolados do resto da sua página.

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

Crie uma tarefa (ex.: "cadastre-se no meu site"), financie N conclusões e confirme cada uma com um postback assinado de servidor para servidor. O usuário é creditado automaticamente no momento em que seu postback chega — sem aprovação manual, sem retenção da plataforma.

📡 Como funciona

1) A URL do postback

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

• cka_cid — o click id que anexamos à sua URL de destino quando o usuário começou (your-url?cka_cid=…). Devolva-o sem alterações.
• sign — hash_hmac('sha256', $cka_cid, $task_secret) (hex em minúsculas). O segredo de cada tarefa é exibido em Create Task → My Tasks.

2) Assinatura

// 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) Pixel de analytics opcional

Coloque isto na sua página de conversão para o seu próprio analytics. Ele nunca credita — o postback acima é a única coisa que credita.

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

Recomendações para uma integração confiável, segura e de alta receita.

⚡ Desempenho

• Coloque as respostas da API em cache por pelo menos 60 segundos por usuário. Não chame a API a cada carregamento de página — os anúncios mudam no máximo a cada poucos minutos.
• Passe o IP real do usuário. Use REMOTE_ADDR por padrão — é o único valor que o visitante não consegue falsificar. Leia um header de proxy no lugar (ex.: CF-Connecting-IP) apenas se o seu próprio servidor estiver atrás de um reverse proxy que você controla e confia; nunca um header fornecido pelo cliente como X-Forwarded-For. IPs incorretos reduzem a qualidade da segmentação de anúncios.
• Defina um timeout de 10 segundos nas suas chamadas cURL para evitar carregamentos lentos de página se a nossa API estiver temporariamente lenta.

🔒 Segurança

• Nunca exponha sua Secret Key em código do lado do cliente nem em repositórios públicos. Ela é usada apenas no servidor para validação de assinaturas.
• Sempre confira transId no seu banco de dados antes de creditar — isso evita recompensas duplicadas por reenvios acidentais de postback.
• Valide o IP de origem antes de processar qualquer postback. Aceite requisições apenas de 62.171.140.250 ou 2a02:c207:2329:8601::1.
• Use HTTPS no seu endpoint de postback. Endpoints HTTP podem ser bloqueados.
• Envie um único sub_id por usuário real. Não acrescente sufixos numéricos a um id base (123-1/123-2, ABC_1/ABC_2, order.1/order.2) — qualquer separador (- _ .) é detectado como fraude e rejeitado sem creditar recompensa. Veja a regra acima.

💰 Receita

• Anúncios impulsionados (boosted_campaign: true) pagam mais — destaque-os na sua interface para aumentar as taxas de clique.
• Anúncios mais longos (60s) pagam significativamente mais que os curtos (2s). Priorize-os quando o engajamento dos usuários estiver alto.
• Equilibre a parcela do usuário — um pagamento maior atrai mais usuários ativos; um pagamento menor aumenta a sua própria margem.
• Os saques estão abertos do dia 1 ao 3 de cada mês — marque no seu calendário.

🐛 Depuração

• Use o botão Test Postback na aba Domains para verificar que seu endpoint retorna exatamente ok com HTTP 200.
• Confira a aba Postback Logs para ver as respostas HTTP completas de cada tentativa de postback — ela mostra códigos de status e respostas do servidor.
• Postbacks que falharam podem ser reenviados individualmente ou em lote na aba de logs. Nenhum dado é perdido permanentemente.
• Se a assinatura sempre falha: para signature_sha256, verifique que secret_key é passada como a chave do HMAC (não concatenada na mensagem) e que você faz o hash de subId + transId + reward sem separadores; para o signature antigo, verifique que você concatena subId + transId + reward + secret sem separadores. De qualquer forma, garanta que reward corresponde à string exata do parâmetro GET (sem arredondar).
• Se você valida signature_sha256_precise: o hash é feito sobre reward_precise, não sobre reward — misturar os dois campos com a assinatura errada é o erro mais comum aqui.