Skip to main content

​
Overview

Cryptocurrency wallet addresses can be checked against sanctions lists to ensure compliance and prevent transactions with blocked entities. This guide shows you how to validate wallet addresses using the KYC API.

​
Quick Example

You can check wallets using either wallet_address (simpler) or the identifiers array (more flexible): 
import requests

url = "https://stg.kyc.legaltalent.ai/kyc"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}

# Method 1: Using wallet_address (recommended for single wallet)
payload = {
    "subject": {
        "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
    },
    "list_name": "ofac"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

if data.get("result", {}).get("is_match"):
    print("Wallet found in sanctions list!")
    print(f"Matches: {data['result']['match_count']}")
else:
    print("Wallet is clear")

# Method 2: Using identifiers array (useful for multiple identifiers)
payload = {
    "subject": {
        "identifiers": [
            {
                "type": "Ethereum Wallet",
                "value": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
            }
        ]
    },
    "list_name": "ofac"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
Note on wallet format:
  • For /kyc endpoint: Use wallet_address directly (simpler) or identifiers array (if you need multiple identifiers)
  • For watchlists: Always use identifier with identifier_type: "wallet" (see watchlist examples below)

​
Available Lists for Crypto Wallets

The API supports validation against specialized lists for cryptocurrency wallets:
List NameDescriptionFocus Area
ofacOFAC Sanctions ListUS Treasury sanctions, includes crypto addresses
nbctfNBCTF (Israel Counter Terror Financing)Israel’s list of wallets linked to terrorism financing
crypto_scamCrypto Scam ListKnown scam wallets and fraudulent addresses
unUN Security Council SanctionsInternational sanctions, includes crypto entities
euEU Consolidated Financial SanctionsEuropean Union sanctions list

​
Supported Wallet Types

The API supports validation of various cryptocurrency wallet addresses:
Wallet TypeExampleNotes
Ethereum0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbEVM-compatible chains (ETH, BSC, Polygon, etc.)
Bitcoin1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNaLegacy and Segwit addresses
TronVarious formatsTRX addresses
Other CryptoVarious formatsSupport depends on list data

​
Common Use Cases

​
1. Validate Before Transaction

Check wallets before allowing deposits or withdrawals: 
def validate_wallet_before_transaction(wallet_address, token):
    """Validate wallet before processing transaction"""
    url = "https://stg.kyc.legaltalent.ai/kyc"
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    }
    
    # Check against crypto-specific lists
    payload = {
        "subject": {
            "wallet_address": wallet_address
        },
        "lists": ["ofac", "nbctf", "crypto_scam"]
    }
    
    response = requests.post(url, json=payload, headers=headers)
    data = response.json()
    
    if data.get("summary", {}).get("has_any_match"):
        raise ValueError("Wallet is blocked - transaction rejected")
    
    return True

# Usage
try:
    validate_wallet_before_transaction(
        "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "YOUR_TOKEN"
    )
    print("Transaction approved")
except ValueError as e:
    print(f"Transaction blocked: {e}")

​
2. Batch Validation

Validate multiple wallets efficiently: 
def validate_wallet_batch(wallet_addresses, token):
    """Validate multiple wallets"""
    url = "https://stg.kyc.legaltalent.ai/kyc"
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    }
    
    results = {}
    
    for wallet in wallet_addresses:
        payload = {
            "subject": {
                "wallet_address": wallet
            },
            "list_name": "nbctf"  # Check against Israel's crypto list
        }
        
        response = requests.post(url, json=payload, headers=headers)
        data = response.json()
        
        results[wallet] = {
            "is_match": data.get("result", {}).get("is_match", False),
            "match_count": data.get("result", {}).get("match_count", 0)
        }
    
    return results

# Usage
wallets = [
    "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "0x8ba1f109551bD432803012645Hac136c23C09E116"
]

results = validate_wallet_batch(wallets, "YOUR_TOKEN")
for wallet, result in results.items():
    status = "BLOCKED" if result["is_match"] else "CLEAR"
    print(f"{wallet[:20]}... : {status}")

​
3. Monitor Wallets in Watchlists

Add wallets to watchlists for ongoing monitoring: 
import requests

# Create a watchlist for crypto wallets
watchlist_url = "https://stg.kyc.legaltalent.ai/kyc/watchlists"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}

# Create watchlist monitoring crypto-specific lists
watchlist_payload = {
    "name": "Monitored Crypto Wallets",
    "check_frequency": "daily",
    "lists_to_monitor": ["ofac", "nbctf", "crypto_scam"],
    "status": "active"
}

response = requests.post(watchlist_url, json=watchlist_payload, headers=headers)
watchlist_data = response.json()
watchlist_id = watchlist_data["data"]["watchlist_id"]

# Add wallets to watchlist
add_subjects_url = f"{watchlist_url}/{watchlist_id}/subjects/batch"
subjects_payload = {
    "subjects": [
        {
            "full_name": "Ethereum Wallet 1",
            "identifier": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
            "identifier_type": "wallet"
        },
        {
            "full_name": "Bitcoin Wallet 1",
            "identifier": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
            "identifier_type": "wallet"
        }
    ]
}

response = requests.post(add_subjects_url, json=subjects_payload, headers=headers)
print(f"Watchlist created: {watchlist_id}")
print("Wallets added for daily monitoring")

​
Error Handling

Always implement proper error handling for production use: 
import requests

def validate_wallet_safe(wallet_address, token):
    """Validate wallet with comprehensive error handling"""
    url = "https://stg.kyc.legaltalent.ai/kyc"
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "subject": {
            "wallet_address": wallet_address
        },
        "list_name": "crypto_scam"  # Check against crypto scam list
    }
    
    try:
        response = requests.post(url, json=payload, headers=headers, timeout=10)
        response.raise_for_status()
        data = response.json()
        
        if response.status_code == 200:
            return {
                "success": True,
                "is_match": data.get("result", {}).get("is_match", False),
                "match_count": data.get("result", {}).get("match_count", 0)
            }
        else:
            return {
                "success": False,
                "error": f"API returned status {response.status_code}"
            }
            
    except requests.exceptions.Timeout:
        return {"success": False, "error": "Request timeout"}
    except requests.exceptions.ConnectionError:
        return {"success": False, "error": "Connection error"}
    except requests.exceptions.HTTPError as e:
        return {"success": False, "error": f"HTTP error: {e}"}
    except Exception as e:
        return {"success": False, "error": f"Unexpected error: {e}"}

# Usage
result = validate_wallet_safe("0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "YOUR_TOKEN")
if result["success"]:
    print(f"Match found: {result['is_match']}")
else:
    print(f"Error: {result['error']}")

​
Best Practices

  1. Validate Before Critical Operations: Always check wallets before processing high-value transactions
  2. Use Crypto-Specific Lists: Check against specialized lists like nbctf (Israel crypto list), crypto_scam (scam wallets), and ofac (US sanctions)
  3. Check Multiple Lists: Use lists parameter to check against multiple lists simultaneously for comprehensive coverage
  4. Monitor Continuously: Use watchlists for ongoing monitoring of wallets
  5. Handle Errors Gracefully: Implement retry logic and proper error handling for production systems
  6. Respect Rate Limits: The API has rate limits (1,000 requests per 5 minutes per IP). See API Overview for details

​
Next Steps

  1. Get your API credentials if you haven’t already
  2. Try the quick example above with your own wallet addresses
  3. Set up a watchlist for automated monitoring
  4. Implement validation in your transaction processing pipeline