Reference · v1

TrustLens API & SDK

Client-side fingerprinting, IP geolocation and trust scoring — through a single@trustlens/browser package or a direct REST integration. This reference covers every method and endpoint you need to ship.

3 services<60 KB gzippedIE11 · iOS Safari · Android WebView

Installation

The SDK is distributed as @trustlens/browseron npm with a drop-in CDN bundle for script-tag installs. The package ships ESM, CJS, and UMD builds — under 60 KB gzipped, no runtime dependencies beyond a Promise polyfill on very old browsers.

bash

# Modern bundlers (Next.js, Vite, Webpack, Rollup)
npm install @trustlens/browser
# or:   yarn add @trustlens/browser
# or:   pnpm add @trustlens/browser

Authentication

Every call — SDK or REST — is authenticated with an API key. Keys are per-project; create them in the dashboard. For browser SDK use the key goes in TrustLens.init(); for server-to-server use it goes in an Authorization: Bearer <key> header.

bash

# Never commit the key to a public repo. Use environment variables.
export TRUSTLENS_API_KEY="YOUR_API_KEY"

Public vs server keys. The public SDK key is safe to embed in your frontend bundle — it is rate-limited and scoped to the public methods below. For privileged backend operations, use a separate server key and keep it off the browser.

Initialize the SDK

Call TrustLens.init() exactly once when your page loads. The instance is a module singleton; subsequent method calls use the key from the last init.

typescript

// app/providers.tsx  (or any root client component)
"use client";
import { useEffect } from "react";
import TrustLens from "@trustlens/browser";

export default function TrustLensBoot() {
  useEffect(() => {
    TrustLens.init({ apiKey: "YOUR_API_KEY" });
  }, []);
  return null;
}

Device Fingerprint

TrustLens.getFingerprint() returns a deterministic device_id plus 30+ browser signals (canvas, WebGL, plugins, fonts, touch points, behaviour biometrics, prototype-pollution and automation markers). It runs entirely in the browser — no network call, no quota consumption.

typescript

import TrustLens from "@trustlens/browser";

const fp = TrustLens.getFingerprint();
console.log(fp.device_id, fp.is_tampered);

Response

json

{
  "device_id"            "e1012a1abc3267d8b68dde3e8355e34338af8e2469c37014b0405e66492074ee",
  "browser"              "Chrome",
  "os"                   "macOS",
  "device_type"          "desktop",
  "is_tampered"          false,
  "automation_artifacts" [],
  "prototype_pollution"  [],
  "movement_entropy"     2.8,
  "interaction_delay_ms" 1420
}

IP Location

TrustLens.getLocation()returns city-level geolocation for the caller's IP. The server resolves the IP from the TCP socket — the client never needs to guess. Backed by a GiST-indexed Postgres table with sub-millisecond lookup.

typescript

import TrustLens from "@trustlens/browser";

async function whereAmI() {
  const loc = await TrustLens.getLocation();
  console.log(loc.country_code, loc.city, loc.isp);
}

Response

json

{
  "ip"           "113.190.81.55",
  "subnet"       "113.190.81.0/24",
  "country_code" "VN",
  "country"      "Vietnam",
  "province"     "Ha Noi",
  "district"     "Ha Dong",
  "city"         "Ha Dong",
  "full_address" "Ha Dong, Ha Noi, Vietnam",
  "asn"          45899,
  "isp"          "VNPT",
  "organization" "VNPT"
}

Trust Score

TrustLens.getTrustScore() blends the fingerprint signals with server-side intelligence — IP2Proxy PX11 exact-IP matching, datacenter / VPN / Tor flags, timezone-spoof detection — and returns a single 0–100 trust_score plus a paired threat_level (“LOW” / “SUSPICIOUS” / “HIGH”) and recommended_action (“ALLOW” / “CHALLENGE” / “BLOCK”).

typescript

import TrustLens from "@trustlens/browser";

