# @gemini-wallet/core 中文文档

规范地址：https://npmcn.com/package/%40gemini-wallet/core/

版本：0\.3\.2
npm 元数据更新时间：2025-11-10T16:31:08.457Z
中文译文更新时间：2026-11-16T02:37:11.551Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：447 kB，39 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：viem \>=2\.0\.0
- 首次发布：2025-07-15T14:44:14.729Z
- 最新版本发布：2025-11-10T16:31:07.979Z
- 近 30 天下载量：3944894（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 0 个）

## 中文简介

双子钱包集成核心SDK与弹出通信

## 安装

```sh
npm install @gemini-wallet/core
```

也可以使用：`pnpm add @gemini-wallet/core`、`yarn add @gemini-wallet/core`、`bun add @gemini-wallet/core`

## README

# @ gemini- wallet/ 核心

完成与双子钱包集成的SDK,提供钱包连接,交易签名,以及EVM供应商功能.

## 概览

`@gemini-wallet/core` 是一个全面的钱包 SDK 提供将双子钱包整合到您的应用程序中所需的一切。 它包括一个完整的EVM兼容供应商,钱包连接管理,安全存储,以及无缝的以弹出为基础的用户互动.

## 特征

-   🔗 **EVM 提供者**: 完成Ethereum供应商实施(EIP-1193兼容)
-   🔒 **安全通讯**: 基于Message的跨源通信
-   🪟 **弹出管理**: 自动弹出窗口生命周期管理
-   💾 **存储层**: 以本地Storage倒置方式持续存储
-   🔄 **事件驱动**: 以承诺为基础的请求/对事件发射人的回应模式
-   ⛓️ **多钱**: 支持Ethereum、Polygon、Base、Arbitrum和测试网
-   🖊️ **签名操作**: 信件签名和EIP-712打入的数据签名
-   💸 **交易支持**: 以内置错误处理发送交易
-   🌐 **横线**: 工作在网页浏览器和回放本地
-   ⚡ **轻巧**: 最佳捆绑大小的最小依赖性

## 安装

```bash
bun add @gemini-wallet/core
# or
npm install @gemini-wallet/core
# or
yarn add @gemini-wallet/core
# or
pnpm add @gemini-wallet/core
```

## 你可能不需要这个

**对于大多数应用,你应该使用Wagmi的内置双子座连接器取而代之:**

```typescript
import { gemini } from "wagmi/connectors";
import { createConfig } from "wagmi";

const config = createConfig({
  connectors: [
    gemini({
      appMetadata: {
        name: "My DApp",
        url: "https://mydapp.com",
        icon: "https://mydapp.com/icon.png",
      },
    }),
  ],
  // ... rest of wagmi config
});
```

