Record Verification

Record and associate Bitrank wallet verification results with a specific transaction for compliance tracking and audit purposes.

Endpoint

POST https://api.trpcontinuum.com/trp/transactions/{id}/bitrank-verify

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

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Transaction ID

Request Body

Field	Type	Required	Description
`originatorWalletVerification`	object	No	Bitrank verification for originator wallet
`beneficiaryWalletVerification`	object	No	Bitrank verification for beneficiary wallet
`verificationTimestamp`	string	Yes	When verification was performed (ISO 8601)
`verifiedBy`	string	Yes	ID of the user/system who performed verification
`complianceDecision`	string	Yes	"approved", "rejected", "requires_review"
`decisionReason`	string	No	Reason for the compliance decision
`riskMitigationMeasures`	array	No	List of risk mitigation measures applied
`reviewNotes`	string	No	Additional notes from the compliance review

Wallet Verification Object

Field	Type	Required	Description
`walletAddress`	string	Yes	Wallet address that was verified
`network`	string	Yes	Network/blockchain identifier
`bitrankScore`	number	Yes	Bitrank risk score (0-100)
`riskLevel`	string	Yes	Risk level assessment
`categories`	array	Yes	Identified wallet categories
`riskFactors`	array	No	Identified risk factors
`complianceFlags`	array	No	Compliance-related flags
`verificationId`	string	No	Bitrank verification reference ID

Example Request

Complete Verification Recording

{
  "originatorWalletVerification": {
    "walletAddress": "0x8ba1f109551bd432803012645Hac136c22AfB15B",
    "network": "ethereum",
    "bitrankScore": 88,
    "riskLevel": "low",
    "categories": [
      {
        "category": "exchange",
        "confidence": 95,
        "details": {
          "exchangeName": "Coinbase",
          "isRegulated": true
        }
      }
    ],
    "riskFactors": [],
    "complianceFlags": [
      "aml_compliant_exchange"
    ],
    "verificationId": "BR-VER-20240808-001"
  },
  "beneficiaryWalletVerification": {
    "walletAddress": "0x742d35Cc6554C40621f3e3ea5c6d1F3B8DbD1234",
    "network": "ethereum",
    "bitrankScore": 45,
    "riskLevel": "medium",
    "categories": [
      {
        "category": "mixer",
        "confidence": 65
      },
      {
        "category": "defi",
        "confidence": 40
      }
    ],
    "riskFactors": [
      {
        "factor": "mixing_service_usage",
        "severity": "medium"
      },
      {
        "factor": "irregular_transaction_patterns",
        "severity": "low"
      }
    ],
    "complianceFlags": [
      "requires_enhanced_monitoring"
    ],
    "verificationId": "BR-VER-20240808-002"
  },
  "verificationTimestamp": "2024-08-08T10:35:00Z",
  "verifiedBy": "compliance_officer_001",
  "complianceDecision": "approved",
  "decisionReason": "Originator wallet is from regulated exchange. Beneficiary wallet has medium risk but within acceptable thresholds for this transaction amount and customer profile.",
  "riskMitigationMeasures": [
    "enhanced_transaction_monitoring",
    "periodic_re_verification",
    "senior_approval_obtained"
  ],
  "reviewNotes": "Transaction approved with enhanced monitoring. Beneficiary wallet will be re-verified monthly due to mixing service usage patterns."
}

Rejection Recording