export async function onCheckout() {
  const result = await TrustLens.getTrustScore();
  if (result.recommended_action === "BLOCK" || result.is_bot) {
    // Route the visitor through an extra verification step.
  }
  return result;
}

Response

json

{
  "trust_score"         88,
  "threat_level"       "LOW",
  "recommended_action" "ALLOW",
  "is_bot"             false,
  "explanation" {
    "device_id" "e1012a1abc...",
    "device" {
      "browser"     "Chrome",
      "os"          "Windows",
      "device_type" "desktop"
    },
    "privacy" {
      "is_vpn"     false,
      "is_proxy"   false,
      "is_tor"     false,
      "is_hosting" false,
      "proxy_type" "",
      "usage_type" "RES",
      "service"    ""
    },
    "risk_breakdown"    [],
    "anomaly_details"   [],
    "fingerprint_score" 96,
    "fraud_score"       0
  }
}

GET/v1/utils/ip-location

IP Location REST

Server-to-server geolocation lookup for an arbitrary IPv4 or IPv6 address.

Request

bash

curl -X GET "https://api.trustlens.site/v1/utils/ip-location?ip=113.190.81.55" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Query parameters

iprequiredIPv4 or IPv6 literal. Example: 113.190.81.55

Response

json

{
  "ip"           "113.190.81.55",
  "subnet"       "113.190.81.0/24",
  "country_code" "VN",
  "country"      "Vietnam",
  "province"     "Ha Noi",
  "district"     "Ha Dong",
  "city"         "Ha Dong",
  "full_address" "Ha Dong, Ha Noi, Vietnam",
  "asn"          45899,
  "isp"          "VNPT",
  "organization" "VNPT"
}

POST/v1/analyze/trust-score

Trust Score REST

Accepts the fingerprint payload produced by TrustLens.getFingerprint() and returns the full trust analysis. Designed for cases where you collect fingerprints on the client but do the scoring decision in your backend.

Request

bash

curl -X POST "https://api.trustlens.site/v1/analyze/trust-score" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_agent":           "Mozilla/5.0 (X11; Linux x86_64) Chrome/124.0",
    "hardware_concurrency": 8,
    "canvas_hash":          "7f3e9a...",
    "timezone_offset":      -420,
    "device_memory":        8
  }'

Body

Any subset of the fields returned by getFingerprint(). Required: user_agent, canvas_hash, timezone_offset.

Response

json

{
  "trust_score"         88,
  "threat_level"       "LOW",
  "recommended_action" "ALLOW",
  "is_bot"             false,
  "explanation" {
    "device_id" "e1012a1abc...",
    "device" {
      "browser"     "Chrome",
      "os"          "Windows",
      "device_type" "desktop"
    },
    "privacy" {
      "is_vpn"     false,
      "is_proxy"   false,
      "is_tor"     false,
      "is_hosting" false,
      "proxy_type" "",
      "usage_type" "RES",
      "service"    ""
    },
    "risk_breakdown"    [],
    "anomaly_details"   [],
    "fingerprint_score" 96,
    "fraud_score"       0
  }
}

Error codes

TrustLens returns conventional HTTP status codes. A non-2xx response always carries a JSON body with an error field (machine-readable code) and a message field (human-readable). Retry 500 and 503 with exponential backoff; 401 / 402 are terminal until the caller fixes the underlying issue.

Code	Name	Meaning
200	OK	Request succeeded; payload follows in the body.
400	Bad Request	Malformed JSON, missing required field, or invalid IP literal.
401	Unauthorized	Missing, malformed, or revoked API key. Re-check the Authorization header.
402	Payment Required	Plan-level quota exhausted. Top up the billing bucket to resume.
429	Too Many Requests	Rate limit for this API key hit. Back off exponentially and retry.
500	Internal Error	Unexpected server-side failure. Safe to retry once with idempotent methods.
503	Service Unavailable	Quota backend is degraded. Retry using the `Retry-After` header.