onchain — read-only Base access for Claude Code

A rig that lets Claude Code talk to Base (chainid 8453) directly — balances, transfers, transaction status, contract state and source, and gas — through the official Blockscout MCP server. No API key, no signing, no key custody.

What this rig CAN do

• Read anything public on Base: native + ERC-20 balances, token transfer history, full transaction details (status, gas, logs, decoded transfers), block data, and current gas.
• Pull verified contract source and ABIs, and diff a deployed contract against source in your repo.
• Live contract state via read_contract (eth_call on view/pure functions) — simulate view functions, read on-chain state without an archive node.
• Answer via five named queries (the base-chain skill): deposit-check, tx-status, activity, contract-diff, gas-now.
• Reach 60+ other EVM chains through the same MCP (pass a different chain_id) — though this rig defaults to and is tuned for Base.

What this rig CANNOT do (by design)

• Sign, send, transfer, approve, deploy, or execute anything. There is no wallet and no signing capability, and there must never be one.
• Hold or read private keys / seed phrases. None are stored here.
• Give financial or investment advice.

It reads the chain. It never changes it.

Setup

rig hub use hub:connor/onchain      # if installed from the hub
# or clone/copy this folder, then:
cd onchain && claude

No credentials required — Blockscout needs no key. On first launch Claude Code loads the blockscout MCP from .mcp.json (pre-approved in .claude/settings.json).

Usage

Just ask, or invoke the skill's queries by name:

• "deposit-check 0x6B53…9755" → current USDC + native balance and recent inbound transfers.
• "tx-status 0x…" → confirmed/pending/failed, confirmations, gas, transfers.
• "activity 0x… 14" → 14-day in/out flows, counterparties, net change.
• "contract-diff 0x…" → verified on-chain source vs repo source.
• "gas-now" → current Base gas with a plain-English read.

Every answer states the as-of block height, respects token decimals (USDC = 6), adds USD only when a price is cheaply available, and says so rather than guessing when data is missing or stale.

Layout

onchain/
├── .mcp.json                     # blockscout (active) + etherscan (staged/disabled)
├── .claude/
│   ├── settings.json             # blockscout enabled + pre-allowed; etherscan disabled
│   └── skills/base-chain/SKILL.md
├── docs/onchain-tools.md         # full Blockscout MCP tool inventory + tier notes
├── CLAUDE.md                     # agent orientation
├── rig.toml                      # rig manifest
└── README.md

Data source & caveats

• Blockscout MCP (https://mcp.blockscout.com/mcp) — official, free, no key, read-only. Server version 1.26.0 as tested 2026-07-18.
• Explorer data is indexed, not the live tip — it can lag slightly. Every answer prints the as-of block height so lag is visible.
• Very large addresses (e.g. a token contract with millions of holders) can time out (HTTP 524); the skill retries once.

Fallback: activating Etherscan (paid)

An etherscan MCP is staged in .mcp.json but disabled. Etherscan's free tier covers Ethereum mainnet only — Base needs a paid plan (Lite $49/mo+, see https://etherscan.io/apis). To activate it as a second source:

1. Upgrade the Etherscan key to a paid plan.
2. Export ETHERSCAN_API_KEY (already in ~/.zshrc if you set it up).
3. Remove "etherscan" from disabledMcpjsonServers in .claude/settings.json.
4. Restart Claude Code.

The .mcp.json entry references the key only as ${ETHERSCAN_API_KEY} — no secret is ever written to a committed file.