Verify Wallets

Verify wallet addresses using Bitrank's blockchain intelligence services to assess risk and compliance factors before processing transactions.

Endpoint

POST https://api.trpcontinuum.com/trp/verify-wallets-bitrank

Authentication

Requires API key and secret key authentication.

Headers

Header	Type	Required	Description
x-api-key	string	Yes	Your API key for authentication
x-secret-key	string	Yes	Your secret key for authentication

Request Body

Field	Type	Required	Description
walletAddresses	array	Yes	List of wallet addresses to verify
networks	array	Yes	Corresponding networks for each address
verificationLevel	string	No	"basic", "standard", "enhanced" (default: "standard")
includeRiskFactors	boolean	No	Include detailed risk factor analysis (default: true)
includeCategoryDetails	boolean	No	Include detailed category information (default: true)
transactionContext	object	No	Additional context for verification

Transaction Context Object

Field	Type	Required	Description
transactionId	string	No	Related transaction ID
amount	string	No	Transaction amount
currency	string	No	Currency code
purpose	string	No	Transaction purpose

Example Request

Single Wallet Verification

{
  "walletAddresses": [
    "0x742d35Cc6554C40621f3e3ea5c6d1F3B8DbD1234"
  ],
  "networks": [
    "ethereum"
  ],
  "verificationLevel": "enhanced",
  "includeRiskFactors": true,
  "includeCategoryDetails": true,
  "transactionContext": {
    "transactionId": "txn_abc123def456ghi789",
    "amount": "1500.00",
    "currency": "USDT",
    "purpose": "business_payment"
  }
}

Multiple Wallet Verification

{
  "walletAddresses": [
    "0x742d35Cc6554C40621f3e3ea5c6d1F3B8DbD1234",
    "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4",
    "0x8ba1f109551bd432803012645Hac136c22AfB15B"
  ],
  "networks": [
    "ethereum",
    "bitcoin",
    "ethereum"
  ],
  "verificationLevel": "standard",
  "includeRiskFactors": true,
  "includeCategoryDetails": false
}

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "verificationResults": [
      {
        "walletAddress": "0x742d35Cc6554C40621f3e3ea5c6d1F3B8DbD1234",
        "network": "ethereum",
        "verificationStatus": "completed",
        "verifiedAt": "2024-08-08T10:30:00Z",
        "bitrankScore": 85,
        "riskLevel": "low",
        "overallAssessment": "acceptable",
        "categories": [
          {
            "category": "exchange",
            "confidence": 92,
            "details": {
              "exchangeName": "Coinbase",
              "isRegulated": true,
              "jurisdiction": "US",
              "complianceRating": "high"
            }
          },
          {
            "category": "institutional",
            "confidence": 78,
            "details": {
              "institutionType": "custody_service",
              "isLicensed": true
            }
          }
        ],
        "riskFactors": [
          {
            "factor": "high_volume_activity",
            "severity": "low",
            "description": "Wallet shows high transaction volume consistent with institutional use",
            "impact": "positive"
          }
        ],
        "complianceChecks": {
          "sanctionsScreening": {
            "status": "clear",
            "lists": ["OFAC_SDN", "EU_SANCTIONS", "UN_SANCTIONS"],
            "lastChecked": "2024-08-08T10:30:00Z"
          },
          "pepScreening": {
            "status": "clear",
            "lastChecked": "2024-08-08T10:30:00Z"
          },
          "adverseMedia": {
            "status": "clear",
            "mentions": 0,
            "lastChecked": "2024-08-08T10:30:00Z"
          }
        },
        "transactionPatterns": {
          "averageTransactionValue": "2500.00",
          "transactionFrequency": "high",
          "primaryCurrencies": ["USDT", "USDC", "ETH"],
          "geographicDistribution": {
            "primaryRegions": ["North America", "Europe"],
            "riskRegions": []
          }
        },
        "historicalData": {
          "firstSeen": "2022-03-15T00:00:00Z",
          "lastActivity": "2024-08-08T09:45:00Z",
          "totalTransactions": 15647,
          "totalVolume": "45750000.00",
          "uniqueCounterparties": 342
        }
      },
      {
        "walletAddress": "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4",
        "network": "bitcoin",
        "verificationStatus": "completed",
        "verifiedAt": "2024-08-08T10:30:00Z",
        "bitrankScore": 45,
        "riskLevel": "medium",
        "overallAssessment": "requires_enhanced_due_diligence",
        "categories": [
          {
            "category": "mixer",
            "confidence": 65,
            "details": {
              "mixerService": "Unknown",
              "detectedMixingPatterns": true
            }
          },
          {
            "category": "gambling",
            "confidence": 23,
            "details": {
              "gamblingPlatform": "Various",
              "frequentGamblingActivity": false
            }
          }
        ],
        "riskFactors": [
          {
            "factor": "privacy_coin_interactions",
            "severity": "medium",
            "description": "Wallet has interactions with privacy-enhancing services",
            "impact": "negative"
          },
          {
            "factor": "mixing_service_usage",
            "severity": "high",
            "description": "Detected use of cryptocurrency mixing services",
            "impact": "negative"
          },
          {
            "factor": "irregular_transaction_patterns",
            "severity": "medium",
            "description": "Unusual transaction timing and amounts",
            "impact": "negative"
          }
        ],
        "complianceChecks": {
          "sanctionsScreening": {
            "status": "clear",
            "lists": ["OFAC_SDN", "EU_SANCTIONS"],
            "lastChecked": "2024-08-08T10:30:00Z"
          },
          "pepScreening": {
            "status": "clear",
            "lastChecked": "2024-08-08T10:30:00Z"
          },
          "adverseMedia": {
            "status": "flagged",
            "mentions": 3,
            "severity": "medium",
            "topics": ["money_laundering_investigation", "regulatory_action"],
            "lastChecked": "2024-08-08T10:30:00Z"
          }
        },
        "recommendedActions": [
          "enhanced_due_diligence",
          "manual_review",
          "transaction_monitoring",
          "senior_approval_required"
        ]
      }
    ],
    "summary": {
      "totalWallets": 2,
      "verificationComplete": 2,
      "verificationFailed": 0,
      "riskDistribution": {
        "low": 1,
        "medium": 1,
        "high": 0,
        "very_high": 0
      },
      "overallRecommendation": "enhanced_due_diligence_required",
      "highestRiskScore": 45,
      "lowestRiskScore": 85,
      "averageRiskScore": 65
    },
    "bitrankMetadata": {
      "apiVersion": "2.1",
      "dataVersion": "2024-08-08",
      "processingTime": 2.3,
      "creditsUsed": 4,
      "rateLimitRemaining": 996
    }
  },
  "message": "Wallet verification completed successfully"
}

Partial Success (206 Partial Content)

When some verifications fail:

{
  "success": true,
  "data": {
    "verificationResults": [
      {
        "walletAddress": "0x742d35Cc6554C40621f3e3ea5c6d1F3B8DbD1234",
        "network": "ethereum",
        "verificationStatus": "completed",
        "bitrankScore": 85,
        "riskLevel": "low"
      },
      {
        "walletAddress": "invalid_address_123",
        "network": "bitcoin",
        "verificationStatus": "failed",
        "error": {
          "code": "INVALID_ADDRESS_FORMAT",
          "message": "Invalid Bitcoin address format"
        }
      }
    ],
    "summary": {
      "totalWallets": 2,
      "verificationComplete": 1,
      "verificationFailed": 1
    }
  },
  "message": "Wallet verification completed with partial failures"
}

Error (400 Bad Request)

{
  "success": false,
  "error": "Invalid verification request",
  "code": "VALIDATION_ERROR",
  "details": {
    "walletAddresses": "At least one wallet address is required",
    "networks": "Networks array must match wallet addresses array length",
    "verificationLevel": "Must be one of: basic, standard, enhanced"
  }
}

Error (401 Unauthorized)

{
  "success": false,
  "error": "Authentication required",
  "code": "AUTH_REQUIRED"
}

Error (503 Service Unavailable)

{
  "success": false,
  "error": "Bitrank service temporarily unavailable",
  "code": "BITRANK_SERVICE_UNAVAILABLE",
  "details": {
    "retryAfter": 300,
    "maintenance": false
  }
}

Verification Levels

Level	Description	Data Included	Credits Used
basic	Basic risk scoring	Score, risk level, categories	1 per wallet
standard	Standard analysis	Basic + risk factors, compliance	2 per wallet
enhanced	Comprehensive analysis	Standard + patterns, historical data	4 per wallet

Risk Levels

Risk Level	Score Range	Recommendation
very_low	90-100	Standard processing
low	70-89	Standard processing
medium	40-69	Enhanced due diligence
high	20-39	Manual review required
very_high	0-19	Consider rejection

Wallet Categories

Common categories returned by Bitrank:

Category	Description	Risk Level
exchange	Centralized exchange wallet	Low-Medium
institutional	Institutional custody	Very Low
defi	DeFi protocol interaction	Medium
mixer	Privacy/mixing service	High
gambling	Gambling platform	Medium-High
marketplace	NFT/Digital marketplace	Low-Medium
mining_pool	Mining pool wallet	Low
ransomware	Known ransomware wallet	Very High
darknet	Darknet marketplace	Very High
sanctions	Sanctioned entity	Very High

Risk Factors

Common risk factors include:

Factor	Severity	Description
mixing_service_usage	High	Use of coin mixing services
privacy_coin_interactions	Medium	Interactions with privacy coins
sanctions_list_proximity	Very High	Close association with sanctioned entities
high_risk_jurisdiction	Medium	Activity in high-risk countries
unusual_transaction_patterns	Medium	Irregular transaction behavior
darknet_marketplace_activity	Very High	Darknet marketplace transactions
ransomware_connections	Very High	Links to ransomware activities

Usage Examples

Basic Wallet Check

curl -X POST "{{baseUrl}}/trp/verify-wallets-bitrank" \
  -H "x-api-key: {your-api-key}" \
  -H "x-secret-key: {your-secret-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddresses": ["0x742d35Cc6554C40621f3e3ea5c6d1F3B8DbD1234"],
    "networks": ["ethereum"],
    "verificationLevel": "basic"
  }'

Enhanced Verification with Context

curl -X POST "{{baseUrl}}/trp/verify-wallets-bitrank" \
  -H "x-api-key: {your-api-key}" \
  -H "x-secret-key: {your-secret-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddresses": [
      "0x742d35Cc6554C40621f3e3ea5c6d1F3B8DbD1234",
      "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4"
    ],
    "networks": ["ethereum", "bitcoin"],
    "verificationLevel": "enhanced",
    "includeRiskFactors": true,
    "includeCategoryDetails": true,
    "transactionContext": {
      "transactionId": "txn_abc123def456ghi789",
      "amount": "50000.00",
      "currency": "USDT",
      "purpose": "business_payment"
    }
  }'

Multiple Wallet Batch Verification

curl -X POST "{{baseUrl}}/trp/verify-wallets-bitrank" \
  -H "x-api-key: {your-api-key}" \
  -H "x-secret-key: {your-secret-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddresses": [
      "0x742d35Cc6554C40621f3e3ea5c6d1F3B8DbD1234",
      "0x8ba1f109551bd432803012645Hac136c22AfB15B",
      "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4"
    ],
    "networks": ["ethereum", "ethereum", "bitcoin"],
    "verificationLevel": "standard",
    "includeRiskFactors": true
  }'

Integration Best Practices

1. Pre-Transaction Verification: Verify wallets before creating transactions
2. Risk-Based Processing: Apply different processing based on risk scores
3. Regular Re-verification: Re-verify high-risk wallets periodically
4. Alert Systems: Set up alerts for high-risk verification results
5. Documentation: Keep records of all verification results for compliance

Response Interpretation

Low Risk (Score 70+)

• Proceed with standard processing
• Standard monitoring required
• Document verification results

Medium Risk (Score 40-69)

• Enhanced due diligence required
• Additional documentation may be needed
• Senior approval recommended

High Risk (Score less than 40)

• Manual review required
• Consider transaction rejection
• Enhanced monitoring if proceeding
• Senior management approval required

Error Handling

Common error scenarios:

Error Code	Description	Resolution
INVALID_ADDRESS_FORMAT	Invalid wallet address	Validate address format
UNSUPPORTED_NETWORK	Network not supported	Use supported network
INSUFFICIENT_CREDITS	Not enough Bitrank credits	Purchase additional credits
SERVICE_UNAVAILABLE	Bitrank service down	Retry later

Webhook Integration

Set up webhooks to receive updates:

• bitrank_verification.completed
• bitrank_verification.failed
• bitrank_verification.high_risk_detected

Compliance Integration

Verification results automatically integrate with:

• Transaction risk assessment
• AML monitoring systems
• Compliance reporting
• Audit trails