API v3.2 - Latest

Developer
Documentation

Enterprise-grade fraud detection infrastructure. Deploy our distributed neural network across your entire traffic funnel in under 15 minutes. Guaranteed 99.97% bot detection accuracy.

<6ms

Average Latency

P99: 12ms

99.97%

Detection Rate

0.003% false positives

47+

Fingerprint Params

Canvas, WebGL, Audio

∞

Scalability

Auto-scaling cluster

Architecture Overview

PROTECTUS operates a globally distributed neural network infrastructure spanning 47 edge locations. Our proprietary Fingerprint X7 engine processes requests through multiple AI layers for unprecedented accuracy.

Global Edge Network

47 PoP locations worldwide. Requests are routed to the nearest edge node for sub-10ms response times. Full GDPR compliance with EU data residency options.

Neural Processing Unit

Custom silicon NPUs designed for fingerprint analysis. 2.4 billion parameter transformer model trained on 847TB of behavioral data.

Threat Intelligence

Real-time threat feed from Google, Meta, and Telegram partnerships. 4.2M known bot signatures updated every 30 seconds.

INFRASTRUCTURE DIAGRAM

Client SDK

Fingerprint Collection

Edge Layer

47 Global PoPs

AI Core

Neural Analysis

Guaranteed ROI

Our customers see an average 47% reduction in CPA and 2.3x improvement in conversion rates within the first 30 days. We guarantee results or your money back.

-47%

Cost Per Acquisition

2.3x

Conversion Rate

Quick Start

Get PROTECTUS running in production in under 15 minutes. Our SDK handles all fingerprint collection, behavioral analysis, and cryptographic session management automatically.

1. Install the SDK

bash

npm install @protectus/sdk @protectus/react

# or with yarn
yarn add @protectus/sdk @protectus/react

# or with pnpm  
pnpm add @protectus/sdk @protectus/react

2. Initialize in your application

typescript

import { ProtectusProvider, useProtectus } from '@protectus/react';

// Wrap your app with the provider
function App() {
  return (
    <ProtectusProvider 
      apiKey={process.env.PROTECTUS_API_KEY}
      options={{
        autoCollect: true,
        behavioralTracking: true,
        sessionPersistence: 'secure',
        clusterRegion: 'auto' // Routes to nearest edge node
      }}
    >
      <YourApp />
    </ProtectusProvider>
  );
}

// Use in any component
function CheckoutButton() {
  const { verify, isVerifying, lastResult } = useProtectus();
  
  const handleCheckout = async () => {
    const result = await verify({
      action: 'checkout',
      metadata: { cartValue: 299.99 }
    });
    
    if (result.isBot) {
      // Handle bot detection
      console.log('Bot detected:', result.signals);
      return;
    }
    
    // Proceed with checkout
    // result.sessionToken can be sent to your backend for verification
    processCheckout(result.sessionToken);
  };
  
  return (
    <button onClick={handleCheckout} disabled={isVerifying}>
      {isVerifying ? 'Verifying...' : 'Complete Purchase'}
    </button>
  );
}

Authentication

All API requests require authentication via API key. Keys are scoped to specific domains and can be rotated instantly from your dashboard without downtime.

http

POST /v1/verify HTTP/2
Host: api.protectus.io
X-API-Key: ptx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Request-ID: req_unique_idempotency_key
Content-Type: application/json

{
  "fingerprint": { ... },
  "behavior": { ... }
}

Security Note

Never expose your API key in client-side code. Use our SDK which handles secure key transmission via encrypted challenge-response protocol.

API Endpoints

POST/v1/verifyPrimary Endpoint

Core verification endpoint. Analyzes fingerprint data through our 47-parameter neural network and returns bot probability score with detailed signal breakdown.

Request Body

json

