Execute a read-only smart contract call without creating a transaction.

Args:

• to (string): Contract address to call (20-byte hex, e.g., '0x...').

• data (string): ABI-encoded function call data (hex string starting with 0x).

• network (string, optional): Ethereum network to query. Defaults to 'mainnet'.

Returns:

• Hexadecimal string containing the return value of the executed contract method.

Examples:

• "Read ERC20 balance": { "to": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "data": "0x70a08231000000000000000000000000..." }

• "Query on Sepolia": { "to": "0x...", "data": "0x...", "network": "sepolia" }

Errors:

• InvalidParams: When 'to' address or 'data' format is invalid.

• InternalError: When contract execution reverts or Infura API fails.

Get the chain ID of an Ethereum network for EIP-155 transaction signing.

Args:

• network (string, optional): Ethereum network to query. Defaults to 'mainnet'.

Returns:

• Hexadecimal string representing the chain ID (e.g., '0x1' for mainnet, '0xaa36a7' for Sepolia).

Examples:

• "Get mainnet chain ID": {}

• "Get Sepolia chain ID": { "network": "sepolia" }

Errors:

• InternalError: When Infura API is unavailable or returns an error.

Estimate the gas required to execute a transaction without broadcasting it.

Args:

• from (string): Sender address (20-byte hex, e.g., '0x...').

• to (string): Recipient address (20-byte hex, e.g., '0x...').

• value (string): Amount to send in wei as hex (e.g., '0xde0b6b3a7640000' for 1 ETH).

• network (string, optional): Ethereum network to query. Defaults to 'mainnet'.

Returns:

• Hexadecimal string representing estimated gas units (e.g., '0x5208' for 21000 gas).

Examples:

• "Estimate ETH transfer": { "from": "0xYourAddress", "to": "0xRecipient", "value": "0xde0b6b3a7640000" }

• "Estimate on Sepolia": { "from": "0x...", "to": "0x...", "value": "0x0", "network": "sepolia" }

Errors:

• InvalidParams: When address format or value format is invalid.

• InternalError: When transaction would revert or Infura API fails.

Get the ETH balance of an address at a specific block.

Args:

• address (string): Ethereum address to check (20-byte hex, e.g., '0x...').

• tag (string): Block reference - 'latest', 'earliest', or 'pending'.

• network (string, optional): Ethereum network to query. Defaults to 'mainnet'.

Returns:

• Hexadecimal string representing balance in wei (e.g., '0xde0b6b3a7640000' for 1 ETH).

Examples:

• "Get current balance": { "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "tag": "latest" }

• "Check Sepolia balance": { "address": "0x...", "tag": "latest", "network": "sepolia" }

Errors:

• InvalidParams: When address format is invalid or tag is not recognized.

• InternalError: When Infura API is unavailable or returns an error.

Get detailed block information using its hash.

Args:

• blockHash (string): 32-byte block hash (66 chars with 0x prefix).

• fullTransactions (boolean): If true, returns full tx objects; if false, returns tx hashes only.

• network (string, optional): Ethereum network to query. Defaults to 'mainnet'.

Returns:

• Block object with number, hash, parentHash, transactions, gasUsed, timestamp, etc. Returns null if block not found.

Examples:

• "Get block with tx hashes": { "blockHash": "0x...", "fullTransactions": false }

• "Get block with full txs": { "blockHash": "0x...", "fullTransactions": true, "network": "mainnet" }

Errors:

• InvalidParams: When blockHash format is invalid (not 66 char hex).

• InternalError: When Infura API is unavailable or returns an error.

Get detailed block information using its number or tag.

Args:

• blockNumber (string): Block number as hex (e.g., '0x10d4f') or tag ('latest', 'earliest', 'pending').

• fullTransactions (boolean): If true, returns full tx objects; if false, returns tx hashes only.

• network (string, optional): Ethereum network to query. Defaults to 'mainnet'.

Returns:

• Block object with number, hash, parentHash, transactions, gasUsed, timestamp, etc. Returns null if block not found.

Examples:

• "Get latest block": { "blockNumber": "latest", "fullTransactions": false }

• "Get specific block with full txs": { "blockNumber": "0x10d4f", "fullTransactions": true }

Errors:

• InvalidParams: When blockNumber format is invalid.

• InternalError: When Infura API is unavailable or returns an error.

Fetch the latest block number from an Ethereum network.

Args:

• network (string, optional): Ethereum network to query. Defaults to 'mainnet'.

Returns:

• Hexadecimal string representing the current block number (e.g., '0x10d4f').

Examples:

• "Get mainnet block number": {}

• "Get Sepolia block number": { "network": "sepolia" }

Errors:

• InternalError: When Infura API is unavailable or returns an error.

Get the number of transactions in a block identified by its hash.

Args:

• blockHash (string): 32-byte block hash (66 chars with 0x prefix).

• network (string, optional): Ethereum network to query. Defaults to 'mainnet'.

Returns:

• Hexadecimal string representing transaction count (e.g., '0x10' for 16 transactions). Returns null if block not found.

Examples:

• "Count txs in block": { "blockHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238" }

• "Query Sepolia block": { "blockHash": "0x...", "network": "sepolia" }

Errors:

• InvalidParams: When blockHash format is invalid (not 66 char hex).

• InternalError: When Infura API is unavailable or returns an error.

Get the number of transactions in a block identified by its number or tag.

Args:

• blockNumber (string): Block number as hex (e.g., '0x10d4f') or tag ('latest', 'earliest', 'pending').

• network (string, optional): Ethereum network to query. Defaults to 'mainnet'.

Returns:

• Hexadecimal string representing transaction count (e.g., '0x10' for 16 transactions). Returns null if block not found.

Examples:

• "Count txs in latest block": { "blockNumber": "latest" }

• "Count txs in specific block": { "blockNumber": "0x10d4f", "network": "mainnet" }

Errors:

• InvalidParams: When blockNumber format is invalid.

• InternalError: When Infura API is unavailable or returns an error.

Get the deployed bytecode of a smart contract.

Args:

• contractAddress (string): Contract address (20-byte hex, e.g., '0x...').

• network (string, optional): Ethereum network to query. Defaults to 'mainnet'.

Returns:

• Hexadecimal string containing the contract bytecode. Returns '0x' if address is not a contract or has no code.

Examples:

• "Get USDT contract code": { "contractAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7" }

• "Check Sepolia contract": { "contractAddress": "0x...", "network": "sepolia" }

Errors:

• InvalidParams: When contractAddress format is invalid.

• InternalError: When Infura API is unavailable or returns an error.

Get historical gas fee data for EIP-1559 fee estimation.

Args:

• blockCount (string): Number of blocks to analyze as hex (e.g., '0x4' for 4 blocks).

• newestBlock (string): Latest block to include ('latest', 'pending', or hex block number).

• rewardPercentiles (array): Percentiles for priority fee sampling (e.g., [25, 50, 75]).

• network (string, optional): Ethereum network to query. Defaults to 'mainnet'.

Returns:

• Object with baseFeePerGas array, gasUsedRatio array, oldestBlock, and reward matrix.

Examples:

• "Get last 4 blocks fee history": { "blockCount": "0x4", "newestBlock": "latest", "rewardPercentiles": [25, 50, 75] }

• "Query Sepolia fees": { "blockCount": "0xa", "newestBlock": "latest", "rewardPercentiles": [10, 50, 90], "network": "sepolia" }

Errors:

• InvalidParams: When blockCount format, newestBlock, or rewardPercentiles are invalid.

• InternalError: When Infura API is unavailable or returns an error.

Get the current gas price in wei for legacy (non-EIP-1559) transactions.

Args:

• network (string, optional): Ethereum network to query. Defaults to 'mainnet'.

Returns:

• Hexadecimal string representing gas price in wei (e.g., '0x3b9aca00' for 1 Gwei).

Examples:

• "Get mainnet gas price": {}

• "Get Sepolia gas price": { "network": "sepolia" }

Errors:

• InternalError: When Infura API is unavailable or returns an error.

Query event logs emitted by smart contracts with flexible filters. Supports pagination for large result sets.

Args:

• fromBlock (string): Start block as hex (e.g., '0x10d4f') or tag ('latest', 'earliest', 'pending').

• toBlock (string): End block as hex or tag.

• address (string, optional): Contract address to filter logs from.

• topics (array, optional): Array of 32-byte topic filters for indexed event parameters.

• network (string, optional): Ethereum network to query. Defaults to 'mainnet'.

• limit (integer, optional): Maximum logs to return (1-10000). Defaults to 1000.

• offset (integer, optional): Number of logs to skip for pagination. Defaults to 0.

Returns:

• Object with 'logs' array and 'pagination' metadata (total, count, offset, limit, has_more, next_offset).

Examples:

• "Get all logs in block range": { "fromBlock": "0x10d4f", "toBlock": "0x10d50" }

• "Filter by contract and topic": { "fromBlock": "latest", "toBlock": "latest", "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"] }

