WalletChan RPC

Local Ethereum JSON-RPC server for WalletChan approvals.

WalletChan RPC gives scripts, CLIs, and AI agents a standard local RPC endpoint while keeping transaction and signature approval inside the user's connected wallet. Tools send normal Ethereum JSON-RPC to localhost; the paired wallet receives the request over WalletConnect or MetaMask Connect and asks the user to approve it.

Agent skill: SKILL.md

Use it for:

• Giving AI agents wallet access through a local RPC, with every send or signature still requiring user approval
• Foundry, Cast, viem, ethers, shell scripts, or any JSON-RPC client
• User-approved sends, signatures, and wallet_sendCalls call sets with ERC-5792 batching or sequential fallback
• Any EVM chain when you provide its numeric chain ID and upstream RPC URL
• WalletConnect-compatible wallets, including WalletChan and many mobile wallets
• MetaMask Mobile through MetaMask Connect

Requirements

• Node.js 20.19.0 or newer.

Usage

Published package, choose one:

# npm
npx @walletchan/rpc --chain base

# pnpm
pnpm dlx @walletchan/rpc --chain base

# Yarn
yarn dlx @walletchan/rpc --chain base

# Bun
bunx @walletchan/rpc --chain base

Use MetaMask Connect instead of WalletConnect:

npx @walletchan/rpc --chain base --wallet-transport metamask-connect

From this repo:

pnpm dev:walletchan-rpc --chain base

On first use, the CLI copies the pairing URI to your clipboard when possible, then prints a terminal QR code, raw URI, and browser QR URL.

• Wallet app: scan the QR code or paste the pairing URI.
• Browser QR page: open http://127.0.0.1:4209/qr, then scan the QR or copy the URI.

The local RPC, SKILL.md, and /qr endpoints start immediately at http://127.0.0.1:4209 by default. Wallet requests become available after the wallet session is approved.

For isolated containers, bind the RPC inside the container while publishing the port only to host loopback:

walletchan-rpc --chain base --host 0.0.0.0

Agent Skill

Agents can fetch the live local skill/manual from the running RPC:

curl http://127.0.0.1:4209/SKILL.md

The live skill includes the current RPC URL, approved account, active chain, and batching state.

If the wallet connection is revoked, the RPC treats the selected transport session as disconnected once the wallet deletes/expires the session or reports no approved accounts. In an interactive terminal, the CLI prints the disconnect reason and waits for Enter before generating a fresh URI. Non-interactive callers can call http://127.0.0.1:4209/pairing to get a fresh URI without restarting the RPC process, or show http://127.0.0.1:4209/qr so the user can scan the browser QR page.

To switch transports while the RPC is already running:

curl "http://127.0.0.1:4209/pairing?transport=metamask-connect&force=true"
curl "http://127.0.0.1:4209/pairing?transport=walletconnect&force=true"

The browser QR page also supports fresh pairing URIs and updates in place. MetaMask Connect account reads refresh from MetaMask Connect's selected account; if MetaMask Mobile does not report the account switch, request it explicitly:

curl "http://127.0.0.1:4209/pairing?transport=metamask-connect&account=0xYourAddress&forceRequest=true"

Chains

WalletChan RPC is not limited to the chains in this table. It can expose any EVM chain that the connected wallet supports when you provide a numeric chain ID and upstream RPC URL.

Built-in names and default RPC URLs are copied from WalletChan's extension registry:

walletchan-rpc --chain base
walletchan-rpc --chain base --chain arbitrum
walletchan-rpc --chain optimism --port 4210

Mainnet aliases:

| Name | Chain ID | Default RPC | | ---------------- | -------- | -------------------------------------- | | ethereum | 1 | https://eth.drpc.org | | arbitrum | 42161 | https://arb1.arbitrum.io/rpc | | base | 8453 | https://base.drpc.org | | bnb | 56 | https://bsc-dataseed.binance.org | | optimism | 10 | https://mainnet.optimism.io | | megaeth | 4326 | https://mainnet.megaeth.com/rpc | | polygon | 137 | https://polygon.drpc.org | | unichain | 130 | https://mainnet.unichain.org | | gnosis | 100 | https://gnosis.drpc.org | | monad | 143 | https://monad.drpc.org | | sonic | 146 | https://sonic.drpc.org | | intuition | 1155 | https://rpc.intuition.systems | | sei | 1329 | https://sei.drpc.org | | ronin | 2020 | https://ronin.drpc.org | | citrea | 4114 | https://rpc.citrea.xyz | | tempo | 4217 | https://tempo.drpc.org | | mantle | 5000 | https://mantle.drpc.org | | arbitrum-nova | 42170 | https://arbitrum-nova.drpc.org | | celo | 42220 | https://celo.drpc.org | | ink | 57073 | https://ink.drpc.org | | linea | 59144 | https://linea.drpc.org | | berachain | 80094 | https://berachain.drpc.org | | katana | 747474 | https://katana.drpc.org |

Testnet aliases:

| Name | Chain ID | Default RPC | | -------------------- | -------- | ------------------------------------------------ | | bnb-testnet | 97 | https://data-seed-prebsc-1-s1.bnbchain.org:8545 | | unichain-sepolia | 1301 | https://sepolia.unichain.org | | sei-testnet | 1328 | https://evm-rpc-testnet.sei-apis.com | | mantle-sepolia | 5003 | https://rpc.sepolia.mantle.xyz | | citrea-testnet | 5115 | https://rpc.testnet.citrea.xyz | | megaeth-testnet | 6343 | https://carrot.megaeth.com/rpc | | monad-testnet | 10143 | https://testnet-rpc.monad.xyz | | gnosis-chiado | 10200 | https://rpc.chiadochain.net | | intuition-testnet | 13579 | https://testnet.rpc.intuition.systems | | sonic-testnet | 14601 | https://rpc.testnet.soniclabs.com | | tempo-testnet | 42431 | https://rpc.moderato.tempo.xyz | | linea-sepolia | 59141 | https://rpc.sepolia.linea.build | | polygon-amoy | 80002 | https://rpc-amoy.polygon.technology | | berachain-bepolia | 80069 | https://bepolia.rpc.berachain.com | | base-sepolia | 84532 | https://sepolia.base.org | | ronin-saigon | 202601 | https://saigon-testnet.roninchain.com/rpc | | arbitrum-sepolia | 421614 | https://sepolia-rollup.arbitrum.io/rpc | | hoodi | 560048 | https://rpc.hoodi.ethpandaops.io | | katana-bokuto | 737373 | https://rpc.bokuto.katanarpc.com | | ink-sepolia | 763373 | https://rpc-gel-sepolia.inkonchain.com | | celo-sepolia | 11142220 | https://forno.celo-sepolia.celo-testnet.org | | sepolia | 11155111 | https://11155111.rpc.thirdweb.com | | optimism-sepolia | 11155420 | https://sepolia.optimism.io |

For any other EVM chain, use its numeric chain ID and provide an RPC URL:

walletchan-rpc --chain base --rpc base=https://mainnet.base.org
walletchan-rpc --chain 43114 --rpc 43114=https://api.avax.network/ext/bc/C/rpc

Repeat --chain to expose multiple chains. Requests can target a configured chain with wallet_switchEthereumChain or by including a chainId where the method supports it.

Batching

ERC-5792 batching is enabled by default for WalletConnect. The WalletConnect proposal includes:

• wallet_getCapabilities
• wallet_sendCalls
• wallet_getCallsStatus
• wallet_showCallsStatus

If the paired wallet does not approve those ERC-5792 methods, WalletChan RPC still accepts wallet_sendCalls. It sends each call as an individual eth_sendTransaction, waits for that transaction receipt, then asks for the next approval. The returned bundle has mode: "sequential_fallback" and atomic: false.

--skip-batching is still available when you do not want to request ERC-5792 methods during pairing, but it no longer disables wallet_sendCalls; it forces the sequential fallback path.

JSON-RPC Behavior

Wallet requests are sent through the selected wallet transport:

• eth_sendTransaction
• personal_sign
• eth_signTypedData_v3
• eth_signTypedData_v4
• ERC-5792 methods when approved by the wallet

When ERC-5792 is not approved, wallet_sendCalls, wallet_getCapabilities, and local bundle status still work through WalletChan's sequential fallback.

Read-only and unknown methods are forwarded to the active chain's upstream RPC.

Local methods:

• eth_accounts
• eth_requestAccounts
• eth_chainId
• net_version
• web3_clientVersion
• wallet_switchEthereumChain

Rejected methods:

• eth_sendRawTransaction
• eth_sign
• eth_signTransaction

Session Lifecycle

WalletConnect sessions persist across CLI restarts by default. If a compatible stored session exists for the same host and port, the CLI reuses it and skips the QR/paste flow. MetaMask Connect uses the MetaMask Connect client session and exposes the same local pairing, account, and request surfaces.

During a running process, stale or manually revoked sessions are invalidated automatically. Interactive CLI sessions prompt for Enter before generating a new URI; a fresh pairing URI is also available from /pairing. The browser QR page at /qr polls the local process and updates automatically when a new URI is issued. /uri remains available as a compatibility alias.

To discard stored sessions and force a fresh pairing:

walletchan-rpc --chain base --force-new-session

Use --force-new-session when switching wallets, changing to a wallet that supports different methods, or intentionally revoking stale local session state. Use /pairing?transport=...&force=true when you want to switch between WalletConnect and MetaMask Connect without restarting the process.

Environment

WALLETCONNECT_PROJECT_ID is optional. If omitted, the CLI uses WalletChan's default public WalletConnect project ID.

WALLETCHAN_RPC_WALLET_TRANSPORT sets the startup transport. Accepted values are walletconnect and metamask-connect.

WALLETCHAN_RPC_HOST sets the default bind host.

WALLETCHAN_RPC_STORAGE_DIR sets the WalletConnect storage root. Use this in containers to keep session state in a persistent, writable volume owned by the process user.

Foundry

Foundry is optional. WalletChan RPC is a standard JSON-RPC endpoint and is not restricted to Foundry.

For a single call, agents should usually prefer cast send because it avoids creating a full Foundry script. Use Foundry's unlocked-account path so it sends eth_sendTransaction to the local RPC:

cast send 0xContractAddress \
  "transfer(address,uint256)" 0xRecipient 1000000000000000000 \
  --rpc-url http://127.0.0.1:4209 \
  --unlocked \
  --from 0xYourConnectedAddress

For larger flows that already live in a script, use the same unlocked-account path:

forge script script/Deploy.s.sol \
  --rpc-url http://127.0.0.1:4209 \
  --broadcast \
  --unlocked \
  --sender 0xYourConnectedAddress

Do not pass a private key to Foundry for this flow. Signed raw transactions are rejected because they bypass WalletChan approval.