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.
| Field | Type | Required | Description |
|---|---|---|---|
event | string | Required | signup, login, offer_click, conversion, cashout or custom. |
account_id | string | Required | Your user ID, max 191 characters. Use an opaque ID, not an email. |
request_id | string | Optional | From collect() in the browser. Valid for 1 hour. Without it we only have network data. |
ip | string | Optional | The user's IP. Only needed when you have no request_id, for example for postbacks. |
email | string | Optional | Stored as a hash. Detects disposable domains and emails shared between accounts. |
payout_address | string | Optional | PayPal email, wallet or account the money goes to. Stored as a hash. |
payout_method | string | Optional | Free text such as paypal, usdt or giftcard. |
amount | number | Optional | Cashout or conversion amount. |
currency | string | Optional | Currency code, for example USD. Default USD for cashouts. |
offer_id | string | Optional | Offer ID, for offer_click and conversion. Used for offer speed. |
offer_country | string | Optional | Country the offer pays for (ISO code, e.g. US), on conversions. A user in another country is flagged. |
geo_country | string | Optional | Your own geolocation of the user's IP (ISO code). When it disagrees with ours, the IP is likely a proxy exit. |
transaction_id | string | Optional | Network transaction ID of a conversion. Used to catch duplicates. |
offer_name | string | Optional | Offer title as your users see it. Shown everywhere in the dashboard instead of the raw id. |
click_id | string | Optional | Your click id. Send the same value on offer_click and on the conversion so they are linked. |
source | string | Optional | Where the event came from, for example the offerwall or network name. |
meta | object | Optional | Up 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.
scoreis 0 to 100. Reasons are combined so several medium signals add up without passing 100.reasonslists every signal that fired, strongest first, with its weight, details and a plain-English label you can show as it is.device.confidencetells you how unique the device looks. Fingerprints can be spoofed, so we never claim certainty.linked_accountslists other accounts that share a device, payout address or email with this one.cashoutis 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.
| Decision | Score (default) | action in shadow | action in enforce | What to do |
|---|---|---|---|---|
allow | 0-49 | allow | allow | Continue as normal. |
review | 50-79 | allow | review | Hold the cashout or ask for extra verification. It appears in your review queue. |
block | 80-100 | allow | block | Stop 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.
| Event | When to send it | What it catches |
|---|---|---|
signup | Account created | Multi-accounts, bots, VPN signups, disposable emails |
login | Successful login | Account sharing, country changes, new devices |
offer_click | User opens an offer | Starts the clock for offer speed |
conversion | Postback from the offerwall or network | Offers completed too fast, duplicate transactions, conversion bursts |
cashout | User requests a withdrawal | Shared payout addresses, cashout velocity, new-account cashouts |
custom | Anything else you want scored | Device 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.
| Code | Meaning | Group | Weight |
|---|---|---|---|
ip_tor | Tor exit node | Network | 60 |
ip_vpn | VPN connection | Network | 45 |
ip_datacenter | Datacenter / hosting IP | Network | 40 |
timezone_mismatch | Browser timezone does not match IP location | Network | 20 |
webrtc_ip_leak | Real IP leaked in another country | Network | 30 |
ip_multi_timezone | Same IP used with many different timezones (proxy exit) | Network | 50 |
proxy_farm_ip | Several accounts on one IP, all with the same foreign clock (shared proxy) | Network | 60 |
provider_rotation | Many internet providers in a few days, with a foreign clock (rotating residential proxy) | Network | 45 |
privacy_relay | iCloud Private Relay (privacy feature) | Network | 5 |
proxy_headers | Request came through a proxy | Network | 20 |
geo_sources_disagree | Geolocation sources disagree | Network | 45 |
ip_shared_with_accounts | Same IP used by other accounts today | Network | 25 |
country_changed | Country changed | Network | 15 |
impossible_travel | Impossible travel: IPs in two distant countries within hours | Network | 50 |
locale_country_mismatch | Browser language from another country | Network | 30 |
phone_country_mismatch | Phone from another country than the IP | Network | 20 |
ip_flagged_on_network | IP blocked on other websites | Network | 25 |
device_shared_with_accounts | Device shared with other accounts | Device | 55 |
automation_detected | Bot or automation tool | Device | 70 |
auto_clicker | Auto-clicker on the phone | Device | 55 |
scripted_behavior | Scripted page use | Device | 45 |
emulator_or_vm | Emulator or virtual machine | Device | 45 |
browser_tampering | Browser tampering / spoofing | Device | 35 |
device_rooted | Rooted phone | Device | 25 |
incognito | Private browsing | Device | 10 |
device_spoofed | Fake phone model | Device | 55 |
emulator_profile | Emulator default profile | Device | 60 |
cloud_phone | Cloud phone | Device | 60 |
phone_farm_display | Phone farm display | Device | 45 |
device_market_mismatch | China-only phone abroad | Device | 25 |
storage_cleared_reappeared | Cleared cookies and came back | Device | 15 |
no_device_data | No device data sent | Device | 15 |
request_reused | Device token reused by another account | Device | 40 |
device_farm_proxy | Phone farm on residential proxies | Device | 85 |
device_clones | Device clones: one phone resetting its identity to pose as many new accounts on one network | Device | 55 |
payout_address_shared | Payout address used by other accounts | Account | 70 |
email_disposable | Disposable email | Account | 25 |
email_invalid | Email address that cannot receive mail (no such mail domain) | Account | 35 |
email_shared | Same email as another account | Account | 50 |
phone_shared | Phone number shared by other accounts | Account | 50 |
phone_voip | VoIP or virtual phone number | Account | 40 |
phone_invalid | Invalid phone number | Account | 30 |
many_devices_per_account | Too many devices on one account | Account | 20 |
flagged_on_network | Flagged on other websites protected by CashoutGuard | Account | 45 |
face_same_person | Same face as other accounts | Account | 0 |
offer_completed_too_fast | Offer completed impossibly fast | Behavior | 40 |
slow_after_click | Converted long after the click | Behavior | 0 |
conversion_velocity | Too many conversions per hour | Behavior | 30 |
conversion_without_click | Conversion with no click from your wall | Behavior | 35 |
click_conversion_country_mismatch | Clicked in one country, converted in another | Behavior | 30 |
offer_country_mismatch | Offer country differs from the user’s | Behavior | 45 |
click_velocity | Too many offer clicks in a few minutes | Behavior | 35 |
earnings_spike | Earnings far above a normal user | Behavior | 30 |
source_high_reversals | Source with many chargebacks | Behavior | 45 |
offer_high_reversals | Offer with many chargebacks | Behavior | 35 |
duplicate_transaction | Duplicate transaction ID | Behavior | 60 |
offer_repeated_other_publisher | Same offer already done through another publisher | Behavior | 85 |
offer_repeated_other_account | Same offer already done by another account on this device | Behavior | 85 |
offer_farm_burst | Farm wave: many new accounts with farm devices on this offer within hours | Behavior | 30 |
signup_burst | Signup burst: several accounts signed up within seconds of each other from different IPs | Behavior | 25 |
face_check_required | Face check required, not done yet | Behavior | 0 |
face_check_failed | Face check failed | Behavior | 0 |
publisher_farm_wave | Farm wave of its publisher: most new accounts it sent to this offer came from cloud phones or emulators | Behavior | 55 |
cashout_velocity | Too many cashouts per day | Behavior | 30 |
new_account_cashout | Cashout from a brand-new account | Behavior | 20 |
blocklisted | On your blocklist | Your lists | 100 |
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:
- cashoutguard.php: PHP 7.4+, one file, no Composer. require it and go.
- composer require cashoutguard/cashoutguard-php: the same PHP client with its README, for your own vendor folder.
- npm install @cashoutguard/node: Node 18+, TypeScript types included.
- cashoutguard-wordpress.zip: WordPress plugin: the browser script on every page, signups and logins scored, and hooks for cashouts, offerwall conversions and reversals.
Errors and limits
| HTTP | Body | Meaning |
|---|---|---|
| 401 | missing_or_invalid_secret_key | Missing, 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". |
| 404 | not_found | Account not found (account endpoints). |
| 422 | { "message", "errors" } | Invalid body. errors lists each field. |
| 429 | Too Many Requests | Rate limit reached. The server API allows 3,000 requests per minute per site. |
| 401 · agent.js | unknown_public_key | The data-key is not a public key of any site. Copy pk_live_... again from Install. |
| 403 · agent.js | origin_not_allowed | The 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. |
| 403 | account_suspended | The account is suspended, usually for an unpaid invoice. Check Billing. |
| 503 | temporarily_unavailable | Short 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.