CashoutGuard: fraud prevention for rewards, GPT, faucet, PTC and offerwall sites.

Documentation

One script in the browser, one API call from your server. Everything you need to go live, on one page.

Quick start

You need your public key (pk_...) for the browser and your secret key (sk_...) for your server. Both are in the dashboard under Sites and keys.

1. Add the script

Put this tag on the pages where users sign up, log in, click offers or request a cashout. It initialises itself from data-key

<script src="https://cashoutguard.com/v1/agent.js" data-key="pk_live_YOUR_PUBLIC_KEY" async></script>

2. Collect and send request_id to your server

Call collect() at the moment that matters, with the event name. It resolves to { request_id, visitor_id }

const { request_id } = await CashoutGuard.collect({ event: 'cashout' });

collect() never rejects. On failure (blocked, offline, timeout) it resolves with request_id: null and an error string. Send the form anyway and let your server decide.

3. Ask for a decision from your server

POST the event to /v1/evaluate with your secret key in the header Authorization: Bearer sk_live_...

Never put the secret key in browser code or a mobile app. Only your server should call /v1/evaluate.

Evaluate request

POST https://cashoutguard.com/v1/evaluate scores one event for one account, links it to its device, network and payout address, and returns a decision. Send JSON.

FieldTypeRequiredDescription
eventstringRequiredsignup, login, offer_click, conversion, cashout or custom.
account_idstringRequiredYour user ID, max 191 characters. Use an opaque ID, not an email.
request_idstringOptionalFrom collect() in the browser. Valid for 1 hour. Without it we only have network data.
ipstringOptionalThe user's IP. Only needed when you have no request_id, for example for postbacks.
emailstringOptionalStored as a hash. Detects disposable domains and emails shared between accounts.
payout_addressstringOptionalPayPal email, wallet or account the money goes to. Stored as a hash.
payout_methodstringOptionalFree text such as paypal, usdt or giftcard.
amountnumberOptionalCashout or conversion amount.
currencystringOptionalCurrency code, for example USD. Default USD for cashouts.
offer_idstringOptionalOffer ID, for offer_click and conversion. Used for offer speed.
offer_countrystringOptionalCountry the offer pays for (ISO code, e.g. US), on conversions. A user in another country is flagged.
geo_countrystringOptionalYour own geolocation of the user's IP (ISO code). When it disagrees with ours, the IP is likely a proxy exit.
transaction_idstringOptionalNetwork transaction ID of a conversion. Used to catch duplicates.
offer_namestringOptionalOffer title as your users see it. Shown everywhere in the dashboard instead of the raw id.
click_idstringOptionalYour click id. Send the same value on offer_click and on the conversion so they are linked.
sourcestringOptionalWhere the event came from, for example the offerwall or network name.
metaobjectOptionalUp to 20 extra string fields stored with the event (for example sub ids).

Response

The response always has the same shape. Fields that do not apply are null.

  • score is 0 to 100. Reasons are combined so several medium signals add up without passing 100.
  • reasons lists every signal that fired, strongest first, with its weight, details and a plain-English label you can show as it is.
  • device.confidence tells you how unique the device looks. Fingerprints can be spoofed, so we never claim certainty.
  • linked_accounts lists other accounts that share a device, payout address or email with this one.
  • cashout is only set for cashout events and tells you the status in your review queue.

Decisions and actions

Act on the action field, not on decision. The thresholds below are the defaults and can be changed per site in the dashboard.

DecisionScore (default)action in shadowaction in enforceWhat to do
allow0-49allowallowContinue as normal.
review50-79allowreviewHold the cashout or ask for extra verification. It appears in your review queue.
block80-100allowblockStop the action. Freeze the balance or refuse the signup.

In shadow mode action is always allow, so the same code is safe to ship before you enforce. When you switch to enforce, nothing in your code changes.

Event types

Send the events you have. Signup and cashout matter most; conversions power offer speed checks.

