> For the complete documentation index, see [llms.txt](https://help.tokenpocket.pro/developer-cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.tokenpocket.pro/developer-cn/extension-wallet/api-reference/bitcoin-provider-api.md).

# Bitcoin Provider API

TokenPocket Extension 会在页面中注入 Bitcoin Provider，并兼容 UniSat 常用接口，开发者可使用熟悉的 Bitcoin dApp 接口完成账户读取、消息签名、PSBT 签名和广播等操作。

## Provider 注入

页面中可使用以下对象：

```ts
window.unisat
window.tokenpocket.bitcoin
```

说明：

* `window.unisat`：用于兼容 UniSat 风格接入
* `window.tokenpocket.bitcoin`：TokenPocket 原生 Bitcoin Provider

页面初始化完成后会派发一次事件：

```ts
window.dispatchEvent(new Event('unisat#initialized'));
```

## 快速开始

### 请求连接

```ts
const accounts = await window.unisat.requestAccounts();
console.log(accounts[0]);
```

### 读取公钥

```ts
const publicKey = await window.unisat.getPublicKey();
console.log(publicKey);
```

### 签名消息

```ts
const signature = await window.unisat.signMessage('hello tokenpocket');
console.log(signature);
```

## API 列表

### requestAccounts

请求连接当前站点并返回 BTC 地址列表。

```ts
requestAccounts(): Promise<string[]>
```

示例：

```ts
const accounts = await window.unisat.requestAccounts();
console.log(accounts[0]);
```

### getAccounts

读取当前站点已授权的 BTC 地址列表。

```ts
getAccounts(): Promise<string[]>
```

### getPublicKey

读取当前 BTC 地址对应的公钥。

```ts
getPublicKey(): Promise<string>
```

### getBalance

读取 BTC 余额信息。

```ts
getBalance(): Promise<any>
```

说明：

* 返回值格式与钱包实现保持一致

### getNetwork

读取当前网络标识。

```ts
getNetwork(): Promise<string>
```

当前版本仅支持：

```ts
'livenet'
```

### getChain

读取当前链信息。

```ts
getChain(): Promise<{
  enum: string;
  name: string;
  network: string;
}>
```

当前版本返回主网信息：

```ts
{
  enum: 'BITCOIN_MAINNET',
  name: 'Bitcoin Mainnet',
  network: 'livenet',
}
```

### getVersion

读取 Provider 版本号。

```ts
getVersion(): Promise<string>
```

### switchNetwork

切换网络。

```ts
switchNetwork(network?: string): Promise<void>
```

说明：

* 当前版本仅允许主网

### switchChain

切换链配置。

```ts
switchChain(chain?: string): Promise<{
  enum: string;
  name: string;
  network: string;
}>
```

说明：

* 当前版本仅允许主网

### signMessage

签名消息。

```ts
signMessage(
  message: string,
  type?: 'ecdsa' | 'bip322-simple'
): Promise<string>
```

示例：

```ts
const signature = await window.unisat.signMessage(
  'hello tokenpocket',
  'ecdsa'
);
```

### signPsbt

签名单个 PSBT。

```ts
signPsbt(psbtHex: string, options?: Record<string, any>): Promise<string>
```

### signPsbts

批量签名 PSBT。

```ts
signPsbts(
  psbtHexs: string[],
  options?: Record<string, any>[] | Record<string, any>
): Promise<string[]>
```

### pushPsbt

Finalize 并广播 PSBT。

```ts
pushPsbt(psbtHex: string): Promise<string>
```

### pushTx

广播原始交易。

```ts
pushTx(rawtx: string | { rawtx?: string }): Promise<string>
```

### sendBitcoin

发起 BTC 转账。

```ts
sendBitcoin(
  toAddress: string,
  satoshis: number,
  options?: Record<string, any>
): Promise<string>
```

示例：

```ts
const txid = await window.unisat.sendBitcoin(
  'bc1...',
  1000
);
```

## 事件

Bitcoin Provider 支持事件监听。

### accountsChanged

地址切换时触发。

```ts
window.unisat.on('accountsChanged', (accounts) => {
  console.log(accounts);
});
```

### networkChanged

网络变更时触发。

```ts
window.unisat.on('networkChanged', (network) => {
  console.log(network);
});
```

### 事件方法

支持以下监听接口：

* `on`
* `once`
* `off`
* `addListener`
* `removeListener`
* `removeAllListeners`

## 错误处理

建议所有 Provider 调用都使用 `try/catch`。

```ts
try {
  const accounts = await window.unisat.requestAccounts();
  console.log(accounts[0]);
} catch (error) {
  console.error(error);
}
```

常见失败场景：

* 用户拒绝连接
* 用户拒绝签名或交易确认
* 当前站点未授权
* 当前没有可用 BTC 地址
* 当前网络不被支持

## 兼容性说明

* TokenPocket 同时暴露 `window.unisat` 与 `window.tokenpocket.bitcoin`
* 接口设计优先兼容 UniSat 常见接入方式
* 当前版本仅支持 Bitcoin Mainnet