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.
Demos
Try the live demo, or run one of the 15 examples: