DetectBT
DetectBT is a browser bot detection API: a script (about 23 KB gzipped) checks the browser invisibly, with no puzzle for the visitor, and your server verifies the signed token it issues to get a verdict such as human, bot, fraud or unknown. It blocks nothing on its own: by default your server refuses only a verified bot or a forged token, and decides everything else.
From our test runs: Playwright 1.63 · headless Chromium. 5 of 6 browser checks flagged; verdict bot, risk 100.
Lab results: our eval harness against a local worker, September 2026. The headed stealth session is a known miss; see Lab results below.
What does DetectBT checkin the browser?
Eight families of signal. A verdict rests on definitive tells, such as navigator.webdriver, or on several families agreeing. However, we log anything not yet measured on real users rather than score it.
Automation tells
navigator.webdriver, CDP (Chrome DevTools Protocol) and driver artefacts, Playwright, Puppeteer and Selenium patches.
Stealth-plugin tells
The lies stealth plugins tell to hide: patched functions, detached iframes, a worker that disagrees with the page.
Engine coherence
Does the JavaScript engine match the browser the user agent claims? Version, error shapes, headless geometry.
Rendering & environment
Canvas, WebGL and the GPU (graphics processing unit), audio, fonts, DOM geometry and speech voices.
TLS coherence
The TLS handshake Cloudflare sees, checked for consistency across the session. Logged today; it only gains weight once measured on real traffic.
Hidden challenge
A small program, different for each session, built to be answered by a real browser engine. Nothing for the visitor to see or solve.
Network
Cloud and datacenter ranges from the providers’ own lists, and Tor. iCloud Private Relay is exempt; signed AI agents come back as verified_agent.
Device key
A non-extractable, per-site key in IndexedDB signs each evaluation, so a returning browser is recognised on your site. No cookies.
How does your server verifya DetectBT token?
DetectBT issues a short-lived, signed token bound to your key. Your server checks it over HTTPS with DetectBT's /verify endpoint. A forged or tampered token comes back invalid and is refused; send expected_origin with it to also refuse a token minted on another site. A missing one is let through, flagged, so a script blocker or an outage on our side never locks out a real customer.
Non-blocking by default. Your server refuses only a verified bot or a provably bad token (forged, tampered, or bound to another site, request or network). Everything else, including a missing token, goes through to your handler flagged with the reason, so you decide.
Strict on the routes that matter. Mark a route sensitive: true and a missing or expired token is refused instead, unless our own health check shows DetectBT is down. Over your quota, visitors still get through: after a 10% grace, evaluations pass through unscored and are never billed. See the decision table →
// page: <script src="https://detectbt-api.detectbt.workers.dev/detect-bt.js?key=vip_pub_…"></script> // app.js async function onCheckout(cart) { const token = await DetectBT.getToken().catch(() => null); return fetch("/api/checkout", { method: "POST", headers: { ...(token ? { "x-detectbt-token": token } : {}), "content-type": "application/json", }, body: JSON.stringify(cart), }); } // server.ts const token = req.headers["x-detectbt-token"]; if (token) { const r = await fetch(DETECTBT_URL + "/verify", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ token, expected_origin: "https://your-site.example", api_key: process.env.DETECTBT_SECRET_KEY, // sk_live_…, server only }), }).then((res) => res.json()); if (r.valid === false && !r.expired) return res.sendStatus(403); // forged, tampered or bound elsewhere if (r.valid && r.verdict === "bot") return res.sendStatus(403); } // human, fraud, unknown, expired or no token: proceed, and hold fraud for review if you like
There are no npm packages: call /verify from your server with fetch, as above, and apply the decision table (Docs → DetectBT).
How is DetectBT differentfrom a CAPTCHA?
No puzzles. No pain. A CAPTCHA asks people to prove they are human; DetectBT asks the browser instead. Every evaluation includes a hidden challenge: a small program, different for each session, built to be answered by a real browser engine. Scripting it means re-implementing browser layout and canvas, and its encoding changes with every release. It runs in the background, with nothing to see or solve.
What does DetectBT catch,and what does it miss?
| Setup | Result |
|---|---|
| Default and lightly evaded automation (13 setups) | 13 / 13 blocked |
| puppeteer-extra stealth, headless | bot · blocked |
| puppeteer-extra stealth, headed real Chrome | human · not caught |
| Real Chrome attached over CDP | human · not caught |
| Appium XCUITest driving iOS Safari (simulator) | human · not caught |
| Scripted client that solves the hidden challenge without a browser | human · not caught |
| Forged request with captured signals, no challenge | unknown · not allowed |
| Real browsers, unautomated (Mac, iOS and Android simulators) | all human |
| Bundle size, gzipped | 23.3 KB |
Our eval harness and its current gates (eval/gates.json in the DetectBT repo), last full run September 2026: Windows 11 and macOS, against a local worker, not production traffic. Rows marked “not caught” are open issues. In addition, we are still measuring phones and real Safari on iOS, so test it on your own traffic before you rely on it.
DetectBT questions,answered
What teams ask before they add browser bot detection to a live product.
Yes. DetectBT shows the visitor no puzzle. Every evaluation includes a hidden challenge that runs in the background, and your server gets the verdict. If you want a visible challenge on some routes, you can add Cloudflare Turnstile as an opt-in step-up.
No. By default your server refuses only a verified bot or a provably bad token (forged, tampered, or bound to another site, request or network). Everything else, including a missing token, goes through to your handler flagged with the reason. On routes you treat as sensitive, refuse an expired token, and a missing one unless DetectBT’s own health check shows it is down.
For a good token: valid: true, the verdict (human, fraud, bot, unknown, verified_agent or unscored) and a risk_score from 0 (human) to 100 (bot), null when unscored. For a bad one: valid: false with the reason, such as expired, bad_signature or origin_mismatch. Your server sends the token from the x-detectbt-token header, with your secret key (sk_live_…), over HTTPS. Tokens are signed and valid for 5 minutes.
No. It keeps a non-extractable, per-site device key in the browser’s IndexedDB storage and a signed device certificate in localStorage. Together they let a returning browser be recognised on your site only, not across sites. Clearing the site’s data deletes both.
In our lab (September 2026, against a local worker, not production traffic), it did not catch headed puppeteer-extra stealth on real Chrome, real Chrome attached over the Chrome DevTools Protocol, Appium driving iOS Safari in a simulator, or a scripted client that solves the hidden challenge without a browser. It did block all 13 default and lightly evaded automation setups and headless puppeteer-extra stealth. Test it on your own traffic before you rely on it.
About 23 KB gzipped. The production /detect-bt.js (version 3.3.0) is 23,338 bytes when served with gzip and 64,784 bytes uncompressed, measured on 5 October 2026. Browsers that ask for Brotli or Zstandard get 24–25 KB. It collects signals in the browser’s idle time.
You’re billed for one evaluation per page load: the DetectBT script checks each tab once when it loads, and the first token your page requests reuses that check if it is under 4.5 minutes old. Each additional token is a new evaluation. Pages that are prerendered but never opened, and embedded iframes, aren’t evaluated automatically, and bot verdicts are never billed.
No. After a 10% grace allowance, evaluations pass through unscored, so your site keeps working while you upgrade or wait for the quota to reset.
No. Load the script with one tag and your publishable key (vip_pub_…), then call POST /verify from your server with fetch or any HTTP client. Every request and response field is in the docs.