MiCA API Reference

const headers = {
  'Authorization': `Bearer ${YOUR_API_KEY}`,
  'Content-Type': 'application/json'
};

const response = await fetch('https://api.vincta.io/api/mica/evaluate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer sk_live_abc123def456`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    client_id: 'your-client-id',
    trigger_type: 'transaction',
    trigger_entity_type: 'transaction',
    trigger_entity_id: 'tx-001',
    data: { /* ... */ }
  })
});

{
  client_id: string;                    // Your VINCTA client ID
  trigger_type: 'transaction' | 'wallet_screen' | 'travel_rule' | 'periodic' | 'manual';
  trigger_entity_type?: string;         // 'transaction', 'wallet', 'transfer', 'customer'
  trigger_entity_id?: string;           // External ID for tracking
  data: {
    // Context-specific fields (see below)
  }
}

{
  rules_evaluated: number;              // Total rules checked
  rules_triggered: number;              // Rules that triggered
  evaluation_id: string;                // Unique evaluation ID
  timestamp: string;                    // ISO 8601 timestamp (UTC)
  results: Array<{
    rule_id: string;                    // e.g., 'MICA-CDD-002'
    rule_name: string;                  // Human-readable name
    triggered: boolean;                 // Did this rule trigger?
    result: 'pass' | 'fail' | 'alert' | 'block';
    conditions_met: {
      [key: string]: boolean;           // Each condition evaluated
    };
    actions_to_execute: string[];       // Actions to take
    severity: 'low' | 'medium' | 'high' | 'critical';
  }>;
  highest_severity: 'low' | 'medium' | 'high' | 'critical' | null;
  actions_required: string[];           // e.g., ['block_transaction', 'create_case']
  should_block: boolean;                // Block the transaction?
  should_alert: boolean;                // Generate alert?
  should_create_case: boolean;          // Create compliance case?
}

const result = await fetch('https://api.vincta.io/api/mica/evaluate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    client_id: 'f249472f-610c-4d45-b462-cd114829f214',
    trigger_type: 'transaction',
    trigger_entity_type: 'transaction',
    trigger_entity_id: 'tx-20260101-001',
    data: {
      customer_verified: true,
      customer_id: 'cust-12345',
      customer_country: 'DE',
      amount_eur: 1500,
      amount_crypto: 0.05,
      transaction_type: 'send',
      full_cdd_complete: false,
      self_hosted_wallet: true,
      ownership_verified: false,
      address_validation_status: 'passed',
      multiple_identities_detected: false,
      suspicious_activity_detected: false
    }
  })
}).then(r => r.json());

{
  "rules_evaluated": 6,
  "rules_triggered": 1,
  "evaluation_id": "eval-uuid-12345",
  "timestamp": "2026-01-01T10:30:00Z",
  "results": [
    {
      "rule_id": "MICA-CDD-002",
      "rule_name": "Full CDD Threshold",
      "triggered": true,
      "result": "block",
      "conditions_met": {
        "amount_eur_gte_1000": true,
        "full_cdd_complete": false
      },
      "actions_to_execute": ["block_transaction", "create_case"],
      "severity": "high"
    },
    {
      "rule_id": "MICA-CDD-001",
      "rule_name": "Identity Verification Required",
      "triggered": false,
      "result": "pass",
      "conditions_met": {
        "customer_verified": true
      },
      "actions_to_execute": [],
      "severity": "critical"
    }
  ],
  "highest_severity": "high",
  "actions_required": ["block_transaction", "create_case"],
  "should_block": true,
  "should_alert": false,
  "should_create_case": true
}

{
  client_id: string;
  trigger_type: 'transaction';
  trigger_entity_type: 'transaction';
  trigger_entity_id: string;            // Unique transaction ID
  data: {
    // Customer fields
    customer_verified?: boolean;         // Customer identity verified?
    customer_id?: string;                // Unique customer identifier
    customer_country?: string;           // ISO 3166-1 alpha-2 code
    
    // Transaction fields
    amount_eur?: number;                 // Transaction amount in EUR
    amount_crypto?: number;              // Transaction amount in crypto
    transaction_type?: string;           // 'send', 'receive', 'trade'
    
    // CDD fields
    full_cdd_complete?: boolean;         // Full CDD completed?
    cdd_completion_date?: string;        // ISO 8601 date
    
    // Wallet fields
    self_hosted_wallet?: boolean;        // Is it self-hosted?
    ownership_verified?: boolean;        // Ownership verified?
    wallet_address?: string;             // Blockchain address
    
    // Address fields
    address_validation_status?: string;  // 'passed', 'failed', 'pending'
    
    // Risk fields
    multiple_identities_detected?: boolean;
    suspicious_activity_detected?: boolean;
  }
}

