Add live proxy & VPN detection to your site
One script tag on your pages, one JSON callback to your server. About five minutes, no SDK and nothing to host. 1,000 detections a day are free; for more there are plans from $49 a month.
This is the v2 format, which every account created from 6 November 2026 gets. Older accounts keep the v1
format they integrated (pd-lib.js, pdKey / pdVal,
is_proxy / is_vpn); signed in, the integration guide
on your dashboard always shows the format of your account.
Quick start
</body> on the pages you want to protect. Every page view is one
detection.
<script src="https://engine.proxydetect.live/pd.js?key=YOUR_API_KEY&ref=SESSION_ID" async></script>
That is the whole integration. Your dashboard shows the snippet with your key filled in, saves the callback URL, sends a test callback to your endpoint and runs a live detection against your own connection. The rest of this page is reference.
Loading the script
The script comes from engine.proxydetect.live, which answers from Germany or the United
States, whichever is closer. The request alone starts the server-side tests (TCP/IP fingerprint, TLS
timing, IP intelligence, packet flow); once the script runs in the browser it adds the browser tests
(WebRTC, latency, timezone, network behaviour) and reports back.
| Parameter | Meaning |
|---|---|
key |
Your API key. Required. |
ref |
Optional, up to 256 characters, URL-encoded: your session, order or user id. It comes back
unchanged as ref in the callback, so you know which visitor a verdict belongs to. It is
visible in your page source, so use an id, not a secret. |
Loading it from JavaScript
When the id is only known at runtime, or to detect at one moment (login, checkout) rather than on every page:
// Once per visit: after login, on checkout, wherever it matters.
const s = document.createElement('script');
s.src = 'https://engine.proxydetect.live/pd.js?key=YOUR_API_KEY&ref=' + encodeURIComponent(sessionId);
s.async = true;
document.head.appendChild(s);
React, Next.js and other single-page apps
Client-side routing does not reload the page, so mount the loader once per session and again when the session changes, for instance after login.
import { useEffect } from 'react';
export function ProxyDetect({ sessionId }) {
useEffect(() => {
if (!sessionId) return;
const s = document.createElement('script');
s.src = 'https://engine.proxydetect.live/pd.js?key=YOUR_API_KEY&ref=' + encodeURIComponent(sessionId);
s.async = true;
document.head.appendChild(s);
return () => s.remove();
}, [sessionId]);
return null;
}
Google Tag Manager, WordPress, Shopify
Paste the snippet as a Custom HTML tag firing on all pages (GTM), into the theme's footer (WordPress), or
into theme.liquid before </body> (Shopify). In GTM you can pass
{{Client ID}} or a data-layer variable as ref.
Visitors with JavaScript switched off
A browser without JavaScript does not load scripts at all. To classify those visitors too, add this line next to the tag: the image request alone runs the server-side tests, and the callback arrives about ten seconds later.
<noscript><img src="https://engine.proxydetect.live/pd.js?key=YOUR_API_KEY&ref=SESSION_ID" alt=""></noscript>
Callbacks
Every result is an HTTP POST of compact JSON (Content-Type: application/json,
User-Agent: pdServer <version>) to the callback URL on your dashboard. Answer with any
2xx status within 7 seconds; the body is ignored and nothing is retried, so acknowledge first and process
afterwards.
| Setting on the dashboard | What it does |
|---|---|
| Active callback | Always sent, once every test has finished: 3–8 seconds after the page view, about 10 when the browser never reports back. The complete verdict; decide on this one. |
| Passive callback | Off by default. A first verdict within about a second, from the server-side tests alone. Same
shape, with "type": "passive"; the active callback follows either way. |
| Only flagged visitors | Off by default. Skips the callback when a visitor is neither proxy nor VPN. Recommended in production; while you test from your own clean connection it means nothing arrives. |
| Details | Off by default. Adds score, hits and threats to every
callback. |
Saved settings reach the engines within three minutes. The Send test callback button on the
dashboard POSTs the sample below with "type": "test"; handle that value so a test never flags
a real session.
Scripts and AI agents change the same settings with your API key, without the dashboard:
GET https://proxydetect.live/app/api/settings?key=… returns them as url,
passive, onlyFlagged, details, tests and
domains. A POST to the same address with {"key": "…", "url": "https://…"}
changes what it names and keeps the rest, and POST https://proxydetect.live/app/api/settings/test
with {"key": "…"} sends the test callback. Every change is mailed to your account.
Result payload
By default the callback is the verdict and nothing else:
{"type":"active","id":"59d68ddfa135f3f0","ref":"session-8f3a1c","ip":"185.220.101.34","proxy":true,"vpn":false}
With details on:
{"type":"active","id":"59d68ddfa135f3f0","ref":"session-8f3a1c","ip":"185.220.101.34","proxy":true,"vpn":false,"score":{"proxy":85,"vpn":10},"hits":{"proxy":["datacenter","tcpip","tls","latency"],"vpn":["datacenter"]},"threats":[]}
| Field | Meaning |
|---|---|
type |
active, passive, or test from the dashboard button. |
id |
The detection session: one per page view, 16 hex characters. |
ref |
What you passed as ref, unchanged, or null. Your key is never echoed. |
ip |
The visitor's IP address as the engine saw it. |
proxy / vpn |
The verdicts, true or false. A visitor can be both (a VPN provider's
datacenter exit) or neither. |
score |
Details only. proxy and vpn from 0 to 100; the verdict is
true from 40. |
hits |
Details only. Per verdict, the tests that flagged the visitor and count towards that score (names below). |
threats |
Details only. Anomalies of the browser itself, such as JS_USER_AGENT_MISMATCH or
POST_PAYLOAD_NEVER_RECEIVED: a bot signal, independent of proxies. Empty when clean. |
Handling results
The simplest useful rule is proxy || vpn. For graded responses turn details on and use the
score: 100 is a hard fact – a Tor exit, a VPN exit node we enumerated ourselves, or
WebRTC showing two networks for one device – and worth blocking; 60 and above means
independent signals agree (an address on a list plus relay timing) and suits a CAPTCHA or extra
verification; 40–59 comes from connection timing alone, where a cautious integration
asks for a second look rather than acting. The callback arrives seconds after the page view, so store the
verdict against ref and read it on the visitor's next request.
Node.js / Express
app.post('/proxydetect/callback', express.json(), (req, res) => {
res.sendStatus(204); // acknowledge first, any 2xx will do
const { type, ref, proxy, vpn } = req.body;
if (type !== 'test' && (proxy || vpn)) flagSession(ref);
});
Python / Flask
@app.post("/proxydetect/callback")
def proxydetect_callback():
r = request.get_json(force=True)
if r["type"] != "test" and (r["proxy"] or r["vpn"]):
flag_session(r["ref"])
return "", 204
PHP
<?php
$r = json_decode(file_get_contents('php://input'), true);
if ($r['type'] !== 'test' && ($r['proxy'] || $r['vpn'])) {
flag_session($r['ref']);
}
http_response_code(204);
Reading results in the browser
The script sets window.pd.id, and GET https://engine.proxydetect.live/r?id=…
returns the same fields as a callback with details, plus done. Good for showing a notice or a
CAPTCHA right away; not a substitute for the callback, because what a browser reads it can also fake.
// Optional: wait for the verdict in the page, e.g. to show a CAPTCHA.
const s = document.createElement('script');
s.src = 'https://engine.proxydetect.live/pd.js?key=YOUR_API_KEY&ref=SESSION_ID';
s.onload = async () => {
if (!window.pd) return; // no session, e.g. the daily allowance is used up
for (let i = 0; i < 20; i++) {
const r = await fetch('https://engine.proxydetect.live/r?id=' + window.pd.id).then((x) => x.json());
if (r.done) return console.log(r.proxy, r.vpn, r.score);
await new Promise((ok) => setTimeout(ok, 1000));
}
};
document.head.appendChild(s);
Detection tests
All tests run and count towards the scores unless you deselect some under Settings on the
dashboard. These are the names in hits; the first eleven need no JavaScript.
| Test | What it checks |
|---|---|
datacenter | IP belongs to a hosting provider |
proxyList | IP is on a proxy list |
vpnList | IP is on a VPN list |
vpnExit | IP is a VPN exit node we enumerated ourselves |
tor | IP is a Tor exit node |
headers | HTTP headers reveal a forwarding proxy |
tcpip | TCP/IP fingerprint contradicts the browser |
tls | TLS handshake time vs. TCP round trip: an extra hop |
flow | Packet timing of a relay |
ai | AI classifier on the first packets |
ping | Handshake latency vs. ping to the IP |
webrtc | WebRTC (UDP) leaves from another network than TCP |
latency | WebSocket vs. TCP latency mismatch |
highLatency | Latencies too high for a direct path |
timezone | Browser timezone contradicts the IP location |
net | Network behaviour (DNS resolution, blocked requests) |
FAQ
Does it slow my pages down?
No. The tag is async and under 30 KB (10 KB compressed); it never blocks rendering. The tests run on the engine and in the background after the page has loaded.
I use a Content-Security-Policy.
Allow script-src https://engine.proxydetect.live and connect-src
https://engine.proxydetect.live https://engine.proxydetect.live:22379
wss://engine.proxydetect.live:7630, plus img-src https://engine.proxydetect.live for
the latency probes. Under a stricter policy the tests that need other hosts are inconclusive; the verdict
still works.
Is the key a secret?
No, it is in your page source by design. It tells the engine which account a detection is billed to and
where its callback goes, and it reads nothing back. So that nobody else can spend your detections with it,
list your domains under Settings on the dashboard: the engines then refuse every other site without
counting it. A page that sends no referrer needs referrerpolicy="origin" on the script tag.
Can I use several websites with one key?
Yes. The key identifies your account, not a domain. Put the site into ref if you need to tell
them apart.
What happens at my daily limit?
From then until 00:00 UTC the script starts no detection and logs a warning to the browser console, so no callbacks arrive. We send an email when it happens; the usage page on your dashboard shows how close you are.
Where is the data processed, and how long is it kept?
On our own engines in Germany and the United States. Sessions are kept in memory for a few minutes to compute the verdict, then stored briefly for analysis and quality control before they are removed. No cookies are set and no visitor is tracked across sites.
Why do I get no callbacks on my own machine?
Check that only flagged visitors is off while testing: a clean connection produces no callback with it on. Then run the live test on the dashboard; it uses your key and delivers a real callback. Saved settings reach the engines within three minutes.