@ckb-ccc/xverse
Connect Xverse and SATS Connect compatible wallets to CKB — Bitcoin signing through a unified Signer interface.
@ckb-ccc/xverse integrates Xverse Wallet and any SATS Connect compatible Bitcoin wallet into CCC. It provides a SignerBtc implementation using the SATS Connect RPC protocol, supporting multi-wallet discovery via window.btc_providers.
If you're using @ckb-ccc/connector-react or @ckb-ccc/ccc, Xverse is already included — no separate installation needed.
Installation
npm install @ckb-ccc/xverseDependencies:
| Package | Description |
|---|---|
@ckb-ccc/core | Base types — Signer, Client, Transaction, and more |
Architecture
Unlike other wallet packages that detect a single global provider, @ckb-ccc/xverse uses the window.btc_providers array to discover multiple SATS Connect wallets simultaneously.
Entry point: getXverseSigners
getXverseSigners(client) reads from window.btc_providers. Xverse and providers supporting the WBIP network methods get separate Mainnet, Testnet4, Signet, and Regtest entries; legacy providers retain a single BTC entry.
Each provider entry includes wallet metadata (name, icon) allowing SignersController to display distinct wallet entries.
The Signer class
Signer extends ccc.SignerBtc and uses the SATS Connect RPC protocol for all wallet interactions.
Key methods
| Method | Description |
|---|---|
connect() | Requests permissions and switches to the selected network |
disconnect() | Clears the cached address |
isConnected() | Checks the selected network, then reads the payment address without prompting |
getBtcAccount() | Returns the payment address via getAddresses |
getBtcPublicKey() | Returns the public key from the payment address |
signMessageRaw(message) | Signs via signMessage with ECDSA protocol |
onReplaced(listener) | Fires on accountChange or networkChange events |
Connection and address caching
The signer caches the resolved address to avoid redundant RPC calls. The cache is invalidated on disconnect():
Signing flow
Account change detection
Signer implements onReplaced() via the SATS Connect event API:
- Listens for
"accountChange"— user switched BTC account - Listens for
"networkChange"— user switched BTC network
Returns cleanup functions from provider.addListener() for proper teardown.
SATS Connect RPC methods
| Method | Description |
|---|---|
wallet_requestPermissions | Request wallet connection permissions |
getAddresses | Get addresses filtered by purpose (Payment, Ordinals, etc.) |
signMessage | Sign a message with ECDSA or BIP-322 |
Integration pattern
@ckb-ccc/xverse follows the same integration contract as other wallet packages in CCC:
- Factory function —
getXverseSignersreturns{ wallet, signerInfo }[]for multi-wallet support. - Provider detection — reads
window.btc_providersarray. - Multi-wallet discovery — creates separate signer entries per provider with distinct wallet names and icons.
- Graceful degradation — returns an empty array when no SATS Connect wallets are available.
Last updated on