const result = await evaluateMicaRules({
  client_id: 'f249472f-610c-4d45-b462-cd114829f214',
  trigger_type: 'transaction',
  trigger_entity_type: 'transaction',
  trigger_entity_id: 'tx-20260101-001',
  data: {
    customer_verified: true,
    customer_id: 'cust-12345',
    customer_country: 'DE',
    amount_eur: 1500,
    amount_crypto: 0.05,
    transaction_type: 'send',
    full_cdd_complete: false,
    cdd_completion_date: '2025-12-15',
    self_hosted_wallet: true,
    ownership_verified: false,
    wallet_address: '0x742d35Cc6634C0532925a3b844Bc9e7595f42bE',
    address_validation_status: 'passed',
    multiple_identities_detected: false,
    suspicious_activity_detected: false
  }
});

{
  client_id: string;
  trigger_type: 'wallet_screen';
  trigger_entity_type: 'wallet';
  trigger_entity_id: string;            // Wallet address
  data: {
    wallet_address: string;             // Blockchain wallet address
    blockchain: string;                 // 'bitcoin', 'ethereum', etc.
    wallet_risk_score?: number;         // 0-100 risk score
    wallet_risk_level?: string;         // 'low', 'medium', 'high', 'critical'
    associated_exchanges?: string[];    // Known exchange addresses
    associated_sanctions?: boolean;     // Sanctioned entity exposure?
    associated_darknet?: boolean;       // Darknet marketplace exposure?
    transaction_history_length?: number; // Days of transaction history
    transaction_frequency?: number;     // Transactions per day
    self_hosted_wallet?: boolean;       // Is it self-hosted?
    ownership_verified?: boolean;       // Ownership verified?
  }
}

const result = await evaluateMicaRules({
  client_id: 'f249472f-610c-4d45-b462-cd114829f214',
  trigger_type: 'wallet_screen',
  trigger_entity_type: 'wallet',
  trigger_entity_id: '0x742d35Cc6634C0532925a3b844Bc9e7595f42bE',
  data: {
    wallet_address: '0x742d35Cc6634C0532925a3b844Bc9e7595f42bE',
    blockchain: 'ethereum',
    wallet_risk_score: 45,
    wallet_risk_level: 'medium',
    associated_exchanges: ['0x1111111254fb6c44bac0bed2854e76f90643097d'],
    associated_sanctions: false,
    associated_darknet: false,
    transaction_history_length: 180,
    transaction_frequency: 2.5,
    self_hosted_wallet: true,
    ownership_verified: false
  }
});

{
  client_id: string;
  trigger_type: 'travel_rule';
  trigger_entity_type: 'transfer';
  trigger_entity_id: string;            // Transfer ID
  data: {
    transfer_id: string;                // Unique transfer identifier
    direction: 'outbound' | 'inbound';  // Transfer direction
    amount_eur: number;                 // Transfer amount in EUR
    amount_crypto: number;              // Transfer amount in crypto
    
    // Originator information
    originator_name?: string;           // Full name
    originator_customer_id?: string;    // Customer ID
    originator_country?: string;        // ISO 3166-1 alpha-2
    originator_wallet_address?: string; // Wallet address
    
    // Beneficiary information
    beneficiary_name?: string;          // Full name
    beneficiary_customer_id?: string;   // Customer ID (if internal)
    beneficiary_country?: string;       // ISO 3166-1 alpha-2
    beneficiary_wallet_address?: string; // Wallet address
    
    // Transfer details
    transfer_type: 'internal' | 'external'; // Internal or external transfer
    data_completeness: 'complete' | 'partial' | 'missing';
    self_hosted_wallet: boolean;        // Destination is self-hosted?
    ownership_verified?: boolean;       // Ownership verified?
  }
}