EventWhen to send itWhat it catches
signupAccount createdMulti-accounts, bots, VPN signups, disposable emails
loginSuccessful loginAccount sharing, country changes, new devices
offer_clickUser opens an offerStarts the clock for offer speed
conversionPostback from the offerwall or networkOffers completed too fast, duplicate transactions, conversion bursts
cashoutUser requests a withdrawalShared payout addresses, cashout velocity, new-account cashouts
customAnything else you want scoredDevice and network signals

Offerwalls and postbacks

Offerwall conversions arrive by postback, server to server, with no browser. CashoutGuard links each conversion to the click that started it, so the conversion is scored with the device and network of that click.

1. When the user opens an offer

Collect in the browser and send an offer_click with the offer and your click id.

2. When the postback arrives

Send a conversion from your postback handler with the same account_id and click_id. No request_id is needed. Pass the user IP if the offerwall gives it to you.

Conversions are checked for: completed too fast for that offer, conversion without a click, click and conversion from different countries, earnings far above the account's usual day and duplicate transaction ids.

Offerwall networks

If you run a network with many publishers, send account ids that include the publisher and turn on "Offerwall network mode" in Sites. Accounts are then only linked inside the same publisher, because one person using several of your publishers' sites is normal. Format: publisher_id:user_id

Offer catalog

POST /v1/offers sends your offer names (up to 1,000 per call). Past and future events then show the real offer name even when an event only carries the id.

Reason codes

These codes appear in reasons[].code. Show the text to your moderators; use the code in your logic.

CodeMeaningGroupWeight
ip_torTor exit nodeNetwork60
ip_vpnVPN connectionNetwork45
ip_datacenterDatacenter / hosting IPNetwork40
timezone_mismatchBrowser timezone does not match IP locationNetwork20
webrtc_ip_leakReal IP leaked in another countryNetwork30
ip_multi_timezoneSame IP used with many different timezones (proxy exit)Network50
proxy_farm_ipSeveral accounts on one IP, all with the same foreign clock (shared proxy)Network60
provider_rotationMany internet providers in a few days, with a foreign clock (rotating residential proxy)Network45
privacy_relayiCloud Private Relay (privacy feature)Network5
proxy_headersRequest came through a proxyNetwork20
geo_sources_disagreeGeolocation sources disagreeNetwork45
ip_shared_with_accountsSame IP used by other accounts todayNetwork25
country_changedCountry changedNetwork15
impossible_travelImpossible travel: IPs in two distant countries within hoursNetwork50
locale_country_mismatchBrowser language from another countryNetwork30
phone_country_mismatchPhone from another country than the IPNetwork20
ip_flagged_on_networkIP blocked on other websitesNetwork25
device_shared_with_accountsDevice shared with other accountsDevice55
automation_detectedBot or automation toolDevice70
auto_clickerAuto-clicker on the phoneDevice55
scripted_behaviorScripted page useDevice45
emulator_or_vmEmulator or virtual machineDevice45
browser_tamperingBrowser tampering / spoofingDevice35
device_rootedRooted phoneDevice25
incognitoPrivate browsingDevice10
device_spoofedFake phone modelDevice55
emulator_profileEmulator default profileDevice60
cloud_phoneCloud phoneDevice60
phone_farm_displayPhone farm displayDevice45
device_market_mismatchChina-only phone abroadDevice25
storage_cleared_reappearedCleared cookies and came backDevice15
no_device_dataNo device data sentDevice15
request_reusedDevice token reused by another accountDevice40
device_farm_proxyPhone farm on residential proxiesDevice85
device_clonesDevice clones: one phone resetting its identity to pose as many new accounts on one networkDevice55
payout_address_sharedPayout address used by other accountsAccount70
email_disposableDisposable emailAccount25
email_invalidEmail address that cannot receive mail (no such mail domain)Account35
email_sharedSame email as another accountAccount50
phone_sharedPhone number shared by other accountsAccount50
phone_voipVoIP or virtual phone numberAccount40
phone_invalidInvalid phone numberAccount30
many_devices_per_accountToo many devices on one accountAccount20
flagged_on_networkFlagged on other websites protected by CashoutGuardAccount45
face_same_personSame face as other accountsAccount0
offer_completed_too_fastOffer completed impossibly fastBehavior40
slow_after_clickConverted long after the clickBehavior0
conversion_velocityToo many conversions per hourBehavior30
conversion_without_clickConversion with no click from your wallBehavior35
click_conversion_country_mismatchClicked in one country, converted in anotherBehavior30
offer_country_mismatchOffer country differs from the user’sBehavior45
click_velocityToo many offer clicks in a few minutesBehavior35
earnings_spikeEarnings far above a normal userBehavior30
source_high_reversalsSource with many chargebacksBehavior45
offer_high_reversalsOffer with many chargebacksBehavior35
duplicate_transactionDuplicate transaction IDBehavior60
offer_repeated_other_publisherSame offer already done through another publisherBehavior85
offer_repeated_other_accountSame offer already done by another account on this deviceBehavior85
offer_farm_burstFarm wave: many new accounts with farm devices on this offer within hoursBehavior30
signup_burstSignup burst: several accounts signed up within seconds of each other from different IPsBehavior25
face_check_requiredFace check required, not done yetBehavior0
face_check_failedFace check failedBehavior0
publisher_farm_waveFarm wave of its publisher: most new accounts it sent to this offer came from cloud phones or emulatorsBehavior55
cashout_velocityToo many cashouts per dayBehavior30
new_account_cashoutCashout from a brand-new accountBehavior20
blocklistedOn your blocklistYour lists100

