Integration Guide

1. Prerequisites

• •Node.js 18+ or Python 3.9+ (for backend integration)
• •Solidity 0.8+ (for smart contract integration)
• •Veria account with API key (get one here)
• •Basic understanding of REST APIs

2. Get Your API Key

After signing up at veria.cc/choose-plan, you'll receive two API keys:

test_veria_abc123def456ghi789

prod_veria_xyz987wvu654tsr321

3. First API Call

Test your API key with a simple compliance check:

curl https://api.veria.cc/v1/compliance/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "amount": 1000,
    "currency": "USDC",
    "protocol": "your-protocol",
    "chain": "ethereum"
  }'

{
  "decision": "APPROVED",
  "riskScore": 15,
  "riskLevel": "LOW",
  "processingTime": 87
}

Endpoint

Request Schema

{
  "wallet": "string",           // Required: Ethereum address (0x...)
  "amount": number,             // Required: Transaction amount
  "currency": "string",         // Required: USDC, ETH, BTC, etc.
  "protocol": "string",         // Required: Your protocol identifier
  "chain": "string",            // Required: ethereum, polygon, arbitrum, etc.
  "metadata": {                 // Optional: Additional context
    "txType": "string",         // deposit, withdrawal, trade, etc.
    "userKYC": boolean,         // User KYC status
    "ipAddress": "string",      // User IP (for geo-blocking)
    "userId": "string"          // Your internal user ID
  }
}

Response Schema

{
  "decision": "APPROVED" | "REJECTED" | "REVIEW",
  "riskScore": number,          // 0-100 (lower is safer)
  "riskLevel": "LOW" | "MEDIUM" | "HIGH" | "CRITICAL",
  "checks": {
    "sanctionsCheck": {
      "passed": boolean,
      "lists": ["OFAC", "EU", "UN"],
      "matches": []             // If sanctioned
    },
    "walletAnalysis": {
      "risk": "LOW" | "MEDIUM" | "HIGH",
      "score": number,
      "flags": string[]         // mixer, darknet, etc.
    },
    "travelRule": {
      "required": boolean,
      "threshold": number
    }
  },
  "attestation": {
    "id": "string",             // Unique attestation ID
    "hash": "string",           // Cryptographic proof
    "timestamp": "ISO 8601"
  },
  "processingTime": number      // Milliseconds
}

Error Codes

Installation

npm install @veria-protocol/sdk
# or
yarn add @veria-protocol/sdk

Basic Usage

import { VeriaClient } from '@veria-protocol/sdk'

// Initialize client
const veria = new VeriaClient({
  apiKey: process.env.VERIA_API_KEY,
  environment: 'production' // or 'test'
})

// Check compliance
async function checkWallet(wallet: string, amount: number) {
  try {
    const result = await veria.compliance.check({
      wallet,
      amount,
      currency: 'USDC',
      protocol: 'your-protocol',
      chain: 'ethereum',
      metadata: {
        txType: 'deposit',
        userKYC: true
      }
    })

    if (result.decision === 'APPROVED') {
      console.log('Transaction approved:', result.riskScore)
      return true
    } else if (result.decision === 'REJECTED') {
      console.log('Transaction rejected:', result.checks)
      return false
    } else {
      console.log('Manual review required')
      return null
    }
  } catch (error) {
    console.error('Compliance check failed:', error)
    throw error
  }
}

Using Fetch API (No SDK)

async function checkCompliance(wallet: string, amount: number) {
  const response = await fetch('https://api.veria.cc/v1/compliance/check', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.VERIA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      wallet,
      amount,
      currency: 'USDC',
      protocol: 'your-protocol',
      chain: 'ethereum'
    })
  })

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`)
  }

  return await response.json()
}

Installation

pip install veria-sdk
# or
poetry add veria-sdk

Basic Usage

from veria import VeriaClient
import os

# Initialize client
veria = VeriaClient(
    api_key=os.environ['VERIA_API_KEY'],
    environment='production'  # or 'test'
)

def check_wallet(wallet: str, amount: float) -> bool:
    """Check if wallet passes compliance."""
    result = veria.compliance.check(
        wallet=wallet,
        amount=amount,
        currency='USDC',
        protocol='your-protocol',
        chain='ethereum',
        metadata={
            'tx_type': 'deposit',
            'user_kyc': True
        }
    )

    if result['decision'] == 'APPROVED':
        print(f"Approved: Risk score {result['riskScore']}")
        return True
    elif result['decision'] == 'REJECTED':
        print(f"Rejected: {result['checks']}")
        return False
    else:
        print("Manual review required")
        return None

Using Requests Library (No SDK)

import requests
import os

def check_compliance(wallet: str, amount: float):
    response = requests.post(
        'https://api.veria.cc/v1/compliance/check',
        headers={
            'Authorization': f"Bearer {os.environ['VERIA_API_KEY']}",
            'Content-Type': 'application/json'
        },
        json={
            'wallet': wallet,
            'amount': amount,
            'currency': 'USDC',
            'protocol': 'your-protocol',
            'chain': 'ethereum'
        }
    )

    response.raise_for_status()
    return response.json()

Retry Logic with Exponential Backoff

async function checkWithRetry(
  wallet: string,
  amount: number,
  maxRetries = 3
) {
  let lastError: Error

  for (let i = 0; i < maxRetries; i++) {
    try {
      return await veria.compliance.check({
        wallet,
        amount,
        currency: 'USDC',
        protocol: 'your-protocol',
        chain: 'ethereum'
      })
    } catch (error: any) {
      lastError = error

      // Don't retry client errors (4xx)
      if (error.status >= 400 && error.status < 500) {
        throw error
      }

      // Exponential backoff: 1s, 2s, 4s
      const delay = Math.pow(2, i) * 1000
      console.log(`Retry ${i + 1}/${maxRetries} after ${delay}ms`)
      await new Promise(resolve => setTimeout(resolve, delay))
    }
  }

  throw lastError
}

Rate Limiting Best Practices

Operation limits by plan:

• •Sandbox: 100 operations/month (testnet only)
• •Professional: 10,000 operations/month
• •Scale: 100,000 operations/month
• •Protocol: 500,000 operations/month

Test Wallets

Production Checklist

Environment Variables

# .env.production
VERIA_API_KEY=prod_veria_xyz987wvu654tsr321
VERIA_ENVIRONMENT=production

# .env.development
VERIA_API_KEY=test_veria_abc123def456ghi789
VERIA_ENVIRONMENT=test

# Never commit .env files to git!
# Add to .gitignore:
.env*
!.env.example