# @seams/wallet 中文文档

规范地址：https://npmcn.com/package/%40seams/wallet/

版本：0\.41\.1
npm 元数据更新时间：2026-11-02T08:00:09.061Z
中文译文更新时间：2026-11-02T10:49:37.977Z
软件包许可：Apache-2\.0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40seams/wallet
原文对照：https://npmcn.com/package/%40seams/wallet/?lang=original
项目主页：https://github.com/seams-tech/seams-wallet#readme
源码仓库：https://github.com/seams-tech/seams-wallet

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：29.4 MB，2246 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：jsqr 1\.4\.0，react \>=19\.0\.0，qrcode 1\.5\.4，react-dom \>=19\.0\.0
- 首次发布：2026-09-13T01:55:24.111Z
- 最新版本发布：2026-11-02T08:00:08.543Z
- 已发布版本数：82（近 12 个月 82 个）

## 中文简介

为NEAR和evm家族钱包提供web和运行时TypeScript SDK

## 安装

```sh
npm install @seams/wallet
```

也可以使用：`pnpm add @seams/wallet`、`yarn add @seams/wallet`、`bun add @seams/wallet`

## README

# 接缝钱包SDK

`@seams/wallet` **0.41.1** 提供浏览器钱包生命周期，NEAR和evm家族 阈值签名、React组件和托管钱包运行时资产。

## 安装

```sh
pnpm add @seams/wallet@0.41.1
```

React和React DOM是可选的对等体 `>=19.0.0`，包括未来的主要版本。 SDK开发使用精确的 `react@19.2.9` 和 `react-dom@19.2.9`. 应用程序锁定文件选择已安装的React版本。从中导入提供程序和UI `@seams/wallet/react` 和它的样式表 `@seams/wallet/react/styles`. 保留应用程序包、钱包源资产和 `@seams/wallet-server@0.41.1` 在匹配的释放上。钱包iframe协议 是 `23.0.0`． 应用程序和钱包主机必须使用相同的协议版本。

## 当前的API

