identity_check_sanctions

Instructions

Implementation Reference

• src/modules/identity/tools.js:224-347 (handler)

  The handler function for identity_check_sanctions, which screens a Hedera account by analyzing on-chain risk signals, transactions, and token statuses.

  if (name === "identity_check_sanctions") {
    const payment = chargeForTool("identity_check_sanctions", args.api_key);
    const base = getMirrorNodeBase();
  
    const resolved = await resolveAccountInput(args.account_id, base);
    const hederaId = resolved.hederaId;
  
    // Fetch account info (use cached from resolution if available)
    const account = resolved._account ||
      (await axios.get(`${base}/api/v1/accounts/${hederaId}`)).data;
  
    // Fetch recent transactions for pattern analysis
    const txRes = await axios.get(
      `${base}/api/v1/transactions?account.id=${hederaId}&limit=100&order=desc`
    ).catch(() => ({ data: { transactions: [] } }));
    const transactions = txRes.data.transactions || [];
  
    // Fetch token balances
    const tokenRes = await axios.get(
      `${base}/api/v1/accounts/${hederaId}/tokens?limit=100`
    ).catch(() => ({ data: { tokens: [] } }));
    const tokens = tokenRes.data.tokens || [];
  
    // Collect unique counterparties
    const counterparties = new Set();
    const txTypes = {};
    let failedTxCount = 0;
    let largeTransferCount = 0;
  
    for (const tx of transactions) {
      const t = tx.name || "UNKNOWN";
      txTypes[t] = (txTypes[t] || 0) + 1;
      if (tx.result && tx.result !== "SUCCESS") failedTxCount++;
      for (const transfer of tx.transfers || []) {
        if (transfer.account !== hederaId) {
          counterparties.add(transfer.account);
        }
        if (Math.abs(transfer.amount || 0) > 100000000000) {
          largeTransferCount++;
        }
      }
    }
  
    // Risk signal detection
    const riskSignals = [];
    let riskScore = 0;
  
    // Account age check
    const createdAt = account.created_timestamp
      ? new Date(parseFloat(account.created_timestamp) * 1000)
      : null;
    const ageDays = createdAt
      ? Math.floor((Date.now() - createdAt.getTime()) / (1000 * 60 * 60 * 24))
      : null;
  
    if (ageDays !== null && ageDays < 7) {
      riskScore += 20;
      riskSignals.push("Very new account - created less than 7 days ago");
    }
  
    if (failedTxCount > 5) {
      riskScore += 15;
      riskSignals.push("High failed transaction rate - " + failedTxCount + " failed transactions");
    }
  
    if (largeTransferCount > 3) {
      riskScore += 15;
      riskSignals.push("Multiple large transfers detected (over 1000 HBAR each)");
    }
  
    if (counterparties.size > 50) {
      riskScore += 10;
      riskSignals.push("High counterparty count - interacts with many unique accounts");
    }
  
    const frozenTokens = tokens.filter(t => t.freeze_status === "FROZEN");
    if (frozenTokens.length > 0) {
      riskScore += 25;
      riskSignals.push("Account has " + frozenTokens.length + " frozen token relationship(s)");
    }
  
    const revokedKyc = tokens.filter(t => t.kyc_status === "REVOKED");
    if (revokedKyc.length > 0) {
      riskScore += 30;
      riskSignals.push("KYC has been REVOKED for " + revokedKyc.length + " token(s)");
    }
  
    if (account.balance?.balance === 0 && transactions.length > 10) {
      riskScore += 10;
      riskSignals.push("Zero HBAR balance despite significant transaction history");
    }
  
    if (riskSignals.length === 0) {
      riskSignals.push("No on-chain risk signals detected");
    }
  
    const riskLevel = riskScore >= 50 ? "HIGH" : riskScore >= 20 ? "MEDIUM" : "LOW";
  
    return {
      account_id: hederaId,
      input: args.account_id,
      input_type: resolved.inputType,
      screening_result: riskLevel === "HIGH" ? "FLAGGED" : riskLevel === "MEDIUM" ? "REVIEW" : "CLEAR",
      risk_score: riskScore,
      risk_level: riskLevel,
      risk_signals: riskSignals,
      account_profile: {
        age_days: ageDays,
        hbar_balance: account.balance?.balance
          ? (account.balance.balance / 100000000).toFixed(4) + " HBAR"
          : "unknown",
        total_transactions_sampled: transactions.length,
        failed_transactions: failedTxCount,
        unique_counterparties: counterparties.size,
        large_transfers: largeTransferCount,
        token_relationships: tokens.length,
        frozen_tokens: frozenTokens.length,
        kyc_revoked_tokens: revokedKyc.length,
      },
      disclaimer: "This screening is based on on-chain data patterns only. It does not constitute legal sanctions screening and should not be used as a sole compliance determination.",
      payment,
      timestamp: new Date().toISOString(),
    };
  }

• src/modules/identity/tools.js:62-72 (schema)

  Input schema definition for the identity_check_sanctions tool.

    name: "identity_check_sanctions",
    description: "Screen a Hedera account against on-chain risk signals including transaction patterns, counterparty risk, and known flagged accounts. Accepts both Hedera native IDs (0.0.123456) and EVM addresses (0x...). Costs 1.0 HBAR.",
    inputSchema: {
      type: "object",
      properties: {
        account_id: { type: "string", description: "Hedera account ID (e.g. 0.0.123456) or EVM address (0x...)" },
        api_key: { type: "string", description: "Your HederaIntel API key" },
      },
      required: ["account_id", "api_key"],
    },
  },