`@ckb-ccc/uni-sat` integrates [UniSat Wallet](https://unisat.io/) 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.

<Callout type="info">
  If you're using `@ckb-ccc/connector-react` or `@ckb-ccc/ccc`, UniSat is already included — no separate installation needed.
</Callout>

## Installation [#installation]

<PackageBadges pkg="@ckb-ccc/uni-sat" />

<Tabs items="['npm', 'yarn', 'pnpm']">
  <Tab value="npm">
    ```bash
    npm install @ckb-ccc/uni-sat
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @ckb-ccc/uni-sat
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @ckb-ccc/uni-sat
    ```
  </Tab>
</Tabs>

**Dependencies:**

| Package         | Description                                              |
| --------------- | -------------------------------------------------------- |
| `@ckb-ccc/core` | Base types — `Signer`, `Client`, `Transaction`, and more |

## Architecture [#architecture]

<Mermaid
  chart="graph TB
    subgraph &#x22;UniSat Package&#x22;
        GUS[&#x22;getUniSatSigners(client)&#x22;]
        S[&#x22;Signer (extends SignerBtc)&#x22;]
    end

    subgraph &#x22;Provider&#x22;
        WU[&#x22;window.unisat&#x22;]
    end

    subgraph &#x22;Core&#x22;
        CorePkg[&#x22;@ckb-ccc/core (SignerBtc)&#x22;]
    end

    GUS -->|&#x22;detects&#x22;| WU
    GUS -->|&#x22;creates&#x22;| S
    S --> CorePkg
    S -->|&#x22;calls&#x22;| WU"
/>

### Entry point: `getUniSatSigners` [#entry-point-getunisatsigners]

`getUniSatSigners(client, preferredNetworks?)` checks for `window.unisat` and returns a `SignerInfo[]` array — empty if the wallet isn't available:

<Mermaid
  chart="graph TD
    Start[&#x22;getUniSatSigners(client)&#x22;] --> Check[&#x22;window.unisat exists?&#x22;]
    Check -->|No| Empty[&#x22;return []&#x22;]
    Check -->|Yes| Create[&#x22;new Signer(client, window.unisat)&#x22;]
    Create --> Array[&#x22;SignerInfo[] with name 'BTC'&#x22;]"
/>

## The `Signer` class [#the-signer-class]

`Signer` extends `ccc.SignerBtc` and adapts the UniSat provider interface to CKB signing.

### Key methods [#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 [#network-management]

UniSat supports multiple Bitcoin networks. On `connect()`, the signer automatically switches the wallet to the correct network based on `preferredNetworks` configuration:

| CKB Network     | Default BTC Network    |
| --------------- | ---------------------- |
| Mainnet (`ckb`) | `btc` (livenet)        |
| Testnet (`ckt`) | `btcTestnet` (testnet) |

<Mermaid
  chart="sequenceDiagram
    participant App as Application
    participant Signer as UniSat Signer
    participant Wallet as UniSat Extension

    App->>Signer: connect()
    Signer->>Wallet: requestAccounts()
    Wallet->>Signer: accounts[]
    Signer->>Wallet: getNetwork() / getChain()
    Wallet->>Signer: current network
    Signer->>Signer: Match preferred network
    alt Network mismatch
        Signer->>Wallet: switchNetwork(&#x22;livenet&#x22; | &#x22;testnet&#x22;) or switchChain(chain)
    end"
/>

The signer also supports Fractal Bitcoin via the `switchChain` API (when available).

### Signing flow [#signing-flow]

<Mermaid
  chart="sequenceDiagram
    participant App as Application
    participant Signer as UniSat Signer
    participant Wallet as UniSat Extension

    App->>Signer: sendTransaction(tx)
    Signer->>Signer: prepareTransaction(tx)
    Note over Signer: Add CellDeps, prepare witnesses
    Signer->>Wallet: signMessage(challenge, &#x22;ecdsa&#x22;)
    Wallet->>Signer: signature
    Signer->>Signer: Pack signature into witness
    Signer->>App: txHash"
/>

## Account change detection [#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 [#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 [#integration-pattern]

`@ckb-ccc/uni-sat` follows the same integration contract as every other wallet package in CCC:

* **Factory function** — `getUniSatSigners` returns a `SignerInfo[]` array.
* **Provider detection** — checks for `window.unisat` before 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.


---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ckbccc.com/llms.txt
> Use this file to discover all available pages before exploring further.