Signal catalog

Every fraud signal, how it is detected, false positives.

WeightPoints a signal adds when it fires. Set yours in scoring.default.json.
Suspect scoreThe sum of fired weights, capped at 100, on every event.
ReasonsEvery event lists the signals that fired and what each added.
26 signals

Bots and automation

Scripted browsers, AI agents and input no person produced.

Spoofing and tampering

Devices and requests that lie about themselves.

Mobile apps

Signals from the React Native SDK.

Network and IP

Where the request comes from.

Accounts and devices

How accounts, browsers and devices relate.

Activity

How fast and how much.

Privacy tools

Legitimate privacy choices, reported for context.

Bots and AI agents

Every event carries botInfo, one verdict for the visit:

FieldValues
resultgood: a declared crawler (search engine, AI crawler) or an AI agent that proved its identity. bad: automation (the bot signal) or an AI agent that did not. notDetected: neither.
typesearchEngine, aiCrawler, aiAgent, automation, or null
name, providerFor example Googlebot / Google, ChatGPT agent / OpenAI, Playwright / null
identitysigned: proven by a verified HTTP message signature. verified: a crawler or agent confirmed by its operator's published IP ranges or by reverse DNS. unsigned: only claimed (user agent) or inferred. null for no bot.

A user agent proves nothing: anyone can send Googlebot. When a request claims to be Googlebot, Bingbot, Applebot, YandexBot, Baiduspider or Yahoo Slurp, Trace checks it the way those engines document: the IP's reverse DNS must end in the operator's domain and that name must resolve back to the same IP. Confirmed crawlers get identity verified; impostors get result bad. Results are cached per IP for six hours, and a lookup that takes over a second is skipped (the crawler stays unsigned). AI crawlers and agents publish IP lists rather than DNS names. With CRAWLER_RANGES_FILE set (filled by npm run crawler-ranges, which downloads the lists OpenAI, Perplexity, Google and Microsoft publish for GPTBot, OAI-SearchBot, ChatGPT, PerplexityBot, Perplexity, Googlebot and Bingbot), a request claiming one of those names is checked against its list, without DNS: inside it gets identity verified and result good (including ChatGPT and Perplexity acting for a user); outside it is an impostor with result bad (an agent such as ChatGPT then also fires aiAgent; a fake crawler shows in botInfo only). Crawlers without a published list (ClaudeBot, Bytespider and others) stay unsigned. The lists change every few days: refresh daily, because an IP the operator added after your last refresh reads as an impostor. Use createCrawlerVerifier({ ranges }) and fetchCrawlerRanges() from @trace-id/sdk-node/crawlers for the same check on your own routes, or pass crawlers: { ranges } to @trace-id/embed.

Signed agents (Web Bot Auth). Agents such as ChatGPT agent sign their requests with HTTP Message Signatures (RFC 9421, Ed25519) and publish their keys at <agent>/.well-known/http-message-signatures-directory. Trace checks the Signature-Input, Signature and Signature-Agent headers on the identify request: the signature must use tag web-bot-auth, cover @authority and the Signature-Agent header, be current (created, expires, valid for at most a day) and verify against a key from the agent's directory. Only directories you allow are fetched (AGENT_DIRECTORIES, default https://chatgpt.com), so a request cannot make the server call an arbitrary URL. Directories are cached for an hour. The directory's own signature is not checked yet.

To check agents on your own routes (checkout, login, an API, an MCP server), use createAgentVerifier from @trace-id/sdk-node/agents:

TypeScript
import { createAgentVerifier } from '@trace-id/sdk-node/agents';

const verifyAgent = createAgentVerifier({ allowedAgents: ['https://chatgpt.com'] });
const agent = await verifyAgent({ method: req.method, url: `https://${req.headers.host}${req.url}`, headers: req.headers });
if (agent?.verified) tagOrder({ placedBy: agent.agent });

It returns null for unsigned requests and { verified: false, reason } for signatures that fail (expired, unknown_key, bad_signature, agent_not_allowed, directory_unavailable, unsupported_components).

Cross-browser linking

Each browser gets its own visitorId: its storage and its canvas, audio and WebGL readings differ from other browsers on the same machine. To link them, the server builds a second profile from traits that belong to the device and OS, not the browser:

TraitWeightSource
os2 (must match)User agent, falling back to navigator.platform.
gpuVendor1 (must match)WebGL renderer, reduced to a vendor.
gpu3 (must match)WebGL renderer, reduced to vendor and model: Chrome's ANGLE (NVIDIA, NVIDIA GeForce RTX 3060 (0x00002504) Direct3D11 …) and Edge's NVIDIA GeForce RTX 3060 both become nvidia:3060. Firefox reports a stand-in model ("…, or similar") and Safari says "Apple GPU", so for them only the vendor is compared. Laptops with two GPUs give different browsers different GPUs (Chrome on the discrete NVIDIA, Edge on the integrated AMD or Intel), so when one side is integrated and the other discrete, the GPU is left out of the comparison instead of ruling the device out.
screen2 (must match)Screen size, orientation-independent, and color depth.
cpu1navigator.hardwareConcurrency.
touch0.5navigator.maxTouchPoints.
timezone1.5IANA timezone.
language0.5Primary language, without region.
fonts2.5Installed fonts, from the OS, so every browser sees nearly the same set. Compared as a bitmap of the ~60 tested fonts with partial credit (Jaccard), because engines occasionally measure one font differently; older SDKs fall back to an exact match of the fonts hash.
voices1.5Installed text-to-speech voices (local voices only; network voices come with the browser). Hashed in the browser.
displayPrefs1Display and accessibility settings from the OS: color gamut, pointer, hover, reduced motion, forced colors. Hashed in the browser.
gpuArch2WebGPU adapter vendor and architecture (nvidia/ampere); often less masked than WebGL in Firefox and Safari. Hashed in the browser.
screenLayout1Taskbar or dock size and edge (screen minus available area, availLeft/availTop), set by the OS. Hashed in the browser.
mediaDecode1Which of H.264, VP9 and AV1 (1080p, 4K) the GPU decodes in hardware (mediaCapabilities, "power efficient"). Hashed in the browser.
keyboard1Installed keyboard layout (navigator.keyboard.getLayoutMap, Chromium only; not compared elsewhere). Hashed in the browser.
clock2Device clock offset from the server, from the SDK's send time. Every browser shares the OS clock. Only counts when at least one side is off by 2 s or more (a synced clock says nothing); matches within 2 s.

The GPU-dependent traits (gpu, gpuVendor, gpuArch, mediaDecode) are left out together when one browser got the integrated GPU and the other the discrete one.

Every trait except the font bitmap and clock offset is stored as a hash. Similarity is the weighted share of matching traits among those both sides reported; it is 0 if any "must match" trait differs or if the two sides share less than 60% of the total weight. That similarity is then scaled by what the network says:

How the visitors are connectedFactorvia
Two or more networks in common (home and work, say)1sharedNetwork
One network in common, used by at most 5 visitors (a home router)1sharedNetwork
One network, up to busyNetworkVisitors (20) visitors0.95sharedNetwork
One network, up to 100 visitors0.85sharedNetwork
One busier network (campus, mobile carrier)0.75sharedNetwork
No network in common, but at most rareHardwareMaxVisitors (3) other visitors share the exact hardware core (OS, GPU model, screen, CPU) and similarity is at least 0.950.75rareHardware

"In common" means both visitors were seen on the network (IPv4 /24, IPv6 /64, compared as a keyed hash; loopback counts as one) within networkWindowHours (30 days), not necessarily at the same time: a laptop seen at home in Chrome and at work in Firefox links as soon as Chrome is also seen at work. Links of at least 0.7 are returned in linkedVisitors; the crossBrowser signal turns on, and the shared deviceId is assigned, at 0.8. Rare-hardware links top out at 0.75, so they inform but never raise the score or merge device ids.

Why networks matter so much. Identical hardware is common: one laptop model across an office, every iPhone of a model in a city. Without a network in common, only hardware that is rare in your project is compared. Set crossBrowser.requireSharedNetwork to true to turn cross-network links off, or rareHardwareMaxVisitors to 0.

What it catches. One person opening a second browser, a browser profile or a private window in another browser to sign up again, even from another network if the device ever shared a network with the earlier browser, or has rare hardware. What it misses. Common hardware that never shared a network; virtual machines; anti-fingerprinting browsers that fake the GPU or screen; a changed monitor setup.

Turn it off with CROSS_BROWSER_LINKING=false. It is also off when IP_STORAGE=none, because it needs the network.

Anti-detect checks

The SDK reads the user agent, platform, languages, CPU count, time zone, webdriver flag and WebGL renderer three times: in the page, in a short-lived Web Worker (WebGL on an OffscreenCanvas), and in a fresh same-origin iframe. Spoofing tools often patch only the page. Only the names of fields that differ are sent, never the values. A worker blocked by CSP (worker-src without blob:) is reported as workerChecked: false and simply not compared.

The server adds two checks from data it already has: the WebGL renderer against the OS in the user agent (an Apple GPU on "Windows", Direct3D on "macOS", a desktop GeForce on "Android"; Adreno is allowed on Windows because of Snapdragon laptops) and the installed fonts against the OS (two fonts that ship only with macOS on a "Windows" browser, or the reverse; fonts installed by Office for Mac do not count).

Accounts and the device graph

Pass your account id as linkedId on identify (sign-in, sign-up, checkout). The server keeps which accounts were seen with which visitor (visitor_accounts), and since every browser of a device shares a deviceId, it can count accounts per device and devices per account. GET /v1/devices/:deviceId (secret key) lists the browsers and accounts of one device; see the API reference. Tune the thresholds in the accounts section of the scoring file.

