identity_check_sanctions

Screen Hedera accounts against on-chain risk signals including transaction patterns, counterparty risk, and known flagged accounts to identify potential sanctions violations.

Instructions

Screen a Hedera account against on-chain risk signals including transaction patterns, counterparty risk, and known flagged accounts. Costs 0.5 HBAR.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`api_key`	Yes	Your HederaIntel API key
`account_id`	Yes	Hedera account ID to screen

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"],
  },
},

Hedera Toolbox