> 🎯 **瓦格米融合组织**: 双子钱包作为默认连接器在wagmi@2.16.3+ & @wagmi/connectioners@5.9.3+中可用 📚 **瓦格米医生**数字 : [https://wagmi.sh/core/api/connectors/gemini 页面存档备份,存于互联网档案馆](https://wagmi.sh/core/api/connectors/gemini)  
> ⭐ **状态**: 随时提供

## 使用量

此核心SDK为高级使用案例提供多集分级:

### QQ 第1级: EVM 提供者( 为自定义执行推荐)

需要直接提供者访问或不使用 Wagmi 时使用 :

```typescript
import { GeminiWalletProvider } from "@gemini-wallet/core";

const provider = new GeminiWalletProvider({
  appMetadata: {
    name: "My DApp",
    url: "https://mydapp.com",
    icon: "https://mydapp.com/icon.png",
  },
  chain: { id: 42161 }, // Arbitrum One
});

// Connect and get accounts
const accounts = await provider.request({
  method: "eth_requestAccounts",
});

// Send transaction
const txHash = await provider.request({
  method: "eth_sendTransaction",
  params: [
    {
      from: accounts[0],
      to: "0x742E4C3B7dcD26e7Ca95C0Ad2F38C61f6F02C4c0",
      value: "0x38D7EA4C68000", // 0.001 ETH
    },
  ],
});

// Listen for events
provider.on("accountsChanged", (accounts) => {
  console.log("Accounts changed:", accounts);
});
```

### QQ 第 二级 : 直接钱包 API

使用钱包类进行精细控制 :

```typescript
import { GeminiWallet } from "@gemini-wallet/core";

const wallet = new GeminiWallet({
  appMetadata: {
    name: "My DApp",
    url: "https://mydapp.com",
    icon: "https://mydapp.com/icon.png",
  },
  chain: { id: 42161 },
});

// Connect
const accounts = await wallet.connect();

// Send transaction with error handling
const result = await wallet.sendTransaction({
  to: "0x742E4C3B7dcD26e7Ca95C0Ad2F38C61f6F02C4c0",
  value: "1000000000000000000", // 1 ETH in wei
});

if (result.error) {
  console.error("Transaction failed:", result.error);
} else {
  console.log("Transaction hash:", result.hash);
}
```

### 3级:低级通信

对于弹出通信的最大控制 :

```typescript
import { Communicator, GeminiSdkEvent } from "@gemini-wallet/core";

const communicator = new Communicator({
  appMetadata: {
    name: "My DApp",
    url: "https://mydapp.com",
    icon: "https://mydapp.com/icon.png",
  },
});

// Send connect request
const response = await communicator.postRequestAndWaitForResponse({
  event: GeminiSdkEvent.SDK_CONNECT,
  requestId: crypto.randomUUID(),
  chainId: 42161,
  origin: window.location.origin,
});

console.log("Connected address:", response.data.address);

// Listen for specific events
communicator
  .onMessage((message) => message.event === GeminiSdkEvent.SDK_DISCONNECT)
  .then(() => {
    console.log("User disconnected");
  });
```

## API 参考

### 双子钱包提供商

EIP-1193兼容 Ethereum 供应商实施.

```typescript
interface GeminiProviderConfig {
  appMetadata: AppMetadata;
  chain: Chain;
  onDisconnectCallback?: () => void;
  storage?: IStorage;
}
```

#### 方法

-   `request<T>(args: RpcRequestArgs): Promise<T>` - 发送RPC请求
-   `disconnect(): Promise<void>` - 断开钱包
-   `openSettings(): Promise<void>` - 打开钱包设置

#### 活动

-   `accountsChanged` - 账户变动时汇出
-   `chainChanged` - 当链条改变时被放出
-   `connect` - 接通了电话
-   `disconnect` - 断接时发送

### 双子钱包

高级使用大小写的直接钱包界面 .

```typescript
interface GeminiWalletConfig {
  appMetadata: AppMetadata;
  chain?: Chain;
  onDisconnectCallback?: () => void;
  storage?: IStorage;
}
```

#### 方法

-   `connect(): Promise<Address[]>` - 连接钱包
-   `sendTransaction(tx: TransactionRequest): Promise<SendTransactionResponse>` - 发送交易
-   `signData(params: SignMessageParameters): Promise<SignMessageResponse>` - 签名消息
-   `signTypedData(params: SignTypedDataParameters): Promise<SignTypedDataResponse>` - 签名输入的数据
-   `switchChain(params: SwitchChainParameters): Promise<string | null>` - 开锁
-   `openSettings(): Promise<void>` - 打开钱包设置

### 双子座

持续钱包状态的存储接口 .

```typescript
interface IStorage {
  setItem(key: string, value: string): Promise<void>;
  getItem(key: string): Promise<string | null>;
  removeItem(key: string): Promise<void>;
  storeObject<T>(key: string, item: T): Promise<void>;
  loadObject<T>(key: string, fallback: T): Promise<T>;
}
```

### 通讯员

低级交流班.

```typescript
interface CommunicatorConfigParams {
  appMetadata: AppMetadata;
  onDisconnectCallback?: () => void;
}
```

#### 方法

-   `postMessage(message: GeminiSdkMessage): Promise<void>` - 发送消息
-   `postRequestAndWaitForResponse<M, R>(request: GeminiSdkMessage): Promise<R>` - 发送请求等待
-   `onMessage<M, R>(predicate: (message: Partial<M>) => boolean): Promise<R>` - 听着留言
-   `waitForPopupLoaded(): Promise<Window>` - 等待弹出加载

### 信件类型

#### 双子座事件

所有支持事件的编号 :

-   `POPUP_LOADED` - 弹出窗口已装入
-   `POPUP_UNLOADED` - 弹出窗被关闭了
-   `POPUP_APP_CONTEXT` - 向弹出程序发送应用元数据
-   `SDK_CONNECT` - 连接钱包请求
-   `SDK_DISCONNECT` - 断开钱包请求
-   `SDK_SEND_TRANSACTION` - 发送交易请求
-   `SDK_SIGN_MESSAGE` - 签名信件请求
-   `SDK_SIGN_TYPED_DATA` - 签署输入的数据请求
-   `SDK_SWITCH_CHAIN` - 切换链请求
-   `ACCOUNTS_CHANGED` - 账户变更事件
-   `CHAIN_CHANGED` - 链已更改事件
-   `DISCONNECT` - 断开事件

### 支持的链条

双子钱包支持以下网络:

**主网:**

-   乙there(1)
-   仲裁一(42161) - 默认
-   OP 主网(10)
-   基地(8453)
-   多边形( 137)

**测试网 :**

-   塞波利亚(11155111)
-   阿比特伦·塞波利亚(421614)
-   OP 塞波利亚(11155420)
-   塞波利亚基地(84532)
-   多边形弹药( 80002)

### 常数

-   `SDK_BACKEND_URL`数字 : `"https://keys.gemini.com"`
-   `DEFAULT_CHAIN_ID`数字 : `42161` (标题一)
-   `SUPPORTED_CHAIN_IDS`: 支持链式ID阵列
-   `POPUP_WIDTH`数字 : `420`
-   `POPUP_HEIGHT`数字 : `650`

## 安全考虑

1.  **来源验证**: 所有信件都按预期来源验证
2.  **请求ID匹配**: 答复与使用独有身份证的请求相匹配
3.  **用户同意**: 所有动作都需要弹出时明确的用户批准
4.  **无私钥**: SDK 从未直接处理私钥

## 浏览器支持

-   克罗梅/第80号+
-   Firefox 78+ (英语)
-   萨法里14+
-   歌剧院 67+

## 试试双子座钱包

在行动中体验双子座钱包:

🔗 **[键.gemini.com](https://keys.gemini.com/)** - 尝试钱包接口,看看SDK集成是如何工作的

## 整合实例

核心SDK可以实现各种融合模式:

-   EIP-1193 任何 Web3 库的兼容提供者
-   移动平台自定义存储执行
-   有 TypeScript 支持的事件驱动架构
-   ++ 有自动链切换的多链支持
-   QQ 处理方便用户的错误消息出错

## 发展

这个项目使用 [阿宝](https://bun.sh/) 作为软件包管理器并构建工具.

### 设置

```bash
# Install dependencies
bun install

# Run tests
bun test

# Run tests in watch mode
bun test --watch

# Type checking
bun run typecheck

# Build the package
bun run build

# Development mode (watch mode)
bun run dev
```

### 可用的脚本

-   `bun run build` - 制作成套产品
-   `bun run dev` - 以监视模式发展
-   `bun run test` - 运行测试
-   `bun run test:watch` - 在监视模式下进行测试
-   `bun run typecheck` - 运行类型脚本类型检查
-   `bun run lint` - 运行 ESLint(需要配置)
-   `bun run lint:fix` - 自动解决ESLint问题

### 构建输出

构建过程生成:

-   `dist/index.js` - 节点的无害环境管理捆绑
-   `dist/index.d.ts` - 类型脚本声明
-   `dist/*.d.ts.map` - 申报原始地图

## 捐款

我们欢迎捐款! 请看我们的 [贡献指南](https://npmcn.com/package/%40gemini-wallet/core/CONTRIBUTING.md) 详细情况.

## 许可证

麻省理工学院执照 - 看 [自由主义](https://npmcn.com/package/%40gemini-wallet/core/LICENSE) 详细情况.

## 常见问题

### @gemini-wallet/core 是什么？

双子钱包集成核心SDK与弹出通信

### 如何安装 @gemini-wallet/core？

在项目目录运行 npm install @gemini-wallet/core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：viem（\>=2\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gemini-wallet/core 支持 TypeScript 吗？

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

### @gemini-wallet/core 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @gemini-wallet/core 可以商用吗？

@gemini-wallet/core 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gemini-wallet/core 的下载量有多少？

根据 npm 官方下载统计，@gemini-wallet/core 在 2026/10/16 – 2026/11/14 这 30 天内被下载 3,944,894 次，日均约 131,496 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gemini-wallet/core 还在维护吗？

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

