Introduction
butr is a set of multi-chain wallet-management primitives for React. EVM, Solana, Sui, Bitcoin, and Polkadot, discovered and managed through one composable hook surface.
butr discovers EVM (EIP-6963 / EIP-1193), Solana / Sui / Bitcoin (Wallet
Standard), and Polkadot (injectedWeb3) wallets,
manages their connection state across reloads, and exposes everything through
small composable React hooks. It does not wrap viem, wagmi, gill, or
framework-kit; it sits underneath them and hands you a raw signer so you keep
using whatever chain library you already know.
What butr is
- Multi-chain by default. One provider, one pool. A user can connect MetaMask (EVM) and Phantom (SVM) at the same time; butr tracks each platform independently.
- Connector-shaped. Every wallet (injected, WalletConnect, Ledger, or one
you write yourself) is a
WalletAdapterplugged in through a single seam:WalletManagerConfig.createConnector. - No lock-in.
getSigner()returns the underlying provider. You bridge it into viem / wagmi / gill / framework-kit /@solana/kit(or legacy@solana/web3.js) with a few lines. - Modular. Install only the packages you need. The core has no React and no protocol code; protocols live in separate packages.
The package model
butr is layered. Each package depends only on the ones below it.
| Package | What it does | Depends on |
|---|---|---|
@usebutr/core | Types, the wallet store, persistence, the discovery seam. No React, no protocols. | — |
@usebutr/react | Provider + hooks over the store. | @usebutr/core |
@usebutr/evm | EIP-1193 / EIP-6963 / injected discovery and adapters. | @usebutr/core |
@usebutr/svm | Wallet Standard discovery and adapters for Solana. | @usebutr/core |
@usebutr/sui | Wallet Standard discovery and adapters for Sui. | @usebutr/core |
@usebutr/bitcoin | Wallet Standard + injected discovery and adapters for Bitcoin. | @usebutr/core |
@usebutr/polkadot | injectedWeb3 discovery and adapters for Polkadot, with a Wallet Standard fallback. | @usebutr/core |
@usebutr/wallets | Batteries-included five-platform discovery source (autoDiscovery) + combined registries. | core, react, platforms |
@usebutr/walletconnect | WalletConnect v2 adapter for EVM mobile wallets. | core, evm |
@usebutr/ledger | Ledger hardware-wallet adapter (WebUSB, signing-only). | @usebutr/core |
@usebutr/testing | Fake adapter + fake persistence for unit tests. | @usebutr/core |
Most apps want @usebutr/wallets (it pulls in @usebutr/react, @usebutr/core,
and the per-platform adapter packages). Pass autoDiscovery() from
@usebutr/wallets to WalletManagerProvider from @usebutr/react for
discovery across all five platforms. Reach for the lower-level packages when
you want a single-platform bundle or a custom discovery pipeline.
Where to go next
- Installation: pick your packages.
- Quickstart: a working app in five
minutes with
WalletManagerProvider. - Core concepts: the mental model of connectors, the pool, platforms, hydration.
- Standards compliance: how butr follows the Wallet Standard, EIP-6963, and EIP-1193, and the deliberate edges.
- Guides: connect, sign, send, switch chains.
- API reference: every export, per package.
All code in these docs is taken from the runnable demo apps and package tests in the butr repository, not invented. Each guide cites its source.