const result = await evaluateMicaRules({
  client_id: 'f249472f-610c-4d45-b462-cd114829f214',
  trigger_type: 'travel_rule',
  trigger_entity_type: 'transfer',
  trigger_entity_id: 'tr-20260101-001',
  data: {
    transfer_id: 'tr-20260101-001',
    direction: 'outbound',
    amount_eur: 15000,
    amount_crypto: 0.5,
    originator_name: 'John Doe',
    originator_customer_id: 'cust-12345',
    originator_country: 'DE',
    originator_wallet_address: '0x742d35Cc6634C0532925a3b844Bc9e7595f42bE',
    beneficiary_name: 'Jane Smith',
    beneficiary_country: 'FR',
    beneficiary_wallet_address: '0x8ba1f109551bD432803012645Ac136ddd64DBA72',
    transfer_type: 'external',
    data_completeness: 'complete',
    self_hosted_wallet: false,
    ownership_verified: true
  }
});

{
  client_id: string;
  trigger_type: 'periodic';
  trigger_entity_type: 'governance' | 'customer';
  trigger_entity_id: string;
  data: {
    // Governance fields
    compliance_officer_board_access_documented?: boolean;
    third_party_oversight_active?: boolean;
    days_since_last_review?: number;
    days_since_last_training?: number;
    
    // Customer review fields
    customer_id?: string;
    days_since_last_cdd_review?: number;
    risk_profile_changed?: boolean;
  }
}

if (result.should_block) {
  // Step 1: Block transaction
  await blockTransaction(transactionId);
  
  // Step 2: Log to audit trail (automatic)
  // Engine automatically logs to mica_rule_evaluations table
  
  // Step 3: Notify compliance team
  await notifyCompliance({
    type: 'transaction_blocked',
    evaluation_id: result.evaluation_id,
    rules_triggered: result.results
      .filter(r => r.result === 'block')
      .map(r => r.rule_id),
    transaction_id: transactionId,
    severity: result.highest_severity
  });
  
  // Step 4: Return error to customer
  return {
    success: false,
    message: 'Transaction blocked by compliance rules',
    reference: transactionId,
    contact: 'support@yourcompany.com'
  };
}

if (result.should_alert) {
  // Step 1: Create alert in compliance system
  const alert = {
    id: generateUUID(),
    evaluation_id: result.evaluation_id,
    type: 'compliance_alert',
    severity: result.highest_severity,
    rules_triggered: result.results
      .filter(r => r.triggered)
      .map(r => r.rule_id),
    customer_id: customerId,
    transaction_id: transactionId,
    created_at: new Date(),
    assigned_to: 'compliance_team'
  };
  
  // Step 2: Store alert in database
  await supabaseAdmin
    .from('compliance_alerts')
    .insert([alert]);
  
  // Step 3: Send notification
  await sendAlert({
    recipient: 'compliance_team@company.com',
    subject: `Compliance Alert: ${result.rules_triggered.join(', ')}`,
    body: `Rules triggered: ${result.rules_triggered.join(', ')}\nSeverity: ${result.highest_severity}\nEvaluation ID: ${result.evaluation_id}`,
    evaluation_id: result.evaluation_id
  });
  
  // Step 4: Allow transaction to proceed (unless also blocked)
  if (!result.should_block) {
    await processTransaction(transactionId);
  }
}

if (result.should_create_case) {
  // Step 1: Create compliance case
  const complianceCase = {
    id: generateUUID(),
    evaluation_id: result.evaluation_id,
    type: 'compliance_investigation',
    status: 'open',
    severity: result.highest_severity,
    rules_triggered: result.results
      .filter(r => r.triggered)
      .map(r => r.rule_id),
    customer_id: customerId,
    transaction_id: transactionId,
    created_at: new Date(),
    assigned_to: getNextAvailableOfficer(),
    due_date: addDays(new Date(), 5)  // 5 business days
  };
  
  // Step 2: Store case in database
  await supabaseAdmin
    .from('compliance_cases')
    .insert([complianceCase]);
  
  // Step 3: Assign to compliance officer
  await assignCase(complianceCase.id, complianceCase.assigned_to);
  
  // Step 4: Send notification
  await notifyComplianceOfficer({
    case_id: complianceCase.id,
    rules_triggered: complianceCase.rules_triggered,
    priority: result.highest_severity,
    due_date: complianceCase.due_date,
    evaluation_id: result.evaluation_id
  });
  
  // Step 5: Block transaction (if applicable)
  if (result.should_block) {
    throw new Error('Transaction blocked pending compliance review');
  }
}

SELECT
  rule_id,
  result,
  trigger_type,
  evaluated_at,
  transaction_blocked,
  alert_generated,
  conditions_met,
  actions_executed
FROM mica_rule_evaluations
WHERE client_id = 'your-client-id'
  AND trigger_entity_type = 'transaction'
  AND trigger_entity_id IN (
    SELECT transaction_id FROM transactions
    WHERE customer_id = 'customer-123'
  )
ORDER BY evaluated_at DESC;

SELECT
  rule_id,
  trigger_entity_id,
  evaluated_at,
  conditions_evaluated,
  conditions_met,
  actions_executed,
  severity
FROM mica_rule_evaluations
WHERE client_id = 'your-client-id'
  AND result = 'block'
  AND transaction_blocked = true
  AND evaluated_at >= NOW() - INTERVAL '30 days'
ORDER BY evaluated_at DESC;

SELECT
  rule_id,
  trigger_entity_id,
  evaluated_at,
  conditions_met,
  actions_executed,
  severity
FROM mica_rule_evaluations
WHERE client_id = 'your-client-id'
  AND rule_id LIKE 'MICA-RPT%'
  AND result IN ('fail', 'alert', 'block')
ORDER BY evaluated_at DESC;

SELECT
  rule_id,
  trigger_entity_id,
  evaluated_at,
  conditions_met,
  result,
  severity
FROM mica_rule_evaluations
WHERE client_id = 'your-client-id'
  AND rule_id LIKE 'MICA-CDD%'
  AND evaluated_at >= NOW() - INTERVAL '90 days'
ORDER BY evaluated_at DESC;

SELECT
  rule_id,
  trigger_type,
  trigger_entity_type,
  trigger_entity_id,
  result,
  conditions_evaluated,
  conditions_met,
  actions_executed,
  evaluated_at,
  transaction_blocked,
  alert_generated,
  severity,
  evaluation_id
FROM mica_rule_evaluations
WHERE client_id = 'your-client-id'
  AND evaluated_at BETWEEN '2024-01-01' AND '2024-12-31'
ORDER BY evaluated_at ASC;

SELECT
  rule_id,
  COUNT(*) as trigger_count,
  SUM(CASE WHEN result = 'block' THEN 1 ELSE 0 END) as blocks,
  SUM(CASE WHEN result = 'alert' THEN 1 ELSE 0 END) as alerts,
  AVG(CASE WHEN severity = 'critical' THEN 1 ELSE 0 END) as critical_rate
FROM mica_rule_evaluations
WHERE client_id = 'your-client-id'
  AND evaluated_at >= NOW() - INTERVAL '30 days'
GROUP BY rule_id
ORDER BY trigger_count DESC;

curl -H "Authorization: Bearer sk_live_abc123..." \
  "https://app.vincta.io/api/mica/wallet-screening?wallet_address=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb&blockchain=ethereum"

{
  "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "blockchain": "ethereum",
  "transaction_amount_eur": 5000,
  "originator_name": "John Doe",
  "beneficiary_name": "Jane Smith"
}

{
  "risk_profile": {
    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "blockchain": "ethereum",
    "risk_score": 85,
    "risk_category": "high",
    "sanctioned_exposure": 0,
    "darknet_exposure": 90,
    "mixer_exposure": 100,
    "last_activity_at": "2026-01-02T10:30:00Z"
  },
  "rule_evaluation": {
    "rules_triggered": 2,
    "should_alert": true,
    "should_block": false,
    "actions": ["REVIEW"],
    "triggered_rules": []
  }
}

{
  "transfer_id": "TRF-2026-001",
  "direction": "outbound",
  "amount_eur": 5000,
  "originator": {
    "name": "John Doe",
    "wallet_address": "0x123...",
    "geographic_address": "123 Main St, Berlin, Germany",
    "national_id": "DE123456789"
  },
  "beneficiary": {
    "name": "Jane Smith",
    "wallet_address": "0x456...",
    "casp_name": "Example Exchange",
    "casp_lei": "123456789ABCDEFGHIJ12"
  }
}

{
  "validation_result": {
    "transfer_id": "TRF-2026-001",
    "data_completeness": "complete",
    "required_fields": [],
    "self_hosted": false,
    "counterparty_verified": true
  },
  "rule_evaluation": {
    "rules_triggered": 0,
    "should_alert": false,
    "should_block": false,
    "actions": ["ALLOW"]
  }
}

GET /api/mica/circuit-breaker/status

