@gemini-wallet/core

中文文档
0.3.2发布于 2025/11/11MITTypeScriptESM + CJS构建来源已验证近 30 天下载 394.5万

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

中文使用文档
文档目录26 节
  1. 概览
  2. 特征
  3. 安装
  4. 你可能不需要这个
  5. 使用量
  6. QQ 第1级: EVM 提供者( 为自定义执行推荐)
  7. QQ 第 二级 : 直接钱包 API
  8. 3级:低级通信
  9. API 参考
  10. 双子钱包提供商
  11. 双子钱包
  12. 双子座
  13. 通讯员
  14. 信件类型
  15. 支持的链条
  16. 常数
  17. 安全考虑
  18. 浏览器支持
  19. 试试双子座钱包
  20. 整合实例
  21. 发展
  22. 设置
  23. 可用的脚本
  24. 构建输出
  25. 捐款
  26. 许可证

@ gemini- wallet/ 核心

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

概览

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

特征

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

安装

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

你可能不需要这个

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

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
});

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

使用量

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

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

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

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

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级:低级通信

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

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 供应商实施.

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 - 断接时发送

双子钱包

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

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> - 打开钱包设置

双子座

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

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>;
}

通讯员

低级交流班.

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 - 尝试钱包接口,看看SDK集成是如何工作的

整合实例

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

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

发展

这个项目使用 阿宝 作为软件包管理器并构建工具.

设置

# 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 - 申报原始地图

捐款

我们欢迎捐款! 请看我们的 贡献指南 详细情况.

许可证

麻省理工学院执照 - 看 自由主义 详细情况.

版本与发布记录

@gemini-wallet/core 共发布 7 个版本,首次发布于 2025/07/15;过去 12 个月发布了 0 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.3.2latest2025/11/111 年前
0.3.12025/10/241.1 年前
0.3.02025/09/101.2 年前
0.2.02025/08/131.3 年前
0.1.12025/08/091.3 年前
0.1.02025/08/091.3 年前

关于 @gemini-wallet/core 的常见问题

@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 和提交记录判断。