Hedera Toolbox

Instructions

Implementation Reference

• src/modules/contract/tools.js:169-236 (handler)

  The handler function for `contract_read` which interacts with the Hedera Mirror Node API to fetch contract data, recent call results, and state information.

  if (name === "contract_read") {
    const payment = chargeForTool("contract_read", args.api_key);
    const base = getMirrorNodeBase();
  
    // Fetch contract info
    const contractRes = await axios.get(`${base}/api/v1/contracts/${args.contract_id}`);
    const contract = contractRes.data;
  
    // Fetch recent contract results (calls)
    const resultsRes = await axios.get(
      `${base}/api/v1/contracts/${args.contract_id}/results?limit=10&order=desc`
    ).catch(() => ({ data: { results: [] } }));
    const results = resultsRes.data.results || [];
  
    // Fetch contract state entries count
    const stateRes = await axios.get(
      `${base}/api/v1/contracts/${args.contract_id}/state?limit=25`
    ).catch(() => ({ data: { state: [] } }));
    const stateEntries = stateRes.data.state || [];
  
    // Calculate contract age
    const createdAt = contract.created_timestamp
      ? new Date(parseFloat(contract.created_timestamp) * 1000)
      : null;
    const ageDays = createdAt
      ? Math.floor((Date.now() - createdAt.getTime()) / (1000 * 60 * 60 * 24))
      : null;
  
    // Recent callers
    const callers = [...new Set(results.map(r => r.from).filter(Boolean))];
  
    // Gas usage stats
    const gasUsed = results.map(r => parseInt(r.gas_used || 0));
    const avgGas = gasUsed.length > 0
      ? Math.round(gasUsed.reduce((a, b) => a + b, 0) / gasUsed.length)
      : null;
    const maxGas = gasUsed.length > 0 ? Math.max(...gasUsed) : null;
  
    return {
      contract_id: args.contract_id,
      evm_address: contract.evm_address || null,
      admin_key: contract.admin_key ? true : false,
      auto_renew_account: contract.auto_renew_account_id || null,
      auto_renew_period: contract.auto_renew_period || null,
      created_at: createdAt ? createdAt.toISOString() : null,
      age_days: ageDays,
      expiration_timestamp: contract.expiration_timestamp || null,
      memo: contract.memo || null,
      obtainer_account: contract.obtainer_account_id || null,
      proxy_account: contract.proxy_account_id || null,
      bytecode_size_bytes: contract.bytecode ? Math.round(contract.bytecode.length / 2) : null,
      file_id: contract.file_id || null,
      max_automatic_token_associations: contract.max_automatic_token_associations || 0,
      hbar_balance: contract.balance?.balance
        ? (contract.balance.balance / 100000000).toFixed(4) + " HBAR"
        : "0.0000 HBAR",
      recent_call_count: results.length,
      recent_callers: callers.slice(0, 5),
      gas_stats: {
        avg_gas_used: avgGas,
        max_gas_used: maxGas,
      },
      state_entry_count: stateEntries.length,
      deleted: contract.deleted || false,
      payment,
      timestamp: new Date().toISOString(),
    };
  }

• src/modules/contract/tools.js:124-135 (schema)

  The input schema for the `contract_read` tool defining the expected `contract_id` and `api_key`.

  {
    name: "contract_read",
    description: "Read state from a Hedera smart contract - get contract info, bytecode size, recent activity, and storage details without executing a transaction. Costs 0.2 HBAR.",
    inputSchema: {
      type: "object",
      properties: {
        contract_id: { type: "string", description: "Hedera contract ID (e.g. 0.0.123456) or EVM address (0x...)" },
        api_key: { type: "string", description: "Your HederaIntel API key" },
      },
      required: ["contract_id", "api_key"],
    },
  },