Verifyo.SDK 1.0.0

Verifyo .NET SDK

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

Features

• ✅ Zero-Knowledge Verification - Check KYC status without accessing personal data
• 🔒 Type-Safe - Full C# type safety with nullable reference types
• ⚡ Async/Await - Modern async APIs for high-performance applications
• 🛡️ Comprehensive Error Handling - Specific exception types for different errors
• 📊 Rate Limit Monitoring - Built-in rate limit tracking and warnings
• 🎯 Multi-Target - Supports .NET 6.0 and .NET 8.0

Installation

Install via NuGet Package Manager:

dotnet add package Verifyo.SDK

Or via Package Manager Console:

Install-Package Verifyo.SDK

Or add to your .csproj file:

<PackageReference Include="Verifyo.SDK" Version="1.0.0" />

Quick Start

using Verifyo.SDK;
using Verifyo.SDK.Models;

// Initialize the client
var client = new VerifyoClient("vfy_sk_your_api_key");

// Check a wallet address
var response = await client.CheckAddressAsync("0x742d35...", "ethereum");

if (response.HasResults())
{
    var verification = response.GetFirstResult();
    
    if (verification.MeetsBasicRequirements())
    {
        Console.WriteLine("✅ User is KYC verified");
        Console.WriteLine($"KYC Level: {verification.KycLevel}");
        Console.WriteLine($"Country: {verification.DocumentCountry}");
    }
}

Configuration

// With custom configuration
var options = new VerifyoClientOptions(
    BaseUrl: "https://api.verifyo.com",  // Optional: custom API endpoint
    Timeout: TimeSpan.FromSeconds(60),   // Optional: custom timeout
    Debug: true                           // Optional: enable debug logging
);

var client = new VerifyoClient("vfy_sk_your_api_key", options);

API Methods

CheckAddressAsync

Check KYC verification status for a wallet address:

// Check with network specification
var response = await client.CheckAddressAsync(
    address: "0x742d35...",
    network: "ethereum",
    cancellationToken: cancellationToken
);

// Check without network (auto-detection)
var response = await client.CheckAddressAsync("3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy");

Response Structure

CheckResponse

The main response wrapper:

if (response.HasResults())
{
    Console.WriteLine($"Found {response.ResultCount()} verification(s)");
    
    foreach (var result in response.Results)
    {
        // Process each verification
    }
}

// Check rate limits
if (response.RateLimitInfo != null)
{
    Console.WriteLine($"API Usage: {response.RateLimitInfo.Used}/{response.RateLimitInfo.Limit}");
    
    if (response.RateLimitInfo.IsNearLimit())
    {
        Console.WriteLine("⚠️ Approaching rate limit!");
    }
}

VerificationResult

Individual verification details:

var verification = response.GetFirstResult();

// Basic properties
Console.WriteLine($"Status: {verification.KycStatus}");
Console.WriteLine($"Level: {verification.KycLevel}");
Console.WriteLine($"Country: {verification.DocumentCountry ?? "Not provided"}");

// Age verification
Console.WriteLine($"Over 18: {verification.AgeOver18}");
Console.WriteLine($"Over 21: {verification.AgeOver21}");

// Convenience methods
if (verification.IsVerified())
{
    Console.WriteLine("User has completed KYC");
}

if (verification.MeetsBasicRequirements())
{
    // User is verified, 18+, passes AML, and wallet is safe
    Console.WriteLine("User meets all basic compliance requirements");
}

Wallet Information

var wallet = verification.Wallet;

Console.WriteLine($"Address: {wallet.Address}");
Console.WriteLine($"Ownership: {wallet.OwnershipStatus}");
Console.WriteLine($"Sanctioned: {wallet.Sanctioned}");
Console.WriteLine($"High Risk: {wallet.HighRisk}");

if (wallet.IsSafeToInteract())
{
    Console.WriteLine("✅ Wallet is safe for transactions");
}

AML Screening

var aml = verification.Aml;

Console.WriteLine($"Sanctioned: {aml.Sanctioned}");
Console.WriteLine($"PEP: {aml.Pep}");
Console.WriteLine($"Criminal: {aml.Criminal}");
Console.WriteLine($"Adverse Media: {aml.AdverseMedia}");

if (aml.PassesAmlScreening())
{
    Console.WriteLine("✅ Passes all AML checks");
}

Error Handling

The SDK provides specific exception types for different error scenarios:

try
{
    var response = await client.CheckAddressAsync(address);
}
catch (AuthenticationException ex)
{
    // Invalid API key or authentication failure
    Console.WriteLine($"Authentication failed: {ex.Message}");
}
catch (RateLimitException ex)
{
    // Rate limit exceeded
    Console.WriteLine($"Rate limit exceeded. Usage: {ex.Used}/{ex.Limit}");
    Console.WriteLine($"Tier: {ex.Tier}");
    if (ex.ResetsAt != null)
    {
        Console.WriteLine($"Resets at: {ex.ResetsAt}");
    }
}
catch (ApiException ex)
{
    // General API error
    Console.WriteLine($"API error (HTTP {ex.StatusCode}): {ex.Message}");
}
catch (NetworkException ex)
{
    // Network connectivity issues
    Console.WriteLine($"Network error: {ex.Message}");
}

Examples

Exchange Integration

public async Task<bool> CanUserTrade(string walletAddress)
{
    try
    {
        var response = await _verifyoClient.CheckAddressAsync(walletAddress);
        
        if (!response.HasResults())
        {
            // No KYC found
            return false;
        }
        
        var verification = response.GetFirstResult();
        
        // Check trading requirements
        return verification.IsVerified() 
            && verification.AgeOver18 
            && verification.Aml.PassesAmlScreening()
            && verification.Wallet.IsSafeToInteract();
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Error checking KYC status");
        return false; // Fail-safe: deny access on error
    }
}

Age-Restricted Services

public async Task<bool> CanAccessGamblingServices(string walletAddress)
{
    var response = await _verifyoClient.CheckAddressAsync(walletAddress);
    
    if (!response.HasResults())
    {
        return false;
    }
    
    var verification = response.GetFirstResult();
    
    // Most gambling services require 21+
    return verification.IsVerified() 
        && verification.AgeOver21
        && !verification.Aml.Barred;
}

Compliance Reporting

public async Task<List<ComplianceReport>> GenerateComplianceReports(List<string> addresses)
{
    var reports = new List<ComplianceReport>();
    
    foreach (var address in addresses)
    {
        try
        {
            var response = await _verifyoClient.CheckAddressAsync(address);
            
            reports.Add(new ComplianceReport
            {
                Address = address,
                HasKyc = response.HasResults(),
                KycLevel = response.GetFirstResult()?.KycLevel ?? 0,
                PassesAml = response.GetFirstResult()?.Aml.PassesAmlScreening() ?? false,
                Country = response.GetFirstResult()?.DocumentCountry
            });
        }
        catch (RateLimitException)
        {
            // Handle rate limiting gracefully
            await Task.Delay(TimeSpan.FromSeconds(10));
        }
    }
    
    return reports;
}

ASP.NET Core Integration

// In Program.cs or Startup.cs
builder.Services.AddSingleton<VerifyoClient>(provider =>
{
    var configuration = provider.GetRequiredService<IConfiguration>();
    var apiKey = configuration["Verifyo:ApiKey"];
    
    var options = new VerifyoClientOptions(
        Debug: builder.Environment.IsDevelopment()
    );
    
    return new VerifyoClient(apiKey, options);
});

// In your controller
[ApiController]
[Route("api/[controller]")]
public class VerificationController : ControllerBase
{
    private readonly VerifyoClient _verifyoClient;
    
    public VerificationController(VerifyoClient verifyoClient)
    {
        _verifyoClient = verifyoClient;
    }
    
    [HttpGet("check/{address}")]
    public async Task<IActionResult> CheckAddress(string address)
    {
        try
        {
            var response = await _verifyoClient.CheckAddressAsync(address);
            return Ok(response);
        }
        catch (AuthenticationException)
        {
            return Unauthorized("Invalid API credentials");
        }
        catch (RateLimitException ex)
        {
            Response.Headers.Add("X-RateLimit-Limit", ex.Limit.ToString());
            Response.Headers.Add("X-RateLimit-Remaining", ex.Remaining.ToString());
            return StatusCode(429, "Rate limit exceeded");
        }
    }
}

Thread Safety

The VerifyoClient class is thread-safe and can be used as a singleton in your application. It's recommended to create a single instance and reuse it throughout your application's lifetime.

Best Practices

1. Use a Single Client Instance: Create one VerifyoClient instance and reuse it
2. Handle Rate Limits: Implement exponential backoff when hitting rate limits
3. Fail-Safe: Always deny access when verification fails or errors occur
4. Monitor Usage: Check RateLimitInfo to avoid hitting limits
5. Use Cancellation Tokens: Pass cancellation tokens for proper request cancellation
6. Log Errors: Log all exceptions for debugging and monitoring

Requirements

• .NET 6.0 or .NET 8.0
• Valid Verifyo API key (starting with vfy_sk_)

Support

• Documentation: https://verifyo.com/docs
• Email: support@verifyo.com
• GitHub Issues: https://github.com/verifyo-dot-com/verifyo-dotnet-sdk/issues

License

MIT License - see LICENSE file for details