> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fingerprintiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript SDK Reference

Complete API reference for @fingerprintiq/js.

## Class: FingerprintIQ

### Constructor

```typescript
new FingerprintIQ(config: FingerprintIQConfig)
```

Your API key from the dashboard. Use `fiq_live_` for production and `fiq_test_` for development. Test keys have full functionality and don't count toward your monthly quota.

API endpoint URL. Defaults to `https://fingerprintiq.com`. Override for custom proxy or self-hosted deployments.

Request timeout in milliseconds. Defaults to `10000` (10 seconds). Signal collection itself takes 50–150 ms; the rest of the timeout budget covers the network round-trip.

Enable Web3 wallet detection. Defaults to `true`. Set to `false` to skip wallet enumeration and save approximately 50 ms of collection time on non-Web3 sites.

### Methods

#### `identify(options?: IdentifyOptions): Promise<IdentifyResponse>`

Collects all configured signals in parallel and sends them to the FingerprintIQ API. Returns the compact identification result including the stable `visitorId`, `requestId`, verdicts, and scores. Full signal data is available server-side via the Events API using `result.requestId`.

```typescript
const fiq = new FingerprintIQ({ apiKey: 'fiq_live_...' });

// Basic usage
const result = await fiq.identify();
console.log(result.visitorId);      // "iq_01hns3k6tez83695a6t714s6n1"
console.log(result.requestId);      // "req_01hns3k6tez83695a6t7"
console.log(result.visitCount);     // 3
console.log(result.botProbability); // 0.05
console.log(result.suspectScore);   // 0

// With metadata and per-call options
const result = await fiq.identify({
  tag: { page: 'checkout', experiment: 'v2' },
  linkedId: 'user_123',
  timeout: 5000,
});
```

**Options:**

Arbitrary key-value metadata to attach to this event. Stored with the event and accessible via the Server API. Keys and values must be strings.

A string identifier to link this event to an authenticated entity (user ID, session ID, order ID). Enables querying all events for a specific entity via the Server API.

Per-call timeout override in milliseconds. Overrides the instance-level `timeout` for this call only.

**Throws:**
- `Error` if the API returns a non-200 status (message includes the HTTP status code)
- `Error` if the request exceeds the configured `timeout`
- `Error` if `apiKey` is not provided in the constructor config

The `FingerprintIQ` instance is lightweight and safe to reuse. Instantiate it once at module scope and call `identify()` whenever you need a fingerprint — don't create a new instance on each call.

## Types

### FingerprintIQConfig

```typescript
interface FingerprintIQConfig {
  apiKey: string;
  endpoint?: string;         // default: 'https://fingerprintiq.com'
  timeout?: number;          // default: 10000 (ms)
  detectWallets?: boolean;   // default: true
  cache?: {
    storage: 'sessionStorage' | 'localStorage' | 'memory';
    ttl: number;             // seconds
  };
}
```

### IdentifyOptions

```typescript
interface IdentifyOptions {
  tag?: Record<string, string>;  // Arbitrary metadata for this event
  linkedId?: string;             // Entity ID to link this event to
  timeout?: number;              // Per-call timeout override (ms)
}
```

### IdentifyResponse

```typescript
interface IdentifyResponse {
  requestId: string;        // Unique event identifier (format: req_<ulid>)
  visitorId: string;        // Stable device identifier (format: iq_<ulid>)
  confidence: number;       // 0.0 - 1.0 signal confidence
  botProbability: number;   // 0.0 - 1.0 bot likelihood
  suspectScore: number;     // 0 - 100 composite risk score
  visitCount: number;       // Total visits from this device
  firstSeenAt: number;      // Unix timestamp (ms) of first identification
  lastSeenAt: number;       // Unix timestamp (ms) of previous identification
  verdicts: {
    bot: { result: boolean; probability: number };
    vpn: { result: boolean; confidence: number };
    tor: { result: boolean };
    proxy: { result: boolean };
    incognito: { result: boolean };
    tampering: { result: boolean; anomalyScore: number };
    headless: { result: boolean };
    virtualMachine: { result: boolean };
    devtools: { result: boolean };
    privacyBrowser: { result: boolean; name: string | null };
    highActivity: { result: boolean };
    ipBlocklist: { result: boolean };
  };
  ip: string;               // Client IP address
  ipLocation: {
    country: string;
    city: string;
    region: string;
    latitude: number;
    longitude: number;
  };
  riskFactors: string[];    // Active risk indicators
  timestamp: number;        // Unix timestamp (ms) of this visit
}
```

## Bundle Size

The SDK is designed to be lightweight. Signal collection code is bundled inline — no dynamic imports or external dependencies.

| Build | Raw Size | Gzipped |
|-------|----------|---------|
| ESM | 37.7 KB | ~12 KB |
| CJS | 38.1 KB | ~12 KB |

## Browser Support

| Browser | Minimum Version |
|---------|----------------|
| Chrome | 80+ |
| Firefox | 78+ |
| Safari | 14+ |
| Edge | 80+ |
| Opera | 67+ |

Older browsers that lack specific APIs (e.g., OfflineAudioContext, WebGL) will return `null` for those signals rather than throwing. The core fingerprint remains functional with reduced signal coverage.