Інтеграція AML-скринінгу (Chainalysis, Elliptic, Crystal)

Інтеграція AML-скрининга (Chainalysis, Elliptic, Crystal)

AML скрининг крипто-валютних транзакцій — обов'язковий елемент compliance для будь-якої платформи, яка працює з крипто. Завдання: при кожному депозиті або виведенні перевірити, чи не пов'язан адрес з санкціонованими суб'єктами, даркнет маркетами, вкраденими коштами або іншою high-risk активністю.

Chainalysis KYT (Know Your Transaction)

Chainalysis — лідер ринку, використовується більшістю крупних бірж та регуляторами для forensics. API ділиться на кілька продуктів: KYT для transaction monitoring, Reactor для investigation, Kryptos для entity data.

Інтеграція KYT API

class ChainalysisClient {
  private readonly baseURL = "https://api.chainalysis.com";
  
  async registerAddress(address: string, asset: "USDT" | "ETH" | "BTC" | string): Promise<void> {
    await this.post("/api/kyt/v2/users", {
      userId: address,
      asset,
    });
  }
  
  async screenTransfer(params: {
    asset: string;
    network: string;
    transferReference: string; // txHash або address
    direction: "received" | "sent";
    userId: string;
    outputAddress?: string;
    value?: string;
    assetAmount?: number;
    timestamp?: string;
  }): Promise<TransferRisk> {
    const response = await this.post("/api/kyt/v2/transfers", params);
    
    return {
      externalId: response.externalId,
      riskScore: response.riskScore,
      cluster: response.cluster,
      status: response.status, // "APPROVED" | "BLOCKED" | "IN_REVIEW"
    };
  }
  
  // Отримуємо детальні alerts по переводу
  async getTransferAlerts(externalId: string): Promise<Alert[]> {
    const response = await this.get(`/api/kyt/v2/transfers/${externalId}/alerts`);
    return response.alerts;
  }
  
  private async post(path: string, body: any): Promise<any> {
    const response = await fetch(`${this.baseURL}${path}`, {
      method: "POST",
      headers: {
        "Token": this.apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });
    return response.json();
  }
}

Risk Score категорії

Категорії, які дають автоматичну блокировку незалежно від score:

• darknet_market
• ransomware
• stolen_funds
• sanctions
• terrorist_financing

Обробка депозиту

async function processDeposit(deposit: Deposit): Promise<DepositResult> {
  // Реєструємо адрес якщо новий
  await chainalysis.registerAddress(deposit.fromAddress, deposit.asset);
  
  // Скринюємо транзакцію
  const risk = await chainalysis.screenTransfer({
    asset: deposit.asset,
    network: deposit.network,
    transferReference: deposit.txHash,
    direction: "received",
    userId: deposit.userId,
    value: deposit.usdValue.toString(),
    assetAmount: deposit.amount,
  });
  
  if (risk.status === "BLOCKED") {
    await freezeDeposit(deposit.id);
    await notifyCompliance(deposit, risk);
    return { status: "blocked", reason: risk.cluster?.category };
  }
  
  if (risk.status === "IN_REVIEW") {
    await holdForReview(deposit.id);
    await createComplianceTask(deposit, risk);
    return { status: "pending_review" };
  }
  
  await creditUserAccount(deposit);
  return { status: "approved" };
}

Elliptic Lens / Navigator

Elliptic — конкурент Chainalysis з подібним функціоналом. Сильніше в DeFi скринингу та cross-asset трасуванні.

class EllipticClient {
  async getWalletRisk(address: string, asset: string): Promise<EllipticRisk> {
    const response = await this.post("/v2/wallet/synchronous", {
      subject: {
        asset,
        type: "address",
        hash: address,
      },
      type: "wallet_exposure",
      customer_reference: address,
    });
    
    return {
      riskScore: response.risk_score, // 0-10 (у Elliptic інша шкала)
      exposures: response.exposures,   // розбивка за категоріями
      clusters: response.entities,
    };
  }
  
  async getTransactionRisk(txHash: string, asset: string): Promise<EllipticRisk> {
    return this.post("/v2/txs/synchronous", {
      subject: { asset, type: "transaction", hash: txHash },
      type: "indirect_exposure",
    });
  }
}

Elliptic score від 0 до 10 — потрібна нормалізація для єдиної risk логіки якщо використовуєте обох провайдерів.

Crystal Blockchain (для Східної Європи)

Crystal — європейський гравець, часто переважний для проектів з СНГ/ЄС через ціни та підтримку.

const crystalResponse = await axios.post(
  "https://aml.crystalblockchain.com/api/v1/risks/check",
  {
    address,
    currency: asset,
  },
  {
    headers: { "X-Auth-Apikey": CRYSTAL_API_KEY },
  }
);

// crystal повертає: risk_score (0-100), signals (список сигналів)

Dual-provider стратегія

Для production: два провайдери знижують ризик ложноотрицательних результатів. Логіка: BLOCK якщо хоча б один блокує, REVIEW якщо хоча б один флагує.

async function dualProviderScreen(address: string, txHash: string): Promise<RiskDecision> {
  const [chainalysisResult, ellipticResult] = await Promise.allSettled([
    chainalysis.screenTransfer({ transferReference: txHash, ... }),
    elliptic.getWalletRisk(address, asset),
  ]);
  
  const c = chainalysisResult.status === "fulfilled" ? chainalysisResult.value : null;
  const e = ellipticResult.status === "fulfilled" ? ellipticResult.value : null;
  
  // Якщо один з провайдерів недоступен — використовуємо другий
  if (!c && !e) throw new Error("Both AML providers unavailable");
  
  const maxScore = Math.max(
    c?.riskScore ?? 0,
    e ? e.riskScore * 10 : 0, // нормалізація Elliptic 0-10 → 0-100
  );
  
  if (maxScore >= 70 || c?.status === "BLOCKED") return { decision: "BLOCK", score: maxScore };
  if (maxScore >= 40) return { decision: "REVIEW", score: maxScore };
  return { decision: "ALLOW", score: maxScore };
}

Інтеграція одного AML провайдера (API + логіка блокировки + compliance dashboard) — 1-2 тижні. Dual-provider система з автоматичним failover — 2-3 тижні.