{
  "fingerprint": {
    "visitorId": "fp_a1b2c3d4e5f6g7h8",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "language": "en-US",
    "languages": ["en-US", "en"],
    "colorDepth": 24,
    "deviceMemory": 8,
    "hardwareConcurrency": 8,
    "screenResolution": [1920, 1080],
    "availableScreenResolution": [1920, 1040],
    "timezoneOffset": -300,
    "timezone": "America/New_York",
    "sessionStorage": true,
    "localStorage": true,
    "indexedDb": true,
    "openDatabase": true,
    "cpuClass": null,
    "platform": "Win32",
    "plugins": [
      { "name": "Chrome PDF Plugin", "filename": "internal-pdf-viewer" },
      { "name": "Chrome PDF Viewer", "filename": "mhjfbmdgcfjbbpaeojofohoefgiehjai" }
    ],
    "canvas": "canvas_fp_hash_xxxxxxxxxx",
    "webgl": {
      "vendor": "Google Inc. (NVIDIA)",
      "renderer": "ANGLE (NVIDIA, NVIDIA GeForce RTX 3080, D3D11)",
      "hash": "webgl_hash_xxxxxxxxxx"
    },
    "webglVendorAndRenderer": "Google Inc. (NVIDIA)~ANGLE (NVIDIA GeForce RTX 3080)",
    "adBlock": false,
    "hasLiedLanguages": false,
    "hasLiedResolution": false,
    "hasLiedOs": false,
    "hasLiedBrowser": false,
    "touchSupport": {
      "maxTouchPoints": 0,
      "touchEvent": false,
      "touchStart": false
    },
    "fonts": ["Arial", "Arial Black", "Calibri", "Cambria", "Century Gothic", "..."],
    "audio": "audio_context_hash_xxxxxxxxxx",
    "enumerateDevices": ["audioinput", "audiooutput", "videoinput"]
  },
  "behavior": {
    "mouseMovements": 287,
    "mouseVelocity": 142.5,
    "scrollEvents": 45,
    "scrollVelocity": 89.2,
    "keystrokes": 0,
    "keystrokeTiming": [],
    "clickEvents": 7,
    "clickAccuracy": 0.94,
    "focusBlurEvents": 3,
    "timeOnPage": 12450,
    "idleTime": 2340,
    "formInteractions": 2,
    "touchPressure": null
  },
  "context": {
    "url": "https://yoursite.com/checkout",
    "referrer": "https://google.com/search?q=your+product",
    "action": "checkout",
    "value": 299.99
  }
}

Response

json

{
  "success": true,
  "requestId": "req_1234567890abcdef",
  "timestamp": "2025-03-10T14:32:18.847Z",
  "latency": 5.8,
  "result": {
    "verdict": "human",
    "isBot": false,
    "confidence": 0.9847,
    "riskScore": 7,
    "riskLevel": "low",
    
    "signals": {
      "fingerprintIntegrity": {
        "score": 0.98,
        "anomalies": [],
        "uniqueness": 0.9999847
      },
      "behaviorAnalysis": {
        "score": 0.97,
        "humanLikelihood": 0.99,
        "automationSignals": 0,
        "mouseDynamics": "natural",
        "scrollPattern": "human"
      },
      "deviceTrust": {
        "score": 0.99,
        "knownDevice": true,
        "emulatorDetected": false,
        "vmDetected": false,
        "headlessDetected": false
      },
      "networkAnalysis": {
        "score": 0.95,
        "ipReputation": "clean",
        "proxyDetected": false,
        "vpnDetected": false,
        "torDetected": false,
        "datacenterIp": false,
        "geolocation": {
          "country": "US",
          "region": "NY",
          "city": "New York",
          "accuracy": "high"
        }
      },
      "threatIntelligence": {
        "knownBotSignature": false,
        "knownFraudRing": false,
        "recentAbuse": false,
        "blacklisted": false
      }
    },
    
    "sessionToken": "eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6InB0eF8yMDI1MDMxMCJ9...",
    "sessionExpiry": "2025-03-10T15:32:18.847Z",
    
    "recommendations": {
      "action": "allow",
      "captchaRequired": false,
      "manualReview": false,
      "rateLimit": false
    }
  },
  
  "billing": {
    "creditsUsed": 1,
    "creditsRemaining": 99847
  }
}

GET/v1/stats

Retrieve comprehensive statistics including bot detection rates, budget savings, and traffic quality metrics.

json

