@ckb-ccc/uni-sat
Connect UniSat Wallet to CKB — Bitcoin signing through a unified Signer interface.
@ckb-ccc/uni-sat integrates UniSat Wallet into CCC, providing a SignerBtc implementation for Bitcoin signing. It communicates with the wallet via the browser-injected window.unisat object and supports automatic network switching between Bitcoin mainnet and testnet.
If you're using @ckb-ccc/connector-react or @ckb-ccc/ccc, UniSat is already included — no separate installation needed.
Installation
npm install @ckb-ccc/uni-satDependencies:
| Package | Description |
|---|---|
@ckb-ccc/core | Base types — Signer, Client, Transaction, and more |
Architecture
Entry point: getUniSatSigners
getUniSatSigners(client) checks for window.unisat and returns one SignerInfo per supported network — empty if the wallet isn't available.
The Signer class
Signer extends ccc.SignerBtc and adapts the UniSat provider interface to CKB signing.
Key methods
| Method | Description |
|---|---|
connect() | Calls requestAccounts() then ensures the correct BTC network |
isConnected() | Returns true if accounts exist and network matches |
getBtcAccount() | Returns the first BTC address from the provider |
getBtcPublicKey() | Returns the BTC public key (hex-encoded) |
signMessageRaw(message) | Signs via signMessage(msg, "ecdsa") |
onReplaced(listener) | Fires on accountsChanged or networkChanged events |
Network management
UniSat exposes BTC, BTC Testnet, BTC Testnet4, BTC Signet, Fractal Bitcoin, and Fractal Bitcoin Testnet signers. On connect(), the selected signer switches the wallet to its fixed network.
Testnet4, Signet, and Fractal Bitcoin require the wallet's switchChain API.
Signing flow
Account change detection
Signer implements onReplaced() to handle account or network changes:
- Listens for
"accountsChanged"— user switched BTC account - Listens for
"networkChanged"— user switched BTC network
When either fires, the application callback is invoked and the listener is cleaned up.
Provider interface
| Method | Description |
|---|---|
requestAccounts() | Prompt user to connect and return accounts |
getAccounts() | Get connected accounts (no prompt) |
getPublicKey() | Get the BTC public key |
getNetwork() | Get current network ("livenet" or "testnet") |
switchNetwork(network) | Switch between livenet/testnet |
getChain() | Get current chain (extended API) |
switchChain(chain) | Switch chain (extended API, supports Fractal) |
signMessage(msg, type) | Sign a message with "ecdsa" or "bip322-simple" |
Integration pattern
@ckb-ccc/uni-sat follows the same integration contract as every other wallet package in CCC:
- Factory function —
getUniSatSignersreturns aSignerInfo[]array. - Provider detection — checks for
window.unisatbefore creating signers. - Graceful degradation — returns an empty array when the wallet is unavailable.
This package is also used as a dependency by @ckb-ccc/okx for its Bitcoin signing support.
Last updated on