{
  "beneficiaryWalletVerification": {
    "walletAddress": "0x742d35Cc6554C40621f3e3ea5c6d1F3B8DbD1234",
    "network": "ethereum",
    "bitrankScore": 15,
    "riskLevel": "very_high",
    "categories": [
      {
        "category": "ransomware",
        "confidence": 92
      },
      {
        "category": "sanctions",
        "confidence": 88
      }
    ],
    "riskFactors": [
      {
        "factor": "ransomware_connections",
        "severity": "very_high"
      },
      {
        "factor": "sanctions_list_match",
        "severity": "very_high"
      }
    ],
    "complianceFlags": [
      "sanctions_hit",
      "law_enforcement_alert",
      "high_risk_entity"
    ],
    "verificationId": "BR-VER-20240808-003"
  },
  "verificationTimestamp": "2024-08-08T10:40:00Z",
  "verifiedBy": "senior_compliance_officer_001",
  "complianceDecision": "rejected",
  "decisionReason": "Beneficiary wallet associated with ransomware activities and appears on sanctions lists. Transaction cannot proceed due to regulatory restrictions.",
  "reviewNotes": "Transaction rejected immediately. Incident reported to relevant authorities as required by regulations."
}

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "transaction": {
      "id": "txn_abc123def456ghi789",
      "status": "bitrank_verified",
      "bitrankVerification": {
        "recordedAt": "2024-08-08T10:35:00Z",
        "recordedBy": "compliance_officer_001",
        "verificationReference": "BRV-2024080810351",
        "complianceDecision": "approved",
        "decisionReason": "Originator wallet is from regulated exchange. Beneficiary wallet has medium risk but within acceptable thresholds for this transaction amount and customer profile.",
        "originatorWallet": {
          "address": "0x8ba1f109551bd432803012645Hac136c22AfB15B",
          "network": "ethereum",
          "bitrankScore": 88,
          "riskLevel": "low",
          "overallAssessment": "acceptable",
          "primaryCategory": "exchange",
          "complianceStatus": "compliant"
        },
        "beneficiaryWallet": {
          "address": "0x742d35Cc6554C40621f3e3ea5c6d1F3B8DbD1234",
          "network": "ethereum",
          "bitrankScore": 45,
          "riskLevel": "medium",
          "overallAssessment": "acceptable_with_monitoring",
          "primaryCategory": "mixer",
          "complianceStatus": "requires_monitoring"
        },
        "overallRiskAssessment": {
          "combinedRiskScore": 66.5,
          "combinedRiskLevel": "medium",
          "recommendedActions": [
            "enhanced_transaction_monitoring",
            "periodic_re_verification"
          ],
          "complianceRequirements": [
            "monthly_re_verification",
            "enhanced_record_keeping"
          ]
        },
        "riskMitigationMeasures": [
          "enhanced_transaction_monitoring",
          "periodic_re_verification",
          "senior_approval_obtained"
        ]
      },
      "complianceStatus": {
        "bitrankVerified": true,
        "bitrankCompliant": true,
        "overallCompliance": "compliant_with_monitoring"
      },
      "updatedAt": "2024-08-08T10:35:00Z"
    },
    "statusHistory": [
      {
        "status": "pending_beneficiary_approval",
        "timestamp": "2024-08-08T10:00:00Z",
        "actor": "system",
        "notes": "Awaiting beneficiary VASP approval"
      },
      {
        "status": "bitrank_verified",
        "timestamp": "2024-08-08T10:35:00Z",
        "actor": "vasp_123456",
        "actorName": "SecureBank Digital Assets",
        "notes": "Bitrank wallet verification completed and recorded"
      }
    ],
    "nextSteps": [
      {
        "action": "transaction_approval",
        "description": "Proceed with transaction approval process",
        "actor": "beneficiary_vasp",
        "estimated_duration": "30 minutes"
      }
    ]
  },
  "message": "Bitrank verification results recorded successfully"
}

Success - Rejected Transaction (200 OK)

{
  "success": true,
  "data": {
    "transaction": {
      "id": "txn_abc123def456ghi789",
      "status": "rejected",
      "bitrankVerification": {
        "recordedAt": "2024-08-08T10:40:00Z",
        "recordedBy": "senior_compliance_officer_001",
        "verificationReference": "BRV-2024080810401",
        "complianceDecision": "rejected",
        "decisionReason": "Beneficiary wallet associated with ransomware activities and appears on sanctions lists. Transaction cannot proceed due to regulatory restrictions.",
        "beneficiaryWallet": {
          "address": "0x742d35Cc6554C40621f3e3ea5c6d1F3B8DbD1234",
          "network": "ethereum",
          "bitrankScore": 15,
          "riskLevel": "very_high",
          "overallAssessment": "unacceptable",
          "primaryCategory": "ransomware",
          "complianceStatus": "non_compliant"
        },
        "overallRiskAssessment": {
          "combinedRiskScore": 15,
          "combinedRiskLevel": "very_high",
          "recommendedActions": [
            "reject_transaction",
            "report_to_authorities"
          ]
        }
      },
      "rejectionDetails": {
        "rejectedAt": "2024-08-08T10:40:00Z",
        "rejectedBy": "vasp_123456",
        "rejectionReason": "bitrank_high_risk",
        "complianceReport": "filed"
      }
    }
  },
  "message": "Bitrank verification recorded - transaction rejected due to high risk"
}

Error (400 Bad Request)

{
  "success": false,
  "error": "Invalid verification data",
  "code": "VALIDATION_ERROR",
  "details": {
    "verificationTimestamp": "Timestamp cannot be in the future",
    "complianceDecision": "Must be one of: approved, rejected, requires_review",
    "originatorWalletVerification.bitrankScore": "Score must be between 0 and 100"
  }
}

Error (404 Not Found)

{
  "success": false,
  "error": "Transaction not found",
  "code": "TRANSACTION_NOT_FOUND"
}

Error (409 Conflict)

{
  "success": false,
  "error": "Bitrank verification already recorded for this transaction",
  "code": "VERIFICATION_ALREADY_RECORDED",
  "details": {
    "recordedAt": "2024-08-08T10:30:00Z",
    "recordedBy": "compliance_officer_001",
    "verificationReference": "BRV-2024080810301"
  }
}

Compliance Decisions

Decision	Description	Next Steps
`approved`	Verification passed, transaction can proceed	Continue with transaction processing
`rejected`	Verification failed, transaction blocked	Transaction rejected, report if required
`requires_review`	Manual review needed	Escalate to senior compliance officer

Risk Mitigation Measures

Common mitigation measures:

Measure	Description	When Applied
`enhanced_transaction_monitoring`	Increased monitoring frequency	Medium+ risk
`periodic_re_verification`	Regular re-verification schedule	Medium+ risk
`senior_approval_obtained`	Senior management approval	High risk
`enhanced_record_keeping`	Additional documentation	All high-risk cases
`law_enforcement_notification`	Authorities notified	Very high risk
`transaction_amount_limits`	Ongoing amount restrictions	Medium risk
`customer_education`	Customer risk awareness	Medium risk

Status Transitions

Recording verification results can trigger status changes:

From Status	To Status	Condition
`pending_beneficiary_approval`	`bitrank_verified`	Verification recorded
`kyc_required`	`bitrank_verified`	Verification recorded
`bitrank_verified`	`approved`	Low risk, auto-approved
`bitrank_verified`	`rejected`	High risk, auto-rejected
`bitrank_verified`	`requires_manual_review`	Medium-high risk

Usage Examples

Record Approved Verification

curl -X POST "{{baseUrl}}/trp/transactions/txn_abc123def456ghi789/bitrank-verify" \
  -H "x-api-key: {your-api-key}" \
  -H "x-secret-key: {your-secret-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "originatorWalletVerification": {
      "walletAddress": "0x8ba1f109551bd432803012645Hac136c22AfB15B",
      "network": "ethereum",
      "bitrankScore": 88,
      "riskLevel": "low",
      "categories": [{"category": "exchange", "confidence": 95}],
      "riskFactors": []
    },
    "verificationTimestamp": "2024-08-08T10:35:00Z",
    "verifiedBy": "compliance_officer_001",
    "complianceDecision": "approved",
    "decisionReason": "Low risk originator from regulated exchange"
  }'

Record Rejected Verification

curl -X POST "{{baseUrl}}/trp/transactions/txn_abc123def456ghi789/bitrank-verify" \
  -H "x-api-key: {your-api-key}" \
  -H "x-secret-key: {your-secret-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiaryWalletVerification": {
      "walletAddress": "0x742d35Cc6554C40621f3e3ea5c6d1F3B8DbD1234",
      "network": "ethereum",
      "bitrankScore": 15,
      "riskLevel": "very_high",
      "categories": [{"category": "ransomware", "confidence": 92}],
      "riskFactors": [{"factor": "ransomware_connections", "severity": "very_high"}],
      "complianceFlags": ["sanctions_hit"]
    },
    "verificationTimestamp": "2024-08-08T10:40:00Z",
    "verifiedBy": "senior_compliance_officer_001",
    "complianceDecision": "rejected",
    "decisionReason": "Beneficiary wallet associated with ransomware activities"
  }'

Record Verification Requiring Review

curl -X POST "{{baseUrl}}/trp/transactions/txn_abc123def456ghi789/bitrank-verify" \
  -H "x-api-key: {your-api-key}" \
  -H "x-secret-key: {your-secret-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiaryWalletVerification": {
      "walletAddress": "0x742d35Cc6554C40621f3e3ea5c6d1F3B8DbD1234",
      "network": "ethereum",
      "bitrankScore": 55,
      "riskLevel": "medium",
      "categories": [{"category": "gambling", "confidence": 78}],
      "riskFactors": [{"factor": "gambling_platform_activity", "severity": "medium"}]
    },
    "verificationTimestamp": "2024-08-08T10:45:00Z",
    "verifiedBy": "compliance_officer_001",
    "complianceDecision": "requires_review",
    "decisionReason": "Medium risk requires senior review due to gambling activity",
    "reviewNotes": "Customer has legitimate business purpose but wallet shows gambling activity"
  }'

Audit and Compliance

Record Keeping Requirements

All verification results must be recorded
Decision rationale must be documented
Risk mitigation measures must be tracked
Regular audit trail maintenance

Regulatory Reporting

High-risk transactions may trigger reporting requirements
Sanctions hits must be reported to authorities
Suspicious activity reports may be required
Cross-border reporting obligations

Best Practices

Timely Recording: Record verification results immediately after verification
Complete Documentation: Include all relevant risk factors and mitigation measures
Decision Consistency: Apply consistent standards across all verifications
Senior Review: Escalate high-risk cases to senior compliance officers
Regular Updates: Re-verify high-risk wallets periodically
Audit Preparation: Maintain detailed records for regulatory audits

Integration Points

This endpoint integrates with:

Transaction workflow automation
Compliance monitoring systems
Risk assessment engines
Reporting dashboards
Audit trail systems

Webhook Events

This action triggers the following webhook events:

transaction.bitrank_verified
transaction.status_changed
compliance.high_risk_detected (if applicable)
compliance.verification_recorded

Endpoint​

Authentication​

Headers​

Path Parameters​

Request Body​

Wallet Verification Object​

Example Request​

Complete Verification Recording​

Rejection Recording​

Response​

Success (200 OK)​

Success - Rejected Transaction (200 OK)​

Error (400 Bad Request)​

Error (404 Not Found)​

Error (409 Conflict)​

Compliance Decisions​

Risk Mitigation Measures​

Status Transitions​

Usage Examples​

Record Approved Verification​

Record Rejected Verification​

Record Verification Requiring Review​

Audit and Compliance​

Record Keeping Requirements​

Regulatory Reporting​

Best Practices​

Integration Points​

Webhook Events​