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

# 事件与交易记录

> 订阅钱包状态变化，查询和等待交易状态。

## getTransactionHistory

需要网站获得 `transactions` 读取权限。Client 与 Provider 都接受可选的 `{ limit?, offset? }`，返回 `Promise<ArksatTransaction[]>`。

```ts theme={null}
await client.connect({ read: ['transactions'] })
const history = await client.getTransactionHistory({ limit: 20, offset: 0 })
```

记录按最新优先返回。offset 分页不是稳定快照；新记录插入后需按 ID 去重。

## on / off

直接在 Provider 上监听和移除事件：

```ts theme={null}
const onNetwork = (network: 'mainnet' | 'mutinynet') => {
  console.log(network)
}
provider.on('network:changed', onNetwork)
// 页面卸载时
provider.off('network:changed', onNetwork)
```

| 事件 | 数据 |
| - | - |
| account:changed | string\[] |
| network:changed | ArksatNetwork |
| balance:changed / assets:changed | ArksatDataEvent 或 null |
| transaction:updated / transfer:received / transfer:settled | ArksatTransactionEvent |
| connection:connected | 空对象 |
| connection:disconnected | message 字符串字段 |
| wallet:locked / wallet:unlocked | null |

事件协议为 2。账户、网络或锁定状态变化后应更新页面上下文。[事件接入指南](https://docs.arksat.xyz/events.md)。

## subscribe

SDK 提供取消函数，便于组件卸载时清理：

```ts theme={null}
import { subscribe } from '@arksat/wallet-sdk'
const stop = subscribe(provider, 'balance:changed', () => {
  // 重新读取余额
})
stop()
```

## waitForTransaction

```ts theme={null}
import { waitForTransaction } from '@arksat/wallet-sdk'
const tx = await waitForTransaction(provider, txid, {
  timeoutMs: 120000,
  pollIntervalMs: 3000,
})
```

返回 `Promise<ArksatTransaction>`。可选 `signal: AbortSignal`；默认超时 120 秒、轮询 3 秒，轮询最短 1 秒。只搜索最新 100 条授权记录，遇到非 pending 状态即返回，可能包含 failed 等状态。

上下文变化会中止等待。超时后先查询记录，避免重复付款；通知或钱包状态不应作为商户付款证明。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.