Hedera Toolbox

Instructions

Implementation Reference

• src/modules/token/tools.js:254-295 (handler)

  The handler logic for the token_monitor tool, which calculates whale concentration and fetches token balance data.

  if (name === "token_monitor") {
    const payment = chargeForTool("token_monitor", args.api_key);
    const base = getMirrorNodeBase();
    const limit = Math.min(args.limit || 25, 100);
  
    const tokenRes = await axios.get(`${base}/api/v1/tokens/${args.token_id}`);
    const token = tokenRes.data;
    const decimals = parseInt(token.decimals || 0);
    const totalSupply = parseInt(token.total_supply || 0);
  
    // Fetch holder balances — fetch max and sort client-side by balance desc
    const balRes = await axios.get(
      `${base}/api/v1/tokens/${args.token_id}/balances?limit=100&account.balance.gt=0`
    ).catch(() => ({ data: { balances: [] } }));
    const holders = (balRes.data.balances || []).sort((a, b) => parseInt(b.balance || 0) - parseInt(a.balance || 0));
  
    // SaucerSwap price
    const saucerTokens = await getSaucerSwapTokens();
    const saucerToken = saucerTokens.find(t => t.id === args.token_id);
  
    // Top holders / whale detection
    const top10Balance = holders.slice(0, 10).reduce((s, b) => s + parseInt(b.balance || 0), 0);
    const concentrationPct = totalSupply > 0 ? (top10Balance / totalSupply * 100).toFixed(1) : 0;
  
    const whales = holders.slice(0, limit).map((b, i) => ({
      rank: i + 1,
      account: b.account,
      balance: (parseInt(b.balance) / Math.pow(10, decimals)).toLocaleString(),
      pct_supply: totalSupply > 0 ? (parseInt(b.balance) / totalSupply * 100).toFixed(2) + "%" : "unknown",
      is_treasury: b.account === token.treasury_account_id,
    }));
  
    // Activity signals
    const signals = [];
    if (parseFloat(concentrationPct) > 80) signals.push("HIGH CONCENTRATION - Top 10 holders control " + concentrationPct + "% of supply");
    if (holders.length < 20) signals.push("LOW DISTRIBUTION - Token held by fewer than 20 accounts");
    if (token.pause_status === "PAUSED") signals.push("WARNING - Token is currently PAUSED");
    if (saucerToken && !saucerToken.dueDiligenceComplete) signals.push("DEX CAUTION - SaucerSwap due diligence not complete");
    if (signals.length === 0) signals.push("No unusual patterns detected");
  
    return {
      token_id: args.token_id,

• src/modules/token/tools.js:81-92 (schema)

  The tool registration definition and schema for token_monitor.

    name: "token_monitor",
    description: "Monitor recent token transfer activity, whale movements, and unusual trading patterns for a Hedera token. Costs 0.2 HBAR.",
    inputSchema: {
      type: "object",
      properties: {
        token_id: { type: "string", description: "Hedera token ID to monitor (e.g. 0.0.123456)" },
        limit: { type: "number", description: "Number of recent transactions to return (default 25, max 100)" },
        api_key: { type: "string", description: "Your HederaIntel API key" },
      },
      required: ["token_id", "api_key"],
    },
  },