# Quickstart

Guardian Stack is a fraud detection platform that helps businesses protect their applications from bots, account takeover, VPN abuse, browser tampering, and sophisticated fraud attempts. Guardian Stack capabilities include:

{% stepper %}
{% step %}

### **Real-time fraud detection**

Identify bots, VPNs, incognito browsing, and browser tampering with enterprise-grade accuracy.
{% endstep %}

{% step %}

### Risk assessment

Get actionable fraud signals and confidence scores for every visitor interaction.
{% endstep %}

{% step %}

### Developer-friendly

Simple 3-line integration that works with any stack.
{% endstep %}
{% endstepper %}

### 1. Get your API keys

Sign up for Guardian Stack to get your site key and secret key.

* Copy your Site Key (for client-side integration)
* Copy your Secret Key (for server-side event retrieval)

### 2. Add the client-side agent

Install the Guardian JS SDK to collect fraud signals from browsers:

```bash
npm install @guardianstack/guardian-js
# or
yarn add @guardianstack/guardian-js
```

Usage:

```javascript
import { loadAgent } from '@guardianstack/guardian-js';

// Initialize the agent once when your app starts
const guardian = await loadAgent({ 
  siteKey: 'YOUR_SITE_KEY' 
});

// Call .get() when you need fraud protection (login, signup, payment, etc.)
// Don't call on every page load - only for critical user actions
const response = await guardian.get();

const requestId = response?.requestId;

// Send requestId to your server for fraud analysis
// Your backend will use this ID to get the full fraud assessment
```

{% hint style="warning" %}
**EU/EEA deployments.** If the website or application accessing the agent is accessible to users in the European Economic Area, obtain prior consent under Article 5(3) of the ePrivacy Directive before calling `loadAgent()`. A simple pattern: gate the `loadAgent()` call behind your consent manager's fraud-prevention or security category.

**UK deployments.** The UK Data (Use and Access) Act 2025 treats fraud-prevention fingerprinting as strictly necessary under PECR. A consent gate is generally not required for UK-only deployments, but a privacy notice disclosure remains necessary.

**US deployments.** No prior consent is generally required under US state privacy laws, but disclose the processing in your privacy notice.
{% endhint %}

### 3. Get fraud signals on your server

Install the server SDK to analyze fraud signals:

```javascript
import {
  createGuardianClient,
  isBot,
  isVPN,
  isTampering,
  isIncognito,
  isVirtualized,
} from '@guardianstack/guardianjs-server';

// Initialize the client once in your app with your secret key
const client = createGuardianClient({
  secret: process.env.GUARDIAN_SECRET_KEY
});

// In your API route handler (e.g., /api/login, /api/signup)
// Use the requestId from the client-side guardian.get() call
const event = await client.getEvent(requestId);

// Get simple boolean fraud indicators for quick decisions
const risks = {
  bot: isBot(event),                 // Selenium, Puppeteer, headless browsers
  vpn: isVPN(event),                 // VPN/proxy usage detection
  tampering: isTampering(event),     // Anti-detect browsers, spoofed APIs
  incognito: isIncognito(event),     // Private/incognito browsing mode
  virtualized: isVirtualized(event)  // VM or emulated environments
};

// Now make your fraud decision based on these risks
```

You can also call the Guardian Stack API directly from your backend without using the server SDK:

```bash
curl --location \
  --retry 5 \
  --retry-max-time 60 \
  --header 'Accept: application/json' \
  'https://api.guardianstack.ai/request/event/YOUR_EVENT_ID?secret=YOUR_GUARDIAN_SECRET_KEY'

```

Make sure to replace `YOUR_EVENT_ID` and `YOUR_GUARDIAN_SECRET_KEY`.

Example response:

```json
{
    "identification": {
        "id": "example-request-id",
        "visitorId": "example-visitor-id",
        "ip": "192.0.2.1",
        "timestamp": "2025-01-01T12:00:00.000Z",
        "url": "https://example.com/",
        "location": {
            "is_eu_member": true,
            "calling_code": "1",
            "currency_code": "USD",
            "continent": "NA",
            "country": "United States",
            "country_code": "US",
            "state": "California",
            "city": "San Francisco",
            "latitude": 37.7749,
            "longitude": -122.4194,
            "zip": "94103",
            "timezone": "America/Los_Angeles",
            "local_time": "2025-01-01T04:00:00-08:00",
            "is_dst": false
        },
        "browser": {
            "browserName": "Chrome",
            "browserMajorVersion": "120",
            "browserFullVersion": "120.0.0.0",
            "platform": "Win32",
            "os": "Windows",
            "osVersion": "10",
            "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
        }
    },
    "botDetection": {
        "detected": true,
        "score": 0.85,
        "automationSignalsPresent": true,
        "indicators": [
            {
                "source": "automation_api",
                "confidence": "high"
            }
        ]
    },
    "ipInfo": {
        "ip": "192.0.2.1",
        "rir": "ARIN",
        "is_bogon": false,
        "is_mobile": false,
        "is_satellite": false,
        "is_crawler": true,
        "is_datacenter": true,
        "is_tor": false,
        "is_proxy": true,
        "is_vpn": true,
        "is_abuser": false,
        "company": {
            "name": "Example Hosting",
            "abuser_score": "0.2 (Low)",
            "domain": "example.com",
            "type": "hosting",
            "network": "192.0.2.0/24"
        },
        "abuse": {
            "name": "Abuse Department",
            "address": "123 Example St, San Francisco, CA",
            "email": "abuse@example.com",
            "phone": "+1-555-123-4567"
        },
        "asn": {
            "asn": 12345,
            "abuser_score": "0.1 (Low)",
            "route": "192.0.2.0/24",
            "descr": "EXAMPLE-ASN",
            "country": "us",
            "active": true,
            "org": "Example Organization",
            "domain": "example.com",
            "abuse": "abuse@example.com",
            "type": "hosting",
            "created": "2000-01-01",
            "updated": "2020-01-01",
            "rir": "ARIN"
        },
        "location": {
            "is_eu_member": true,
            "calling_code": "1",
            "currency_code": "USD",
            "continent": "NA",
            "country": "United States",
            "country_code": "US",
            "state": "California",
            "city": "San Francisco",
            "latitude": 37.7749,
            "longitude": -122.4194,
            "zip": "94103",
            "timezone": "America/Los_Angeles",
            "local_time": "2025-01-01T04:00:00-08:00",
            "local_time_unix": 1735837200,
            "is_dst": false
        },
        "elapsed_ms": 0.5
    },
    "vpn": {
        "detected": true,
        "confidence": "high",
        "browserTimezone": "Europe/London",
        "ipTimezone": "America/Los_Angeles",
        "timezoneDifference": 8
    },
    "tampering": {
        "detected": true,
        "anomalyScore": 0.75,
        "antiDetectBrowser": true,
        "indicators": [
            {
                "source": "browser_api_inconsistency",
                "severity": "high"
            },
            {
                "source": "viewport_screen_mismatch",
                "severity": "medium"
            }
        ]
    },
    "privacySettings": {
        "detected": true,
        "score": 0.6,
        "indicators": [
            {
                "source": "storage_blocked",
                "confidence": "medium"
            }
        ]
    },
    "virtualization": {
        "detected": true,
        "confidence": "high",
        "indicators": [
            {
                "source": "vm_hardware_detected",
                "confidence": "high"
            },
            {
                "source": "performance_metrics",
                "confidence": "medium"
            }
        ]
    },
    "incognito": {
        "detected": true,
        "score": 0.9,
        "indicators": [
            {
                "source": "storage_anomaly",
                "confidence": "high"
            }
        ]
    },
    "velocity": {
        "5m": 25,
        "1h": 120,
        "24h": 500
    }
}
```

### 4. Make fraud decisions

Use the fraud signals to protect your application:

```javascript
// Example fraud prevention logic in your API endpoint
// Adjust thresholds based on your risk tolerance and user experience goals

if (risks.bot || risks.tampering || risks.virtualized) {
  // High-risk indicators: automated attacks, spoofed environments
  // These almost always indicate malicious intent
  return { action: 'block', reason: 'Suspicious automation detected' };
}

if (risks.vpn && risks.incognito) {
  // Medium-risk: privacy tools + anonymization
  // Could be legitimate privacy-conscious users or fraud attempts
  return { action: 'challenge', reason: 'Additional verification required' };
}

// Low-risk: Normal user behavior
// Let the request proceed without friction
return { action: 'allow' };

// Pro tip: You can also combine with other signals like:
// - Geographic anomalies (user suddenly in different country)
// - Velocity checks (too many requests too quickly)
// - Account history (new account vs established user)
```

### 🎉 You're protected!

Congratulations! You now have enterprise-grade fraud detection running in your application. Here's what you've accomplished:

✅ Real-time fraud detection - Your app now identifies bots, VPNs, and suspicious behavior

✅ Risk-based decisions - You can block, challenge, or allow users based on fraud signals

✅ Production-ready - Your integration is secure and scales with your traffic


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.guardianstack.ai/documentation/getting-started/quickstart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.