{"skill":{"slug":"eth-readonly","displayName":"Ethereum Readonly","summary":"Read-only Ethereum blockchain queries — blocks, transactions, balances, contracts, logs via RPC and Etherscan APIs","description":"---\nname: eth-readonly\ndescription: Read-only Ethereum blockchain queries — blocks, transactions, balances, contracts, logs via RPC and Etherscan APIs\nuser-invocable: true\nhomepage: https://github.com/Fork-Development-Corp/openclaw-web3-skills/tree/master/eth-readonly\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"cast\",\"curl\"]},\"tipENS\":\"apexfork.eth\"}}\n---\n\n# Read-Only Ethereum Queries\n\nYou are a read-only Ethereum assistant. You help the user query blockchain state, inspect historical data, and explore contracts. **This skill is purely for reading data — no wallet required, no transactions sent.** Prefer Foundry's `cast` when available on PATH; otherwise construct raw JSON-RPC calls via `curl`.\n\n## Safety First\n\n**This skill is READ-ONLY.** No private keys, no wallets, no transaction signing. You can safely explore blockchain data without any risk of spending funds or exposing secrets.\n\n## RPC Configuration\n\n### Public RPC Endpoints (Instant Access)\n\n**Free public endpoints** (no API key required):\n```bash\n# Ethereum mainnet\nexport ETH_RPC_URL=\"https://ethereum.publicnode.com\"\nexport ETH_RPC_URL=\"https://rpc.ankr.com/eth\" \nexport ETH_RPC_URL=\"https://eth.llamarpc.com\"\n\n# Sepolia testnet  \nexport SEPOLIA_RPC_URL=\"https://rpc.ankr.com/eth_sepolia\"\nexport SEPOLIA_RPC_URL=\"https://ethereum-sepolia.publicnode.com\"\n```\n\n**Major providers** (require API keys):\n```bash\n# Infura\nexport ETH_RPC_URL=\"https://mainnet.infura.io/v3/${INFURA_PROJECT_ID}\"\n\n# Alchemy  \nexport ETH_RPC_URL=\"https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}\"\n\n# QuickNode\nexport ETH_RPC_URL=\"https://${QUICKNODE_ENDPOINT}.quiknode.pro/${QUICKNODE_TOKEN}/\"\n```\n\n**Local node** (if running your own):\n```bash\nexport ETH_RPC_URL=\"http://localhost:8545\"\n```\n\n### Usage Pattern\n```bash\n# Use environment variable\ncast block-number --rpc-url $ETH_RPC_URL\n\n# Or specify directly\ncast balance vitalik.eth --rpc-url https://ethereum.publicnode.com\n```\n\n**⚠️ Rate Limits:** Public endpoints have limits. Infura free: 100k requests/day. Alchemy free: 300M compute units/month. Use narrow ranges for log queries.\n\n## Chain ID Check\n\nAlways verify chain before any transaction:\n\n```bash\ncast chain-id --rpc-url $ETH_RPC_URL\n```\n\nCommon chain IDs: 1 (mainnet), 11155111 (sepolia), 17000 (holesky).\n\n## Detecting Available Tools\n\n```bash\ncommand -v cast && echo \"cast available\" || echo \"using curl fallback\"\n```\n\n## Querying State\n\n### Instant Exploration Examples\n\n**Get latest block (no API key needed):**\n```bash\ncast block-number --rpc-url https://ethereum.publicnode.com\n```\n\n**Check Vitalik's ETH balance:**\n```bash\ncast balance vitalik.eth --rpc-url https://ethereum.publicnode.com\n# Output: 2139127306712808209 (wei) = ~2139 ETH\n```\n\n**Look up a recent transaction:**\n```bash\ncast tx 0x... --rpc-url https://ethereum.publicnode.com\n```\n\n### Common Query Patterns\n\n```bash\n# Account balance (using env var)\ncast balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --rpc-url $ETH_RPC_URL\n\n# Transaction receipt\ncast receipt 0xTXHASH --rpc-url $ETH_RPC_URL\n\n# Contract code\ncast code 0xA0b86a33E6441929FD1F423c7ecE8F6DD15fA5E3 --rpc-url $ETH_RPC_URL  # USDC\n\n# ENS resolution\ncast resolve-name vitalik.eth --rpc-url $ETH_RPC_URL\ncast lookup-address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --rpc-url $ETH_RPC_URL\n```\n\n**curl JSON-RPC equivalents:**\n```bash\n# Block number\ncurl -s -X POST https://ethereum.publicnode.com \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"eth_blockNumber\",\"id\":1}'\n\n# Balance  \ncurl -s -X POST $ETH_RPC_URL \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"eth_getBalance\",\"params\":[\"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\",\"latest\"],\"id\":1}'\n```\n\n### Nonce (Account Transaction Count)\n\nUseful for debugging stuck or pending transactions:\n\n**cast:**\n```bash\n# Confirmed nonce\ncast nonce 0xADDRESS --rpc-url http://localhost:8545\n\n# Pending nonce (includes mempool txs)\ncast nonce 0xADDRESS --block pending --rpc-url http://localhost:8545\n```\n\n**curl:**\n```bash\ncurl -s -X POST http://localhost:8545 \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"eth_getTransactionCount\",\"params\":[\"0xADDRESS\",\"latest\"],\"id\":1}'\n```\n\nIf confirmed nonce < pending nonce, there are transactions in the mempool. For transaction management and replacement, see the `/foundry` skill.\n\n## Calling Contracts (Read-Only)\n\n**cast:**\n```bash\ncast call 0xCONTRACT \"balanceOf(address)\" 0xADDRESS --rpc-url http://localhost:8545\n```\n\n**curl (eth_call):**\n```bash\ncurl -s -X POST http://localhost:8545 \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"eth_call\",\"params\":[{\"to\":\"0xCONTRACT\",\"data\":\"0xABI_ENCODED_DATA\"},\"latest\"],\"id\":1}'\n```\n\nUse `cast calldata` to ABI-encode function calls when constructing raw data payloads.\n\n## Transaction Analysis (Read-Only)\n\n**Look up transaction details:**\n```bash\ncast tx 0xTXHASH --rpc-url $ETH_RPC_URL\ncast receipt 0xTXHASH --rpc-url $ETH_RPC_URL\n```\n\n**Decode transaction data:**\n```bash\ncast 4byte-decode 0xCALLDATA\ncast abi-decode \"transfer(address,uint256)\" 0xOUTPUT\n```\n\n## Gas Price Analysis\n\n**Current gas prices:**\n```bash\n# Via Etherscan\ncurl -s \"https://api.etherscan.io/api?module=gastracker&action=gasoracle&apikey=$ETHERSCAN_API_KEY\" | jq '.result'\n\n# Via RPC\ncast gas-price --rpc-url $ETH_RPC_URL\ncast base-fee --rpc-url $ETH_RPC_URL\n```\n\n## Event Log Queries\n\n**⚠️ REQUIRED: Always specify contract address and narrow block ranges.** Full-range queries can exhaust RPC limits instantly.\n\n```bash\n# Good: specific contract + block range\ncast logs 0xA0b86a33E6441929FD1F423c7ecE8F6DD15fA5E3 --from-block 19000000 --to-block 19001000 \\\n  \"Transfer(address,address,uint256)\" --rpc-url $ETH_RPC_URL\n\n# BAD: will likely fail on public RPCs\ncast logs --from-block 0 --to-block latest \"Transfer(address,address,uint256)\"\n```\n\nFor curl, always include `\"address\": \"0xCONTRACT\"` and specific `fromBlock`/`toBlock` in the filter object.\n\n\n## Etherscan API Integration\n\n**Setup:**\n```bash\nexport ETHERSCAN_API_KEY=\"your_api_key_here\"  # Get free key at etherscan.io/apis\n```\n\n### Contract Source Code\n```bash\n# Get verified contract source\ncurl -s \"https://api.etherscan.io/api?module=contract&action=getsourcecode&address=0xA0b86a33E6441929FD1F423c7ecE8F6DD15fA5E3&apikey=$ETHERSCAN_API_KEY\" | jq '.result[0].SourceCode'\n\n# Check if contract is verified\ncurl -s \"https://api.etherscan.io/api?module=contract&action=getabi&address=0xA0b86a33E6441929FD1F423c7ecE8F6DD15fA5E3&apikey=$ETHERSCAN_API_KEY\"\n```\n\n### Transaction History\n```bash  \n# Get account transactions (latest 10)\ncurl -s \"https://api.etherscan.io/api?module=account&action=txlist&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&startblock=0&endblock=99999999&page=1&offset=10&sort=desc&apikey=$ETHERSCAN_API_KEY\" | jq '.result[] | {hash: .hash, value: .value, gas: .gas}'\n\n# Get ERC-20 token transfers\ncurl -s \"https://api.etherscan.io/api?module=account&action=tokentx&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&page=1&offset=10&sort=desc&apikey=$ETHERSCAN_API_KEY\" | jq '.result[] | {tokenName: .tokenName, tokenSymbol: .tokenSymbol, value: .value}'\n```\n\n### Gas Tracker\n```bash\n# Current gas prices\ncurl -s \"https://api.etherscan.io/api?module=gastracker&action=gasoracle&apikey=$ETHERSCAN_API_KEY\" | jq '.result'\n\n# Output: {\"SafeGasPrice\": \"12\", \"ProposeGasPrice\": \"13\", \"FastGasPrice\": \"14\"}\n```\n\n### Block & Network Stats\n```bash\n# Get block by number\ncurl -s \"https://api.etherscan.io/api?module=proxy&action=eth_getBlockByNumber&tag=0x10d4f&boolean=true&apikey=$ETHERSCAN_API_KEY\" | jq '.result | {number: .number, timestamp: .timestamp, gasUsed: .gasUsed}'\n\n# Total ETH supply  \ncurl -s \"https://api.etherscan.io/api?module=stats&action=ethsupply&apikey=$ETHERSCAN_API_KEY\" | jq '.result'\n```\n\n**Rate limits:** Free tier: 5 calls/second, 100k calls/day. Pro tier available.","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":1054,"installsAllTime":40,"installsCurrent":4,"stars":1,"versions":1},"createdAt":1771219229389,"updatedAt":1778491552996},"latestVersion":{"version":"1.0.0","createdAt":1771219229389,"changelog":"- Initial release of eth-readonly skill for read-only Ethereum blockchain queries.\n- Supports querying blocks, transactions, account balances, contract data, and logs via Foundry's cast or raw JSON-RPC (curl).\n- Integrates Etherscan API for additional endpoints such as contract source, ABI, transaction history, and gas prices.\n- No wallet or private keys required — purely read-only; no transactions or signing.\n- Public and major provider RPC endpoint configuration supported.\n- Complete usage documentation with example commands for both cast and curl.","license":null},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"apexfork","userId":"s17fckz2xmvepa04w7e65a9bv188457m","displayName":"J. Campbell","image":"https://avatars.githubusercontent.com/u/363026?v=4"},"moderation":null}