TLS fingerprints

The server never sees the TLS handshake: the proxy that terminates TLS does. If that proxy can compute JA4 (nginx or HAProxy with a JA4 module, Cloudflare Workers via request.cf, and others), have it put the value in a header and set TLS_FINGERPRINT_HEADER to that header's name. The proxy must overwrite the header on every request, or a client could send its own. JA4_BLOCKLIST_FILE adds known bot fingerprints, one per line.

IP intelligence

Lists

The open build never bundles IP data. Lists are plain text, one IP or CIDR per line, # comments allowed, IPv4 and IPv6 both supported. npm run ip-data -w trace-server -- <dir> downloads free ones: Tor exits from the Tor Project, the ranges AWS, Google Cloud, Oracle Cloud, DigitalOcean and Linode publish, Apple's iCloud Private Relay ranges and DB-IP Lite databases (see Self-hosting: IP data). Changed files are reloaded within 10 minutes.

GeoIP and ASN

Set GEOIP_COUNTRY_DB (a Country or City database) and/or GEOIP_ASN_DB to MaxMind-format .mmdb files you obtained yourself, for example GeoLite2 under its own license or a commercial equivalent. They are never bundled because their licenses forbid redistribution. With an ASN database, DATACENTER_ASN_FILE (one ASN per line, AS16509 or 16509) also marks hosting networks as datacenterIp. Country and ASN appear in every event (ip.country, ip.asn).

IP data providers

For commercial VPN and residential proxy detection, name providers in IP_PROVIDERS: IPQualityScore, ipinfo, MaxMind web services, Spur, ipdata, ipapi.is, IP2Location.io, ipregistry, proxycheck.io, AbuseIPDB, ipgeolocation.io, ip-api, or your CDN's country header (settings). Their answers merge with the local files: a flag fires when any source reports it, so a provider's VPN verdict fires vpn (method publicVpn), its proxy verdict proxy, its Tor verdict tor, its hosting verdict datacenterIp. Lookups have a time budget and a per-IP cache, and a failing provider leaves those fields "not checked" instead of failing the event. Other providers plug in through @trace-id/ip-intel (IpIntelSource: a name and a lookup(ip)).

Location and proximity

With a City edition GeoIP database in GEOIP_COUNTRY_DB, every event's ip.location carries city, region, latitude and longitude (rounded to 2 decimals), accuracyRadiusKm, timezone and zone. zone is a geohash cell of about 39 by 20 km: devices that keep sharing a zone are near each other, or behind the same network. IP geolocation is an estimate for the network, not the person, and two places a kilometre apart can still fall either side of a cell edge, so compare neighbouring zones before concluding devices are far apart.

Identification components

These feed matching, not the suspect score. Each is hashed in the browser.

ComponentWeightReading
canvas32D canvas render (text, emoji, blending). Omitted when two renders differ (farbling).
webgl3Unmasked GPU vendor and renderer.
webglParams2WebGL limits and extension list.
audio2OfflineAudioContext compressor output.
fonts3Installed fonts by text measurement against fallbacks.
screen1.5Screen size (orientation-independent), color depth, pixel ratio.
hardware1.5CPU cores, device memory, touch points.
timezone1IANA timezone.
languages1navigator.languages.
platform1navigator.platform and UA-CH platform.
math1Floating-point results of transcendental functions.
css0.5CSS.supports feature bitmap.
media0.5Stable media queries (gamut, pointer, hover; not color scheme).
userAgentFamily2Browser family and OS, no version.
intl1Locale settings from the OS: resolved locale, calendar, numbering system, hour cycle, number and date formatting.
textMetrics1.5Canvas text measurement of Latin, emoji and rare-script strings in four generic font families: font rasterisation and emoji fonts differ by OS, version and settings.
webglRender2A small shaded scene rendered by WebGL and read back, plus shader precision formats. Omitted when two renders differ (the browser adds noise).
webgpu1.5WebGPU adapter feature list and selected limits.
apiSurface1Which of ~24 newer web APIs exist (presence only), navigator.vendor, productSub, PDF viewer, plugin names: pins down engine, version and build.
systemStyle1CSS system colours (Canvas, Highlight, AccentColor...) and system fonts (caption, menu...) as the browser maps them from the OS theme.
codecs1Which of 19 audio and video formats play (canPlayType, MediaSource.isTypeSupported): licensed codecs differ by OS, browser build and distribution.
webgl21.5WebGL 2 limits and extension list.
appInstall4Native apps only: SHA-256 of the platform install id (identifierForVendor, ANDROID_ID) salted with the app id. Two installs with different values are never matched, so phones of one model stay apart.
Edit this page on GitHub

This page is in the public repository: fix it and send a pull request.