Verifyo Node.js SDK

Official Node.js/TypeScript SDK for the Verifyo Zero-Knowledge KYC API. Verify wallet addresses for KYC compliance without exposing user personal data.

Features

• ✅ Zero-Knowledge KYC Verification - Check wallet KYC status without accessing personal data
• 🔐 Full TypeScript Support - Complete type definitions with strict typing
• 📊 Rate Limit Monitoring - Built-in rate limit tracking and warnings
• 🛡️ AML Screening - Complete anti-money laundering compliance checks
• 🌍 Multi-Chain Support - Works with 190+ cryptocurrencies and blockchains
• 🔄 Robust Error Handling - Specific exception types for different error scenarios
• ⚡ Modern Async/Await - Promise-based API with native Node.js patterns
• 📦 Dual Module Support - Both ESM and CommonJS compatibility
• 🎯 Express.js Ready - Middleware examples for web applications

Installation

Install via npm:

npm install verifyo-node-sdk

Requirements

• Node.js 14.0.0 or higher
• TypeScript 5.0+ (for TypeScript projects)

Quick Start

TypeScript

import { VerifyoClient } from 'verifyo-node-sdk';

// Initialize client with your API key
const client = new VerifyoClient('vfy_sk_your_api_key_here');

try {
  // Check KYC status for a wallet address
  const response = await client.checkAddress('0x742d35Cc6634C0532925a3b8D89B0E5C9a7c9f35');
  
  if (response.hasResults) {
    const verification = response.firstResult;
    
    if (verification.isVerified && verification.ageOver18) {
      console.log('✅ User is KYC verified and over 18');
      console.log(`KYC Level: ${verification.kycLevel}`);
      console.log(`Document Country: ${verification.documentCountry}`);
    } else {
      console.log('❌ User does not meet requirements');
    }
  } else {
    console.log('❌ No KYC verification found for this address');
  }
  
} catch (error) {
  console.error('Error:', error.message);
}

JavaScript (CommonJS)

const { VerifyoClient } = require('verifyo-node-sdk');

async function checkKyc() {
  const client = new VerifyoClient('vfy_sk_your_api_key_here');
  
  try {
    const response = await client.checkAddress('0x742d35Cc6634C0532925a3b8D89B0E5C9a7c9f35');
    
    if (response.hasResults) {
      const verification = response.firstResult;
      console.log(`KYC Status: ${verification.kycStatus}`);
      console.log(`Meets Requirements: ${verification.meetsBasicRequirements}`);
    }
  } catch (error) {
    console.error('KYC check failed:', error.message);
  }
}

checkKyc();

Authentication

Get your API keys from the Verifyo Dashboard:

1. Public Key (vfy_pk_*) - For frontend SDK (not used in Node.js SDK)
2. Secret Key (vfy_sk_*) - For backend API calls (use this in Node.js SDK)

⚠️ Keep your secret key secure - Never expose it in frontend code or commit to version control.

API Reference

VerifyoClient

Constructor

const client = new VerifyoClient(apiKey: string, options?: ClientOptions);

Parameters:

• apiKey - Your Verifyo secret API key (starts with vfy_sk_)
• options - Optional configuration:
  • baseUrl - API base URL (default: https://api.verifyo.com)
  • timeout - Request timeout in milliseconds (default: 30000)
  • debug - Enable debug logging (default: false)

Methods

checkAddress(address: string, network?: string): Promise

Check KYC verification status for a wallet address.

Parameters:

• address - Wallet address to check (required)
• network - Blockchain network identifier (optional, e.g., 'ethereum', 'bitcoin')

Returns: Promise resolving to CheckResponse object

Response Models

CheckResponse

Main response wrapper containing verification results and rate limit information.

// Properties
response.hasResults: boolean                     // Check if any results found
response.results: VerificationResult[]          // All verification results
response.firstResult: VerificationResult | null // First result (most common)
response.resultCount: number                     // Number of results
response.hasVerifiedResult: boolean              // Check if any verified results
response.verifiedResults: VerificationResult[]  // Only verified results
response.rateLimitInfo?: RateLimitInfo          // Rate limit information
response.isApproachingRateLimit: boolean        // Check if near limit

VerificationResult

Individual KYC verification result for a wallet address.

// Basic verification info
result.zkKycToken: string              // Zero-knowledge proof token
result.identity: string                // User identity/email
result.kycLevel: number                // KYC level (0-3)
result.kycStatus: string              // "verified" or "not_verified"
result.isVerified: boolean            // Quick verification check

// Geographic information  
result.documentCountry: string | null  // Document issuing country
result.residenceCountry: string | null // Residence country

// Age verification
result.ageOver18: boolean             // Age 18+ verification
result.ageOver21: boolean             // Age 21+ verification

// Wallet and AML data
result.wallet: WalletInfo             // Wallet information
result.aml: AmlScreening              // AML screening results

// Convenience getters
result.meetsBasicRequirements: boolean                // Verified + 18+ + AML clean + safe wallet
result.isSuitableForAgeRestrictedServices: boolean   // Above + 21+

WalletInfo

Wallet-specific information and risk assessment.

wallet.address: string                        // Wallet address
wallet.ownershipStatus: string               // "verified", "self_declared", "not_found"
wallet.isOwnershipVerified: boolean          // Cryptographic ownership proof
wallet.sanctioned: boolean                   // Wallet on sanctions lists
wallet.highRisk: boolean                     // High-risk wallet flag
wallet.isSafeToInteract: boolean             // Not sanctioned + not high risk

AmlScreening

Anti-Money Laundering screening results.

aml.sanctioned: boolean                 // On government sanctions lists
aml.pep: boolean                        // Politically Exposed Person
aml.criminal: boolean                   // Criminal convictions
aml.barred: boolean                     // Barred from financial services
aml.military: boolean                   // Military organization connections
aml.adverseMedia: boolean               // Negative media coverage
aml.passesAmlScreening: boolean         // Passes all AML checks

Error Handling

The SDK provides specific exception classes for different error types:

import { 
  VerifyoClient,
  AuthenticationException,
  RateLimitException,
  ApiException,
  NetworkException 
} from 'verifyo-node-sdk';

const client = new VerifyoClient('vfy_sk_your_key');

try {
  const response = await client.checkAddress(address);
  // Process response...
  
} catch (error) {
  if (error instanceof AuthenticationException) {
    // Invalid API key - check configuration
    console.error('Authentication failed:', error.message);
    
  } else if (error instanceof RateLimitException) {
    // Rate limit exceeded - implement backoff or upgrade plan
    console.error('Rate limit exceeded:', error.message);
    console.error('Usage:', error.getUsageInfo());
    
  } else if (error instanceof ApiException) {
    // API error - log and handle gracefully
    console.error('API error:', error.message);
    console.error('Status code:', error.statusCode);
    
  } else if (error instanceof NetworkException) {
    // Network issue - retry with exponential backoff
    console.error('Network error:', error.message);
    
  } else {
    // Unexpected error - log and fail safe
    console.error('Unexpected error:', error.message);
  }
}

Rate Limiting

The API enforces rate limits based on your plan:

• Unauthenticated: 10 requests per 24 hours
• Free Account: 30 requests per month
• With MTO Tokens: Up to 1,000,000 requests per month

const response = await client.checkAddress(address);
const rateLimitInfo = response.rateLimitInfo;

if (rateLimitInfo) {
  console.log(`Used: ${rateLimitInfo.used}/${rateLimitInfo.limit}`);
  console.log(`Remaining: ${rateLimitInfo.remaining}`);
  console.log(`Tier: ${rateLimitInfo.tier}`);
  
  if (rateLimitInfo.isNearLimit) {
    console.warn('⚠️ Approaching rate limit!');
  }
}

Common Use Cases

Express.js Middleware

import express from 'express';
import { VerifyoClient, RateLimitException } from 'verifyo-node-sdk';

const app = express();
const kycClient = new VerifyoClient(process.env.VERIFYO_API_KEY!);

// KYC verification middleware
const verifyKyc = (minLevel: number = 1) => {
  return async (req: express.Request, res: express.Response, next: express.NextFunction) => {
    try {
      const { walletAddress } = req.body;
      const response = await kycClient.checkAddress(walletAddress);
      
      if (response.hasResults && response.firstResult.meetsBasicRequirements) {
        req.kycVerification = response.firstResult;
        next();
      } else {
        res.status(403).json({ error: 'KYC verification required' });
      }
    } catch (error) {
      if (error instanceof RateLimitException) {
        res.status(429).json({ error: 'Rate limit exceeded' });
      } else {
        res.status(500).json({ error: 'KYC verification failed' });
      }
    }
  };
};

// Use the middleware
app.post('/api/trade', verifyKyc(1), (req, res) => {
  res.json({ message: 'Trading allowed', user: req.kycVerification });
});

Exchange Onboarding

async function canUserTrade(walletAddress: string): Promise<boolean> {
  const client = new VerifyoClient(process.env.VERIFYO_API_KEY!);
  
  try {
    const response = await client.checkAddress(walletAddress);
    
    if (!response.hasResults) {
      return false; // No KYC found
    }
    
    const verification = response.firstResult;
    
    // Check minimum requirements for trading
    return (
      verification.isVerified &&
      verification.ageOver18 &&
      verification.kycLevel >= 1 &&
      verification.aml.passesAmlScreening &&
      verification.wallet.isSafeToInteract
    );
    
  } catch (error) {
    console.error('KYC check failed:', error.message);
    return false; // Fail safe - deny access on errors
  }
}

Age-Restricted Services

interface AgeVerificationResult {
  allowed: boolean;
  reason?: string;
  kycLevel?: number;
  documentCountry?: string;
}

async function canAccessAgeRestrictedContent(walletAddress: string): Promise<AgeVerificationResult> {
  const client = new VerifyoClient(process.env.VERIFYO_API_KEY!);
  
  try {
    const response = await client.checkAddress(walletAddress);
    
    if (!response.hasResults) {
      return { allowed: false, reason: 'No KYC verification found' };
    }
    
    const verification = response.firstResult;
    
    if (!verification.isVerified) {
      return { allowed: false, reason: 'KYC verification required' };
    }
    
    if (!verification.ageOver21) {
      return { allowed: false, reason: 'Must be 21 years or older' };
    }
    
    if (!verification.aml.passesAmlScreening) {
      return { allowed: false, reason: 'Failed compliance screening' };
    }
    
    return {
      allowed: true,
      kycLevel: verification.kycLevel,
      documentCountry: verification.documentCountry ?? undefined,
    };
    
  } catch (error) {
    console.error('Age verification failed:', error.message);
    return { allowed: false, reason: 'Verification service unavailable' };
  }
}

Configuration

Environment Variables

# .env file
VERIFYO_API_KEY=vfy_sk_your_secret_key_here

import { VerifyoClient } from 'verifyo-node-sdk';

const client = new VerifyoClient(process.env.VERIFYO_API_KEY!);

Advanced Configuration

const client = new VerifyoClient('vfy_sk_your_api_key_here', {
  timeout: 60000,                         // 60 second timeout
  debug: true,                           // Enable debug logging
  baseUrl: 'https://api.verifyo.com'     // Custom API endpoint
});

Development

Building the SDK

# Install dependencies
npm install

# Build for production
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type checking
npm run type-check

# Linting
npm run lint

# Formatting
npm run format

Module Formats

The SDK is built to support both module systems:

// ESM (import)
import { VerifyoClient } from 'verifyo-node-sdk';

// CommonJS (require)
const { VerifyoClient } = require('verifyo-node-sdk');

Testing

The SDK includes comprehensive tests:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

Examples

Check the examples/ directory for complete working examples:

• basic-check.js - Simple KYC verification in JavaScript
• typescript-example.ts - Type-safe TypeScript usage
• express-middleware.js - Express.js middleware integration

Support

• Documentation: https://verifyo.com/docs
• Issues: GitHub Issues
• Email: [email protected]

License

This SDK is open-sourced software licensed under the MIT license.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Made with ❤️ by the Verifyo Team

For more information about Verifyo's Zero-Knowledge KYC platform, visit verifyo.com.