{
  "success": true,
  "period": "30d",
  "stats": {
    "totalVerifications": 2847563,
    "uniqueVisitors": 1923847,
    
    "verdicts": {
      "human": 2412847,
      "bot": 398472,
      "suspicious": 36244
    },
    
    "botTypes": {
      "scrapers": 124847,
      "clickFraud": 187423,
      "accountTakeover": 12847,
      "spam": 45832,
      "other": 27523
    },
    
    "performance": {
      "avgLatency": 5.7,
      "p50Latency": 4.2,
      "p95Latency": 8.9,
      "p99Latency": 12.1,
      "uptime": 99.998
    },
    
    "savings": {
      "estimatedBudgetSaved": 127847.50,
      "invalidClicksBlocked": 398472,
      "avgCpcSaved": 0.32,
      "roiMultiplier": 47.2
    },
    
    "quality": {
      "preProtectus": {
        "conversionRate": 1.2,
        "avgCpa": 47.80
      },
      "postProtectus": {
        "conversionRate": 2.76,
        "avgCpa": 25.30
      },
      "improvement": {
        "conversionRateDelta": "+130%",
        "cpaDelta": "-47%"
      }
    }
  }
}

POST/v1/verify/batchENTERPRISE

Process up to 1000 verifications in a single request. Ideal for offline analysis and historical traffic auditing.

Fingerprint X7 Technology

Our proprietary fingerprinting engine collects 47 unique device parameters that create a mathematically unique signature for each visitor. Even the most sophisticated bots cannot replicate genuine human device characteristics.

Hardware

GPU RendererCPU CoresDevice MemoryScreen ResolutionColor DepthTouch Support

Software

User AgentPlatformPluginsLanguagesTimezoneDo Not Track

Graphics

Canvas HashWebGL VendorWebGL RendererWebGL HashFont RenderingEmoji Rendering

Behavior

Mouse DynamicsScroll PatternsKeystroke TimingClick AccuracySession DurationIdle Patterns

Behavioral AI Engine

Our 2.4 billion parameter transformer model analyzes micro-behaviors that are impossible for bots to replicate. Trained on 847TB of human interaction data across 2.3 billion sessions.

Mouse Dynamics Analysis

Velocity curves, acceleration patterns, micro-corrections, and natural tremor detection

Scroll Behavior Modeling

Momentum physics, pause patterns, content engagement correlation

Keystroke Biometrics

Inter-key timing, dwell time, pressure variation (on supported devices)

Attention Modeling

Eye-tracking inference, reading speed, content consumption patterns

Official SDKs

JavaScript/TypeScript

@protectus/sdk

stable

React

@protectus/react

stable

Next.js

@protectus/next

stable

Vue

@protectus/vue

stable

Python

protectus-python

stable

PHP

protectus/php-sdk

stable

Ruby

protectus-ruby

stable

github.com/protectus/go-sdk

stable

Rate Limits & Quotas

Plan	Requests/Month	Rate Limit	Burst
Basic	100,000	100/sec	500
Professional	1,000,000	1,000/sec	5,000
Enterprise	Unlimited	Custom	Custom

Error Handling

json

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after 1 second.",
    "retryAfter": 1000,
    "requestId": "req_1234567890"
  }
}

Code	HTTP	Description
`INVALID_API_KEY`	401	API key is missing or invalid
`RATE_LIMIT_EXCEEDED`	429	Too many requests, retry after cooldown
`INVALID_FINGERPRINT`	400	Fingerprint data is malformed or incomplete
`QUOTA_EXCEEDED`	402	Monthly quota exhausted, upgrade required

Enterprise Support

Get dedicated support, custom SLAs, and direct access to our engineering team. We offer white-glove onboarding with guaranteed integration in under 24 hours.

Contact Sales Technical Support

DeveloperDocumentation

Architecture Overview

Global Edge Network

Neural Processing Unit

Threat Intelligence

Guaranteed ROI

Quick Start

Authentication

API Endpoints

Fingerprint X7 Technology

Behavioral AI Engine

Official SDKs

Rate Limits & Quotas

Error Handling

Enterprise Support

Developer
Documentation