TypeScript/Node.js SDK

Official TypeScript SDK for the Circuit KYC Network API.

---

Installation

npm install @circuit-kyc/sdk
# or
yarn add @circuit-kyc/sdk

Requirements: Node.js 18+

---

Quick Start

import { CircuitClient } from '@circuit-kyc/sdk';

const client = new CircuitClient({ apiKey: 'sk_sandbox_your-key' });

const result = await client.checkEligibility({
  email: 'user@example.com',
  phone: '+14155551234',
});

if (result.eligible) {
  console.log(`KYC Level: ${result.kyc_level}`);
}

---

Configuration

import { CircuitClient } from '@circuit-kyc/sdk';

const client = new CircuitClient({
  apiKey: 'sk_sandbox_your-key', // Required
  baseUrl: undefined,             // Auto-detected from key
  timeout: 30000,                 // Request timeout (ms)
  maxRetries: 3,                  // Retry attempts
  environment: undefined,         // 'sandbox' or 'production'
});

---

Error Handling

import {
  CircuitClient,
  AuthenticationError,
  RateLimitError,
  InsufficientCreditsError,
  ValidationError,
} from '@circuit-kyc/sdk';

const client = new CircuitClient({ apiKey: 'sk_sandbox_your-key' });

try {
  const result = await client.checkEligibility({ email: 'test@example.com' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
    await sleep(error.retryAfter * 1000);
  } else if (error instanceof InsufficientCreditsError) {
    console.log(`Low balance: ${error.currentBalance} credits`);
  } else if (error instanceof ValidationError) {
    console.log('Validation error:', error.errors);
  }
}

---

API Reference

Eligibility

const result = await client.checkEligibility({
  email: 'user@example.com',
  phone: '+14155551234',
  first_name: 'John',
  last_name: 'Doe',
  date_of_birth: '1990-01-15',
  ssn_last4: '1234',
  address: {
    street: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    zip: '94102',
  },
});

Risk Assessment

const risk = await client.assessRisk({
  subjectId: 'user-123',
  email: 'user@example.com',
  ipAddress: '203.0.113.42',
  transactionAmount: 5000.0,
  transactionCurrency: 'USD',
});

console.log(`Risk Level: ${risk.risk_level}`); // low, medium, high, critical
console.log(`Risk Score: ${risk.risk_score}/100`);

Credentials

// Issue
const credential = await client.issueCredential({
  subjectId: 'user-123',
  claims: { kyc_level: 'full' },
  expiresInDays: 365,
});

// Verify
const result = await client.verifyCredential(credentialJwt);
console.log(`Valid: ${result.valid}`);

// Claim from eligibility
const credential = await client.claimIdentity({
  subjectId: 'user-123',
  email: 'user@example.com',
  eligibilityRequestId: eligibility.request_id,
  consentGiven: true,
});

Data Ingestion

const result = await client.ingestData({
  records: [
    {
      subject_id: 'user-123',
      email: 'john@example.com',
      kyc_level: 'full',
      verified_at: '2024-01-15T10:30:00Z',
    },
  ],
});

console.log(`Batch ID: ${result.batch_id}`);

Billing

// Check balance
const balance = await client.getCreditBalance();
console.log(`Available: ${balance.available_credits}`);

// Get pricing
const pricing = await client.getPricing();

---

TypeScript Types

Full type definitions are included:

import type {
  EligibilityResult,
  RiskAssessment,
  Credential,
  CreditBalance,
  CheckEligibilityRequest,
} from '@circuit-kyc/sdk';

const request: CheckEligibilityRequest = {
  email: 'test@example.com',
};

const result: EligibilityResult = await client.checkEligibility(request);

---

Source Code

github.com/circuit-kyc/typescript-sdk