contract_read
Read Hedera smart contract state without executing transactions. Get contract info, bytecode size, activity logs, and storage details for 0.1 HBAR per query.
Instructions
Read state from a Hedera smart contract - get contract info, bytecode size, recent activity, and storage details without executing a transaction. Costs 0.1 HBAR.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | Yes | Your HederaIntel API key | |
| contract_id | Yes | Hedera contract ID (e.g. 0.0.123456) or EVM address (0x...) |
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(), }; } - 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"], }, },