identity_verify_kyc

Verify KYC status of Hedera accounts for token compliance. Check grant status and verification history using Hedera Toolbox's blockchain data access.

Instructions

Check the KYC status of a Hedera account for one or more tokens. Returns KYC grant status and verification history. Costs 0.2 HBAR.

Input Schema

TableJSON Schema

Name	Required	Description
`api_key`	Yes	Your HederaIntel API key
`account_id`	Yes	Hedera account ID to check KYC for
`token_id`	No	Optional token ID to check KYC status for a specific token

Implementation Reference

src/modules/identity/tools.js:164-221 (handler)

The identity_verify_kyc tool handler, which fetches an account's token list from the Hedera Mirror Node and analyzes KYC and freeze statuses.

if (name === "identity_verify_kyc") {
  const payment = chargeForTool("identity_verify_kyc", args.api_key);
  const base = getMirrorNodeBase();

  const resolved = await resolveAccountInput(args.account_id, base);
  const hederaId = resolved.hederaId;

  // Fetch account token relationships
  const tokenRes = await axios.get(
    `${base}/api/v1/accounts/${hederaId}/tokens?limit=100&order=desc`
  ).catch(() => ({ data: { tokens: [] } }));
  const tokens = tokenRes.data.tokens || [];

  // Filter by token_id if provided
  const filtered = args.token_id
    ? tokens.filter(t => t.token_id === args.token_id)
    : tokens;

  const kycResults = filtered.map(t => ({
    token_id: t.token_id,
    kyc_status: t.kyc_status || "NOT_APPLICABLE",
    kyc_granted: t.kyc_status === "GRANTED",
    freeze_status: t.freeze_status || "NOT_APPLICABLE",
    balance: t.balance,
  }));

  const grantedCount = kycResults.filter(r => r.kyc_granted).length;
  const revokedCount = kycResults.filter(r => r.kyc_status === "REVOKED").length;
  const notApplicableCount = kycResults.filter(r => r.kyc_status === "NOT_APPLICABLE").length;

  // Fetch account info for context
  const accountRes = await axios.get(`${base}/api/v1/accounts/${hederaId}`)
    .catch(() => ({ data: {} }));
  const account = accountRes.data;

  return {
    account_id: hederaId,
    input: args.account_id,
    input_type: resolved.inputType,
    token_filter: args.token_id || null,
    total_token_relationships: tokens.length,
    kyc_summary: {
      granted: grantedCount,
      revoked: revokedCount,
      not_applicable: notApplicableCount,
      total_checked: kycResults.length,
    },
    kyc_details: kycResults,
    account_memo: account.memo || null,
    note: notApplicableCount === kycResults.length
      ? "All tokens show NOT_APPLICABLE - these tokens do not use Hedera KYC keys."
      : grantedCount > 0
      ? "Account has KYC granted for " + grantedCount + " token(s)."
      : "No KYC grants found for this account.",
    payment,
    timestamp: new Date().toISOString(),
  };
}

src/modules/identity/tools.js:49-60 (schema)

Input schema definition for the identity_verify_kyc tool, specifying required account_id, optional token_id, and API key.

  name: "identity_verify_kyc",
  description: "Check the KYC status of a Hedera account for one or more tokens. Returns KYC grant status and verification history. Accepts both Hedera native IDs (0.0.123456) and EVM addresses (0x...). Costs 0.5 HBAR.",
  inputSchema: {
    type: "object",
    properties: {
      account_id: { type: "string", description: "Hedera account ID (e.g. 0.0.123456) or EVM address (0x...)" },
      token_id: { type: "string", description: "Optional token ID to check KYC status for a specific token" },
      api_key: { type: "string", description: "Your HederaIntel API key" },
    },
    required: ["account_id", "api_key"],
  },
},

Hedera Toolbox