Weights are combined with a noisy-OR: score = 100 x (1 - product of (1 - weight/100)). Two signals of 40 give 64, not 80. A blocklist match always gives 100.

Webhooks

Set a webhook URL in the dashboard. We send a POST for every event scored block (event.blocked), when an account turns to block (account.blocked) and when your team decides a cashout (cashout.decided). Ignore types you do not use.

Each request is signed with your webhook secret. The hex HMAC-SHA256 of the raw body is in the header X-CashoutGuard-Signature

Reply with any 2xx status. Failed deliveries are retried up to 5 times: after 10 seconds, 1 minute, 5 minutes and 15 minutes.

Account status

GET /v1/accounts/{account_id} returns the current risk view of an account without creating an event.

POST /v1/accounts/{account_id}/status lets your own moderation tools change an account's status.

  • active: Normal scoring.
  • allowlisted: Scores are capped below the review threshold. For trusted users and staff.
  • blocked: Every event returns block with score 100.

Reversals & accuracy

POST /v1/outcomes reports what happened to conversions after we scored them: reversed by the offerwall or advertiser (chargeback) or confirmed valid. We match your ids to the conversions and measure the engine on your own traffic in the Accuracy page: how much reversed money we had flagged and which signals predict reversals.

No code needed: upload the monthly reversal export from your offerwalls (CSV or Excel) on the Accuracy page. We find the id column automatically.

PHP, Node.js, Python, Android

No SDK needed. A plain HTTP call with a short timeout is enough. Full cashout example:

Errors and limits

HTTPBodyMeaning
401missing_or_invalid_secret_keyMissing, wrong or revoked secret key. The response says why in "reason" (missing, public_key, unknown_secret, placeholder, malformed) and how to fix it in "hint".
404not_foundAccount not found (account endpoints).
422{ "message", "errors" }Invalid body. errors lists each field.
429Too Many RequestsRate limit reached. The server API allows 3,000 requests per minute per site.
401 · agent.jsunknown_public_keyThe data-key is not a public key of any site. Copy pk_live_... again from Install.
403 · agent.jsorigin_not_allowedThe page's domain is not in the site's allowed origins. Add it in Sites, or leave the list empty. localhost always works. agent.js also explains this in the browser console. App WebViews send the origin "null": add null to the list to accept them. The native Android SDK needs nothing.
403account_suspendedThe account is suspended, usually for an unpaid invoice. Check Billing.
503temporarily_unavailableShort outage on our side. Fail open and retry later.

Fail open: if the call times out or errors, allow the action and log it. Never let our outage stop your users.