• "Paginate results": { "fromBlock": "0x10d4f", "toBlock": "0x10d50", "limit": 100, "offset": 0 }

Errors:

• InvalidParams: When block tags or address format is invalid.

• InternalError: When query range is too large or Infura API fails.

Returns the current Ethereum protocol version used by the node. Useful for checking client compatibility and supported features.

Args:

• network (string, optional): Ethereum network to query, defaults to 'mainnet'

Returns:

• Hex-encoded string representing the protocol version number (e.g., '0x41' for version 65)

Examples:

• "Get mainnet protocol version": {}

• "Get Sepolia protocol version": { "network": "sepolia" }

Errors:

• InternalError: When Infura API is unavailable or method not supported

Read the raw value from a specific storage slot of a contract.

Args:

• address (string): Contract address (20-byte hex, e.g., '0x...').

• position (string): Storage slot index as hex (e.g., '0x0' for slot 0).

• network (string, optional): Ethereum network to query. Defaults to 'mainnet'.

Returns:

• 32-byte hexadecimal string representing the storage value at the given position.

Examples:

• "Read slot 0": { "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "position": "0x0" }

• "Read mapping slot": { "address": "0x...", "position": "0x1", "network": "sepolia" }

Errors:

• InvalidParams: When address or position format is invalid.

• InternalError: When Infura API is unavailable or returns an error.

Get a transaction by its position within a block identified by hash.

Args:

• blockHash (string): 32-byte block hash (66 chars with 0x prefix).

• index (string): Transaction index position as hex (e.g., '0x0' for first tx).

• network (string, optional): Ethereum network to query. Defaults to 'mainnet'.

Returns:

• Transaction object with hash, from, to, value, gas, gasPrice, input, nonce, etc. Returns null if not found.

Examples:

• "Get first tx in block": { "blockHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238", "index": "0x0" }

• "Get third tx on Sepolia": { "blockHash": "0x...", "index": "0x2", "network": "sepolia" }

Errors:

• InvalidParams: When blockHash or index format is invalid.

• InternalError: When Infura API is unavailable or returns an error.

Retrieves a transaction by its position within a specific block using block number and transaction index.

Args:

• blockNumber (string): Block number as hex (e.g., '0x10d4f') or tag ('latest', 'earliest', 'pending')

• transactionIndex (string): Zero-based position of the transaction in the block as hex (e.g., '0x0')

• network (string, optional): Ethereum network to query, defaults to 'mainnet'

Returns:

• Transaction object with hash, from, to, value, gas, gasPrice, input, nonce, blockHash, blockNumber, transactionIndex; null if not found

Examples:

• "Get first transaction in latest block": { "blockNumber": "latest", "transactionIndex": "0x0" }

• "Get transaction at index 5 in specific block": { "blockNumber": "0x10d4f", "transactionIndex": "0x5" }

Errors:

• InvalidParams: When blockNumber or transactionIndex format is invalid

• InternalError: When Infura API is unavailable

Retrieves detailed transaction information using its unique transaction hash.

Args:

• transactionHash (string): 32-byte transaction hash in hex format (e.g., '0xabc123...')

• network (string, optional): Ethereum network to query, defaults to 'mainnet'

Returns:

• Transaction object with hash, from, to, value, gas, gasPrice, input, nonce, blockHash, blockNumber, transactionIndex; null if transaction not found or still pending

Examples:

• "Get transaction details": { "transactionHash": "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b" }

• "Query on Sepolia testnet": { "transactionHash": "0xabc...", "network": "sepolia" }

Errors:

• InvalidParams: When transactionHash is not a valid 32-byte hex string

• InternalError: When Infura API is unavailable

Returns the number of transactions sent from an address (nonce). Useful for determining the next nonce for sending transactions.

Args:

• address (string): 20-byte Ethereum address in hex format (e.g., '0x742d35Cc6634C0532925a3b844Bc9e7595f...')

• tag (string, optional): Block tag - 'latest', 'earliest', or 'pending', defaults to 'latest'

• network (string, optional): Ethereum network to query, defaults to 'mainnet'

Returns:

• Hex-encoded integer representing the number of transactions sent from the address

Examples:

• "Get current nonce for address": { "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" }

• "Get pending transaction count": { "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "tag": "pending" }

Errors:

• InvalidParams: When address format is invalid or tag is not a valid block tag

• InternalError: When Infura API is unavailable

Retrieves the receipt of a mined transaction, including status, gas used, and logs. Only available for transactions that have been included in a block.

Args:

• transactionHash (string): 32-byte transaction hash in hex format (e.g., '0xabc123...')

• network (string, optional): Ethereum network to query, defaults to 'mainnet'

Returns:

• Receipt object with status (1=success, 0=failure), blockHash, blockNumber, transactionIndex, from, to, contractAddress (if contract creation), cumulativeGasUsed, gasUsed, effectiveGasPrice, logs array, logsBloom; null if transaction pending or not found

Examples:

• "Get receipt to check if transaction succeeded": { "transactionHash": "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b" }

• "Get receipt on Sepolia": { "transactionHash": "0xabc...", "network": "sepolia" }

Errors:

• InvalidParams: When transactionHash is not a valid 32-byte hex string

• InternalError: When Infura API is unavailable

Retrieves an uncle (ommer) block by block hash and uncle index position. Uncles are valid blocks that were not included in the main chain but are referenced by main chain blocks.

Args:

• blockHash (string): 32-byte hash of the block containing the uncle (e.g., '0xabc123...')

• index (string): Zero-based uncle index position as hex (e.g., '0x0' for first uncle)

• network (string, optional): Ethereum network to query, defaults to 'mainnet'

Returns:

• Uncle block object with hash, parentHash, sha3Uncles, miner, stateRoot, number, gasLimit, gasUsed, timestamp, difficulty, nonce; null if not found

Examples:

• "Get first uncle in block": { "blockHash": "0xb3b20624f8f0f86eb50dd04688409e5cea4bd02d700bf6e79e9384d47d6a5a35", "index": "0x0" }

Errors:

• InvalidParams: When blockHash or index format is invalid

• InternalError: When Infura API is unavailable

Retrieves an uncle (ommer) block by block number and uncle index position. Uncles are valid blocks that were not included in the main chain but are referenced by main chain blocks.

Args:

• blockNumber (string): Block number as hex (e.g., '0x10d4f') or tag ('latest', 'earliest', 'pending')

• index (string): Zero-based uncle index position as hex (e.g., '0x0' for first uncle)

• network (string, optional): Ethereum network to query, defaults to 'mainnet'

Returns:

• Uncle block object with hash, parentHash, sha3Uncles, miner, stateRoot, number, gasLimit, gasUsed, timestamp, difficulty, nonce; null if not found

Examples:

• "Get first uncle in specific block": { "blockNumber": "0x29c", "index": "0x0" }

• "Get uncle from latest block": { "blockNumber": "latest", "index": "0x0" }

Errors:

• InvalidParams: When blockNumber or index format is invalid

• InternalError: When Infura API is unavailable

Returns the number of uncle (ommer) blocks in a specific block identified by its hash.

Args:

• blockHash (string): 32-byte hash of the block to query (e.g., '0xabc123...')

• network (string, optional): Ethereum network to query, defaults to 'mainnet'

Returns:

• Hex-encoded integer representing the number of uncles in the block (e.g., '0x0' for no uncles, '0x2' for two uncles)

Examples:

• "Get uncle count for block": { "blockHash": "0xb3b20624f8f0f86eb50dd04688409e5cea4bd02d700bf6e79e9384d47d6a5a35" }

• "Query on Sepolia": { "blockHash": "0xabc...", "network": "sepolia" }

Errors:

• InvalidParams: When blockHash is not a valid 32-byte hex string

• InternalError: When Infura API is unavailable

Returns the number of uncle (ommer) blocks in a specific block identified by its number or tag.

Args:

• blockNumber (string, optional): Block number as hex (e.g., '0x10d4f') or tag ('latest', 'earliest', 'pending'), defaults to 'latest'

• network (string, optional): Ethereum network to query, defaults to 'mainnet'

Returns:

• Hex-encoded integer representing the number of uncles in the block (e.g., '0x0' for no uncles, '0x2' for two uncles)

Examples:

• "Get uncle count for latest block": {}

• "Get uncle count for specific block": { "blockNumber": "0x29c" }

• "Query on Sepolia": { "blockNumber": "latest", "network": "sepolia" }

Errors:

• InvalidParams: When blockNumber format is invalid

• InternalError: When Infura API is unavailable

Returns the sync status of the Ethereum node. Useful for determining if the node is fully synced before relying on its data.

Args:

• network (string, optional): Ethereum network to query, defaults to 'mainnet'

Returns:

• false if the node is not syncing (fully synced)

• Object with startingBlock, currentBlock, and highestBlock (all hex-encoded) if syncing is in progress

Examples:

• "Check if mainnet node is synced": {}

• "Check Sepolia sync status": { "network": "sepolia" }

Errors:

• InternalError: When Infura API is unavailable

Returns the number of peers currently connected to the client. Useful for monitoring network connectivity and health.

Args:

• network (string, optional): Ethereum network to query, defaults to 'mainnet'

Returns:

• Hex-encoded integer representing the number of connected peers (e.g., '0x19' for 25 peers)

Examples:

• "Get mainnet peer count": {}

• "Get Sepolia peer count": { "network": "sepolia" }

Errors:

• InternalError: When Infura API is unavailable

Returns the current network ID. Useful for identifying which Ethereum network the node is connected to (1=mainnet, 11155111=sepolia, etc.).

Args:

• network (string, optional): Ethereum network to query, defaults to 'mainnet'

Returns:

• String representing the network ID (e.g., '1' for mainnet, '11155111' for Sepolia)

Examples:

• "Get mainnet network ID": {}

• "Verify Sepolia network ID": { "network": "sepolia" }

Errors:

• InternalError: When Infura API is unavailable

Returns whether the client is actively listening for network connections. Useful for checking node connectivity status.

Args:

• network (string, optional): Ethereum network to query, defaults to 'mainnet'

Returns:

• true if the client is listening for connections

• false if the client is not listening

Examples:

• "Check if mainnet node is listening": {}

• "Check Sepolia node status": { "network": "sepolia" }

Errors:

• InternalError: When Infura API is unavailable

Returns the current Ethereum client version string. Useful for identifying the node software and version being used.

Args:

• network (string, optional): Ethereum network to query, defaults to 'mainnet'

Returns:

• String containing the client name and version (e.g., 'Geth/v1.10.26-stable/linux-amd64/go1.18.5')

Examples:

• "Get mainnet client version": {}

• "Get Sepolia client version": { "network": "sepolia" }

Errors:

• InternalError: When Infura API is unavailable