Relay

Reliable wallet connections for wagmi. Automatic RPC fallback, multi-account support, and connection observability.

Built on wagmi v2 + viem. Handles the parts that break in production: RPC failures, duplicate accounts, and session persistence.

Why Relay?

RainbowKit gives you the button. Relay makes sure it actually connects.

Most dApps lose 8-15% of users at the connect step and have no idea why. Relay provides the transport layer that survives:

• Alchemy rate limits and 403s
• Slow public RPCs
• Users switching accounts mid-session
• WalletConnect timeouts on mobile

Install

pnpm add @ghostmountain3/relay @wagmi/core viem

Quick Start

import { 
  init, 
  connectMetaMask, 
  connectWalletConnect,
  signPersonalMessage,
  getCurrentAccount 
} from '@ghostmountain3/relay'

// Initialize once at app startup
init({
  alchemyKey: process.env.NEXT_PUBLIC_ALCHEMY_KEY,
  wcProjectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID,
})

// Connect
await connectMetaMask()
const account = getCurrentAccount()
console.log(account.address)

// Sign a message (EIP-191)
const signature = await signPersonalMessage('Sign in to my app')

Features

Automatic RPC Fallback

init({
  alchemyKey: 'your-key', // Primary
  // Automatically falls back to public RPCs on failure
})

Transport tries Alchemy first, switches to public nodes on 403/timeout without user noticing.

Multi-Account Detection

import { getAuthorizedAccounts } from '@ghostmountain3/relay'

const accounts = getAuthorizedAccounts()
// Returns deduped list of all accounts user has approved

Handles the case where users have 2+ MetaMask accounts connected.

Network Switching

import { changeNetwork, SUPPORTED_CHAINS } from '@ghostmountain3/relay'

await changeNetwork(42161) // Arbitrum

Built-in support for Ethereum, Polygon, Arbitrum, Optimism.

Session Persistence

Accounts persist across page reloads. No reconnect needed.

Normalized Errors

All wallet errors map to consistent codes:

• 4001 → User rejected
• 4902 → Chain not added
• -32002 → Request pending

API Reference

Core

• init(config) - Initialize wagmi config
• connectMetaMask() - Connect injected wallet
• connectWalletConnect() - Connect via WalletConnect
• connectCoinbase() - Connect Coinbase Wallet
• disconnectWallet() - Disconnect and clear session

Accounts

• getCurrentAccount() - Get active account and chain
• getAuthorizedAccounts() - Get all approved accounts (deduped)
• onAccountChange(callback) - Subscribe to account changes

Network

• changeNetwork(chainId) - Switch chains
• SUPPORTED_CHAINS - Array of supported chains
• testRpcCall() - Test current RPC health

Signing

• signPersonalMessage(message) - EIP-191 personal_sign
• verifySignature({message, signature, address}) - Verify signature

Architecture

Your App
    ↓
@ghostmountain3/relay
    ↓
wagmi v2 → viem
    ↓
fallback([alchemy, ankr, public])
    ↓
watchAccount + persist

Live Demo

Try it: [demo link]

Source: https://github.com/ghostmountain3/universal-wallet-connector

Comparison

| Feature | Relay | RainbowKit | wagmi | |---------|-------|------------|-------| | UI Components | ❌ BYO | ✅ | ❌ | | RPC Fallback | ✅ Automatic | ⚠️ Manual | ⚠️ Manual | | Bundle Size | ~12kb | ~200kb | ~45kb | | Multi-account | ✅ Deduped | ✅ | ⚠️ | | React Native | ✅ | ❌ | ✅ |

Use Relay with RainbowKit for best of both: beautiful UI + reliable transport.

Roadmap

• [x] Core transport with fallback
• [x] Multi-account support
• [x] EIP-191 signing
• [ ] Devtools dashboard (npx relay dev)
• [ ] React Native package
• [ ] Connection analytics
• [ ] Wallet simulator for testing

License

MIT

Contributing

Follow progress: https://github.com/ghostmountain3/universal-wallet-connector