identity_verify_kyc

Instructions

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