README

Official PHP 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
🔐 Secure Authentication - API key-based authentication with automatic error handling
📊 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 - Comprehensive exception handling for production use
📱 Type-Safe - Full PHP 7.4+ type declarations and IDE support

Installation

Install via Composer:

composer require verifyo/php-sdk

Requirements

PHP 7.4 or higher
Guzzle HTTP client (automatically installed)
Valid Verifyo API key

Quick Start

<?php

require_once 'vendor/autoload.php';

use Verifyo\SDK\VerifyoClient;

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

try {
    // Check KYC status for a wallet address
    $response = $client->checkAddress('0x742d35Cc6634C0532925a3b8D89B0E5C9a7c9f35');
    
    if ($response->hasResults()) {
        $verification = $response->getFirstResult();
        
        if ($verification->isVerified() && $verification->isAgeOver18()) {
            echo "✅ User is KYC verified and over 18";
            echo "KYC Level: " . $verification->getKycLevel();
            echo "Document Country: " . $verification->getDocumentCountry();
        } else {
            echo "❌ User does not meet requirements";
        }
    } else {
        echo "❌ No KYC verification found for this address";
    }
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

Authentication

Get your API keys from the Verifyo Dashboard:

Public Key (vfy_pk_*) - For frontend SDK (not used in PHP SDK)
Secret Key (vfy_sk_*) - For backend API calls (use this in PHP SDK)

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

API Reference

VerifyoClient

Constructor

$client = new VerifyoClient(string $apiKey, array $options = [])

Parameters:

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

Methods

checkAddress(string $address, ?string $network = null): CheckResponse

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: CheckResponse object containing verification results

Throws:

AuthenticationException - Invalid API key (401)
RateLimitException - Rate limit exceeded (429)
ApiException - General API errors
NetworkException - Network connectivity issues

Response Models

CheckResponse

Main response wrapper containing verification results and rate limit information.

// Check if any results found
$response->hasResults(): bool

// Get all results
$response->getResults(): VerificationResult[]

// Get first result (most common use case)
$response->getFirstResult(): ?VerificationResult

// Get number of results
$response->getResultCount(): int

// Check if any verified results
$response->hasVerifiedResult(): bool

// Get only verified results
$response->getVerifiedResults(): VerificationResult[]

// Get rate limit info
$response->getRateLimitInfo(): ?RateLimitInfo

// Check if approaching rate limit
$response->isApproachingRateLimit(): bool

VerificationResult

Individual KYC verification result for a wallet address.

// Basic verification info
$result->getZkKycToken(): string           // Zero-knowledge proof token
$result->getIdentity(): string             // User identity/email
$result->getKycLevel(): int                // KYC level (0-3)
$result->getKycStatus(): string            // "verified" or "not_verified"
$result->isVerified(): bool                // Quick verification check

// Geographic information
$result->getDocumentCountry(): ?string     // Document issuing country
$result->getResidenceCountry(): ?string    // Residence country

// Age verification
$result->isAgeOver18(): bool               // Age 18+ verification
$result->isAgeOver21(): bool               // Age 21+ verification

// Wallet and AML data
$result->getWallet(): WalletInfo           // Wallet information
$result->getAml(): AmlScreening            // AML screening results

// Convenience methods
$result->meetsBasicRequirements(): bool    // Verified + 18+ + AML clean + safe wallet
$result->isSuitableForAgeRestrictedServices(): bool // Above + 21+

WalletInfo

Wallet-specific information and risk assessment.

$wallet->getAddress(): string              // Wallet address
$wallet->getOwnershipStatus(): string      // "verified", "self_declared", "not_found"
$wallet->isOwnershipVerified(): bool       // Cryptographic ownership proof
$wallet->isSanctioned(): bool              // Wallet on sanctions lists
$wallet->isHighRisk(): bool                // High-risk wallet flag
$wallet->isSafeToInteract(): bool          // Not sanctioned + not high risk

AmlScreening

Anti-Money Laundering screening results.

$aml->isSanctioned(): bool                 // On government sanctions lists
$aml->isPep(): bool                        // Politically Exposed Person
$aml->hasCriminalRecord(): bool            // Criminal convictions
$aml->isBarred(): bool                     // Barred from financial services
$aml->hasMilitaryConnections(): bool       // Military organization connections
$aml->hasAdverseMedia(): bool              // Negative media coverage
$aml->passesAmlScreening(): bool           // Passes all AML checks

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

Rate limit information is included in every response:

$rateLimitInfo = $response->getRateLimitInfo();

if ($rateLimitInfo) {
    echo "Used: " . $rateLimitInfo->getUsed() . "/" . $rateLimitInfo->getLimit();
    echo "Remaining: " . $rateLimitInfo->getRemaining();
    echo "Tier: " . $rateLimitInfo->getTier();
    
    if ($rateLimitInfo->isNearLimit()) {
        echo "⚠️ Approaching rate limit!";
    }
}

Error Handling

The SDK provides specific exceptions for different error types:

use Verifyo\SDK\Exceptions\AuthenticationException;
use Verifyo\SDK\Exceptions\RateLimitException;
use Verifyo\SDK\Exceptions\ApiException;
use Verifyo\SDK\Exceptions\NetworkException;

try {
    $response = $client->checkAddress($address);
    // Process response...
    
} catch (AuthenticationException $e) {
    // Invalid API key - check configuration
    echo "Authentication failed: " . $e->getMessage();
    
} catch (RateLimitException $e) {
    // Rate limit exceeded - implement backoff or upgrade plan
    echo "Rate limit exceeded: " . $e->getMessage();
    echo "Usage: " . $e->getUsed() . "/" . $e->getLimit();
    
} catch (ApiException $e) {
    // API error - log and handle gracefully
    echo "API error: " . $e->getMessage();
    echo "Status code: " . $e->getStatusCode();
    
} catch (NetworkException $e) {
    // Network issue - retry with exponential backoff
    echo "Network error: " . $e->getMessage();
    
} catch (Exception $e) {
    // Unexpected error - log and fail safe
    echo "Unexpected error: " . $e->getMessage();
}

Common Use Cases

Exchange Onboarding

function canUserTrade(string $walletAddress): bool
{
    $client = new VerifyoClient($_ENV['VERIFYO_API_KEY']);
    
    try {
        $response = $client->checkAddress($walletAddress);
        
        if (!$response->hasResults()) {
            return false; // No KYC found
        }
        
        $verification = $response->getFirstResult();
        
        // Check minimum requirements for trading
        return $verification->isVerified()
            && $verification->isAgeOver18()
            && $verification->getKycLevel() >= 1
            && $verification->getAml()->passesAmlScreening()
            && $verification->getWallet()->isSafeToInteract();
            
    } catch (Exception $e) {
        error_log("KYC check failed: " . $e->getMessage());
        return false; // Fail safe - deny access on errors
    }
}

Age-Restricted Services

function canAccessAgeRestrictedContent(string $walletAddress): array
{
    $client = new VerifyoClient($_ENV['VERIFYO_API_KEY']);
    
    try {
        $response = $client->checkAddress($walletAddress);
        
        if (!$response->hasResults()) {
            return ['allowed' => false, 'reason' => 'No KYC verification found'];
        }
        
        $verification = $response->getFirstResult();
        
        if (!$verification->isVerified()) {
            return ['allowed' => false, 'reason' => 'KYC verification required'];
        }
        
        if (!$verification->isAgeOver21()) {
            return ['allowed' => false, 'reason' => 'Must be 21 years or older'];
        }
        
        if (!$verification->getAml()->passesAmlScreening()) {
            return ['allowed' => false, 'reason' => 'Failed compliance screening'];
        }
        
        return [
            'allowed' => true,
            'kyc_level' => $verification->getKycLevel(),
            'document_country' => $verification->getDocumentCountry()
        ];
        
    } catch (Exception $e) {
        error_log("Age verification failed: " . $e->getMessage());
        return ['allowed' => false, 'reason' => 'Verification service unavailable'];
    }
}

Configuration

Environment Variables

# .env file
VERIFYO_API_KEY=vfy_sk_your_secret_key_here

Advanced Configuration

$client = new VerifyoClient('vfy_sk_your_api_key_here', [
    'timeout' => 60,                    // 60 second timeout
    'debug' => true,                    // Enable debug logging
    'base_url' => 'https://api.verifyo.com' // Custom API endpoint
]);

Development

Running Tests

# Install dev dependencies
composer install

# Run tests
composer test

# Run static analysis
composer analyse

# Check code style
composer cs-check

# Fix code style
composer cs-fix

Debug Mode

Enable debug mode to log API requests and responses:

$client = new VerifyoClient('vfy_sk_your_key', ['debug' => true]);

// Or enable later
$client->setDebugMode(true);

Support

Documentation: https://verifyo.com/docs
Issues: GitHub Issues
Email: developers@verifyo.com

License

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

Security

If you discover any security related issues, please email security@verifyo.com 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.

verifyo / php-sdk

Maintainers

Details