公共API将调用分组在下面 `auth`， `connection`， `config`， `events`， `registration`，以及链命名空间。看到 [浏览器的参考](https://wallet.seams.sh/docs/reference/core). 使用 `auth.lock()` 结束会话，同时保留有效的持久预签名。

自定义电子邮件解锁使用主机拥有的挑战：

```ts
const requested = await seams.auth.requestEmailCode({
  method: 'google',
  idToken,
  target: { kind: 'wallet', walletId },
});
if (!requested.ok) throw new Error(requested.error.message);
const result = await seams.auth.unlockWithEmailCode({
  challenge: requested.value,
  code,
});
if (!result.ok) throw new Error(result.error.message);
```

对于现有的本地电子邮件方法，请使用 `{ method: 'email', walletId, email }`． 挑战支持 `resend()` 和 `cancel()`． 使用成功重发后返回的替换挑战。 SDK选择签名者并在内部完成待激活。

只有在用户选择该方法后才请求电子邮件代码。主机拥有的钱包 挑战和它的到期。应用程序接收类型化质询句柄。

## 申请会议和新业主批准

SDK 0.41.1接受来自显式信任的应用程序后端的切换。 谷歌和app-passkey登录可以使用相同的稳定应用用户ID。 使用 `registration.registerOwnerWallet` 使用NEAR-only密码登机和 `near.prepareOwnerTransaction` 重新批准每笔交易。 这些操作不创建可重用的签名授权。 React读连接将所有者操作句柄与可重用的签名者分开公开。 看到 [应用程序会话指导](https://wallet.seams.sh/docs/guides/application-auth).

## 带上自己的谷歌身份验证

SDK 0.41.1可以重用应用程序的b谷歌ID令牌来打开相关的钱包设置。 配置环境的谷歌客户端ID，并让所有者将他们的钱包关联一次。 然后在应用程序现有的谷歌登录后传递令牌：

```ts
const result = await seams.auth.authenticate({ method: 'google', walletId, idToken });
if (!result.ok) throw new Error(result.code);
```

保留令牌的应用程序在后端使用 `prepareExternalAuth` 以及浏览器绑定的切换。 呼叫 `seams.auth.lock()` 当应用程序注销或切换帐户时。 这些会话授予设置读取。签名、导出、恢复和安全更改保留其所有者身份验证要求。 看到 [谷歌单点登录指南](https://wallet.seams.sh/docs/guides/google-sso) 对于交换路径、关联、到期和撤销。

## 反应快速启动

三个必需的值是钱包来源、网关/中继器URL和 管理注册可发布密钥。从您的项目中获取它们并允许 您的应用程序在该环境中的源。浏览器配置是公开的。

```tsx
import {
  HostedSeamsAuthMenu,
  SeamsWebProvider,
  seamsTestnetConfig,
  type HostedAuthMenuOutcome,
} from '@seams/wallet/react';
import '@seams/wallet/react/styles';

const config = seamsTestnetConfig({
  walletOrigin: import.meta.env.VITE_WALLET_ORIGIN,
  relayerUrl: import.meta.env.VITE_RELAYER_URL,
  publishableKey: import.meta.env.VITE_SEAMS_PUBLISHABLE_KEY,
});

function handleOutcome(outcome: HostedAuthMenuOutcome): void {
  console.log('Wallet authentication:', outcome);
}

export function App() {
  return (
    <SeamsWebProvider config={config}>
      <HostedSeamsAuthMenu onOutcome={handleOutcome} />
    </SeamsWebProvider>
  );
}
```

`seamsTestnetConfig` 选择NEAR和Tempo测试网。使用 `defineSeamsConfig` 对于另一个链集。evm家族链记录需要数字 `chainId`. 一个可选的 `projectEnvironmentId` 交叉检查拒绝a的可发布密钥 不同的环境。

托管菜单拥有注册，登录，OTP提示，恢复代码备份， 还有用户的存在感。供应 `externalAuthBroker` 当您的应用程序获得 谷歌钱包主机的身份证明。保密证书和 从应用配置和日志中恢复材料。

## 签名和生命周期

`useSeams()` 公开身份验证操作、生命周期状态和当前 `wallet`． 注销时钱包为空。经过身份验证的钱包提供 `near`， `evm`, `tempo` 签名者受其身份约束。 `wallet.near` 在NEAR帐户准备好之前为空。检查注册是否未完成 分支和用途 `registration.waitForNearAccount` 签署NEAR之前。

```tsx
const { unlock, lock, wallet } = useSeams();
```

解锁在随后的React渲染中更新钱包。使用经过身份验证的 在签名处理程序中渲染钱包。 `wallet.walletId` 识别钱包。

这个体系的中立者 `SeamsWeb` 下的客户端组操作 `registration`， `auth`， `near`， `evm`， `tempo`， `recovery`， `devices`, `keys`。签名可以 一次操作使用新授权； `unlock` 供应有限 可重复使用钱包会话。evm系列签名或导出呼叫需要 `chainTarget` 命名已配置的链。

`keys.exportKey` 打开钱包源查看器并返回 `{ kind: 'exported' }`. 它不向应用程序返回私钥。 `recovery.syncAccount` 同步已知钱包的账户状态；托管菜单处理恢复 代码和新因素验证。

看到 [编制示例](https://wallet.seams.sh/docs/examples/) 用于 注册、解锁、签名、链接设备、导出、恢复和主题化。

## 钱包设置

`WalletSettingsPage` 提供帐户，密钥导出，恢复代码， 认证方法、设备链接、链接设备和事务 偏好。已注销用户可查看托管身份验证菜单。

```tsx
import {
  SeamsWebProvider,
  WalletSettingsPage,
  type SeamsConfigsInput,
} from '@seams/wallet/react';
import '@seams/wallet/react/styles';

export function WalletSettingsApp({ config }: { config: SeamsConfigsInput }) {
  return (
    <SeamsWebProvider config={config}>
      <WalletSettingsPage />
    </SeamsWebProvider>
  );
}
```

保持配置 `/wallet-service` 端点。裸服务HTML 资产需要部署的引导和配置，然后才能提供服务 完成设置应用程序。

## 接待边界和区域家庭

专用钱包原点服务 `/wallet-service` 和 `/sdk/*`,包括 工人、WASM和导出查看器。SDK iframe委托WebAuthn 该源的权限。在那里执行凭据创建和断言； 没有应用程序源凭据桥接。

区域托管部署在注册时为每个钱包分配一个home。 一个项目中的钱包可以有不同的家，而所有设备都是一个 钱包使用同一个家。旅行不会改变它。钱包的主人可以移动钱包 到另一个具有钱包区域设置的区域。自动区域重新定位 未来的能力。

对于亚太地区，注册和搬迁申请东南亚安置通过 `apac-se`。提示不保证城市或移动现有对象。运营商 必须验证实际的对象位置和数据库主。

遵循 [升级指南](https://wallet.seams.sh/docs/deploy-and-operate/hosted-integration) 在更改应用程序、钱包资产或后端之前。不相容的开放 客户端在重试之前必须重新加载匹配的资产。

## 初次装载和登记

当钱包原点没有存储钱包时，主机回答连接读取 它的引导代码。它在操作需要时加载运行时。呼叫 `seams.authMenu.prepare()` 在登录时，打算提前下载登录代码。 越来越多 `HostedSeamsAuthMenu` 无需额外呼叫即可开始下载。

打开托管的注册视图准备它的钱包和密钥挑战。 `authMenu.prepare()` 只下载代码。一个直接 `registerWallet()` 电话开始 该调用中的注册设置。看到 [编译的托管菜单示例](https://wallet.seams.sh/docs/examples/wallet-setup-and-authentication).

注册可以在控制台目录中显示其完成之前进行签名。 网关重新尝试挂起的目录发布。在得到承认之前， 钱包可以从控制台列表中缺席，并且在区域移动时不可用。

## 公共entrypoints

-   `@seams/wallet` -浏览器客户端，配置构建器，公共结果和值。
-   `@seams/wallet/react` -提供程序、钩子、组件、事务审查和主题。
-   `@seams/wallet/external-evm` -浏览器EVM扩展连接器。
-   `@seams/wallet/advanced` -精确的身份生成器，RPC和编码助手。
-   `@seams/wallet/threshold` -会话策略助手、PRF盐和意图摘要。
-   `@seams/wallet/runtime` -明确的平台端口和自定义签名运行时。

使用文档化的包导出。代理通道的发行仍在计划中。 VoiceID审批原型是可选择的：

```ts
import { defineSeamsConfig } from '@seams/wallet';
import { voiceIdAuthMethod } from '@seams/voiceid';

const config = defineSeamsConfig({
  walletOrigin,
  relayerUrl,
  publishableKey,
  authMethods: [voiceIdAuthMethod()],
});
```

VoiceID是一个单独的可选包。钱包主机运营商必须部署其 钱包主机旁边的资产。描述符本身不下载实现 或模型。VoiceID支持注册，钱包会话解锁和审查NEAR 和Arc测试网签约。看到 [`@seams/voiceid`](https://npmcn.com/package/%40seams/voiceid/README.md) 为安装。

## 从源头发展

从存储库根目录：

```sh
pnpm install
pnpm build
pnpm -C packages/wallet dev
pnpm test:wallet-browser
pnpm -C packages/wallet type-check
```

已经构建了所需的WASM和服务器构件，只需重新构建SDK 与 `pnpm -C packages/wallet build:sdk`。请参阅存储库README以获取完整的 本地栈和控制台Lite示例。

## 许可和支持

apache - 2.0。请看包装的 `LICENSE.md` 和 `THIRD_PARTY_NOTICES.md`.

-   [文档](https://wallet.seams.sh/docs/)
-   [存储库和问题](https://github.com/seams-tech/seams-wallet)

## 常见问题

### @seams/wallet 是什么？

为NEAR和evm家族钱包提供web和运行时TypeScript SDK

### 如何安装 @seams/wallet？

在项目目录运行 npm install @seams/wallet，或使用 pnpm add / yarn add / bun add。

### @seams/wallet 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @seams/wallet 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @seams/wallet 可以商用吗？

@seams/wallet 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @seams/wallet 还在维护吗？

最新版本 0\.41\.1 发布于 2026/11/02（1 天前）；至今共发布 82 个版本，其中过去 12 个月发布了 82 个；首次发布于 2026/09/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。