{
  "breakers": {
    "trm_labs": {
      "state": "CLOSED",
      "failures": 0,
      "successes": 287,
      "last_failure": null
    },
    "scorechain": {
      "state": "CLOSED",
      "failures": 0,
      "successes": 287,
      "last_failure": null
    },
    "notabene": {
      "state": "CLOSED",
      "failures": 0,
      "successes": 287,
      "last_failure": null
    }
  }
}

GET /api/mica/cache/stats

{
  "wallet_screening": {
    "hit_rate": 0.72,
    "miss_rate": 0.28,
    "total_requests": 1247,
    "cache_size": 523,
    "memory_usage_mb": 4.2
  },
  "travel_rule": {
    "hit_rate": 0.68,
    "miss_rate": 0.32,
    "total_requests": 523,
    "cache_size": 287,
    "memory_usage_mb": 2.1
  }
}

{
  "error": "Vendor API unavailable",
  "type": "VENDOR",
  "details": {
    "vendor": "trm_labs",
    "breaker_state": "OPEN",
    "retry_after": 30
  },
  "statusCode": 503
}

if (error.statusCode === 503 && error.type === 'VENDOR') {
  // Use cached data if available
  const cached = await getFromCache(wallet_address);
  if (cached) {
    return cached;
  }
  
  // Otherwise, wait and retry
  await sleep(error.details.retry_after * 1000);
  return retry();
}

{
  "error": "Rate limit exceeded",
  "type": "RATE_LIMIT",
  "details": {
    "limit": 100,
    "remaining": 0,
    "reset_at": "2026-01-02T11:30:00Z"
  },
  "statusCode": 429
}

if (error.statusCode === 429) {
  const resetTime = new Date(error.details.reset_at);
  const waitTime = resetTime.getTime() - Date.now();
  
  // Implement exponential backoff
  await sleep(waitTime);
  return retry();
}

{
  "error": "Validation failed",
  "type": "VALIDATION",
  "details": {
    "errors": [
      "wallet_address: Required",
      "blockchain: Must be one of: ethereum, bitcoin, polygon, binance-smart-chain, solana"
    ]
  },
  "statusCode": 400
}

if (error.statusCode === 400 && error.type === 'VALIDATION') {
  // Fix validation errors and retry
  console.error('Validation errors:', error.details.errors);
  // Do not retry automatically - fix the request first
}

{
  error: {
    code: string;                       // Error code (e.g., 'INVALID_REQUEST')
    message: string;                    // Human-readable message
    details?: {
      field?: string;                   // Field that caused error
      reason?: string;                  // Specific reason
    };
  }
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required field: trigger_type",
    "details": {
      "field": "trigger_type",
      "reason": "Must be one of: transaction, wallet_screen, travel_rule, periodic, manual"
    }
  }
}

try {
  const result = await evaluateMicaRules(request);
  
  if (result.should_block) {
    // Handle block
  }
} catch (error) {
  if (error.code === 401) {
    // Re-authenticate
    console.error('Authentication failed. Check API key.');
  } else if (error.code === 429) {
    // Implement backoff
    await sleep(Math.random() * 1000);
    // Retry
  } else if (error.code === 500) {
    // Log and alert
    console.error('Server error:', error.message);
    await alertOps(error);
  }
}

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1609459200

if (response.status === 429) {
  const resetTime = parseInt(response.headers['X-RateLimit-Reset']);
  const waitTime = resetTime - Math.floor(Date.now() / 1000);
  console.log(`Rate limited. Retry after ${waitTime} seconds`);
  
  // Implement exponential backoff
  await sleep(waitTime * 1000);
  // Retry request
}

const cache = new Map();
 
async function evaluateWithCache(request) {
  const cacheKey = JSON.stringify(request);
  
  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }
  
  const result = await evaluateMicaRules(request);
  cache.set(cacheKey, result);
  
  // Clear cache after 5 minutes
  setTimeout(() => cache.delete(cacheKey), 5 * 60 * 1000);
  
  return result;
}

async function batchEvaluate(requests) {
  const results = await Promise.all(
    requests.map(req => evaluateMicaRules(req))
  );
  return results;
}
 
// Usage
const transactions = [...];
const results = await batchEvaluate(
  transactions.map(tx => ({
    client_id: CLIENT_ID,
    trigger_type: 'transaction',
    trigger_entity_type: 'transaction',
    trigger_entity_id: tx.id,
    data: tx
  }))
);