@gemini-wallet/core

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

Core SDK for Gemini Wallet integration with popup communication

原始使用文档
文档目录26 节
  1. Overview
  2. Features
  3. Installation
  4. ⚠️ YOU MIGHT NOT NEED THIS
  5. Usage
  6. 🚀 Level 1: EVM Provider (Recommended for Custom Implementat…
  7. ⚡ Level 2: Direct Wallet API
  8. ⚙️ Level 3: Low-Level Communication
  9. API Reference
  10. GeminiWalletProvider
  11. GeminiWallet
  12. GeminiStorage
  13. Communicator
  14. Message Types
  15. Supported Chains
  16. Constants
  17. Security Considerations
  18. Browser Support
  19. Try Gemini Wallet
  20. Integration Examples
  21. Development
  22. Setup
  23. Available Scripts
  24. Build Output
  25. Contributing
  26. License

@gemini-wallet/core

Complete SDK for integrating with Gemini Wallet, providing wallet connection, transaction signing, and EVM provider functionality.

Overview

@gemini-wallet/core is a comprehensive wallet SDK that provides everything needed to integrate Gemini Wallet into your application. It includes a complete EVM-compatible provider, wallet connection management, secure storage, and seamless popup-based user interactions.

Features

  • 🔗 EVM Provider: Complete Ethereum provider implementation (EIP-1193 compatible)
  • 🔒 Secure Communication: PostMessage-based cross-origin communication
  • 🪟 Popup Management: Automatic popup window lifecycle management
  • 💾 Storage Layer: Persistent storage with localStorage fallback
  • 🔄 Event-Driven: Promise-based request/response pattern with event emitters
  • ⛓️ Multi-Chain: Support for Ethereum, Polygon, Base, Arbitrum, and testnets
  • 🖊️ Sign Operations: Message signing and EIP-712 typed data signing
  • 💸 Transaction Support: Send transactions with built-in error handling
  • 🌐 Cross-Platform: Works in web browsers and React Native
  • ⚡ Lightweight: Minimal dependencies for optimal bundle size

Installation

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

⚠️ YOU MIGHT NOT NEED THIS

For most applications, you should use Wagmi's built-in Gemini connector instead:

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 Integration: Gemini Wallet is available as a default connector in [email protected]+ & @wagmi/[email protected]+ 📚 Wagmi Docs: https://wagmi.sh/core/api/connectors/gemini
⭐ Status: Readily available

Usage

This core SDK provides multiple integration levels for advanced use cases:

Use when you need direct provider access or aren't using 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);
});

⚡ Level 2: Direct Wallet API

Use the wallet class for fine-grained control:

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

⚙️ Level 3: Low-Level Communication

For maximum control over the popup communication:

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 Reference

GeminiWalletProvider

EIP-1193 compatible Ethereum provider implementation.

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

Methods

  • request<T>(args: RpcRequestArgs): Promise<T> - Send RPC requests
  • disconnect(): Promise<void> - Disconnect wallet
  • openSettings(): Promise<void> - Open wallet settings

Events

  • accountsChanged - Emitted when accounts change
  • chainChanged - Emitted when chain changes
  • connect - Emitted on connection
  • disconnect - Emitted on disconnection

GeminiWallet

Direct wallet interface for advanced use cases.

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

Methods

  • connect(): Promise<Address[]> - Connect to wallet
  • sendTransaction(tx: TransactionRequest): Promise<SendTransactionResponse> - Send transaction
  • signData(params: SignMessageParameters): Promise<SignMessageResponse> - Sign message
  • signTypedData(params: SignTypedDataParameters): Promise<SignTypedDataResponse> - Sign typed data
  • switchChain(params: SwitchChainParameters): Promise<string | null> - Switch chains
  • openSettings(): Promise<void> - Open wallet settings

GeminiStorage

Storage interface for persisting wallet state.

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

Communicator

Low-level communication class.

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

Methods

  • postMessage(message: GeminiSdkMessage): Promise<void> - Send message
  • postRequestAndWaitForResponse<M, R>(request: GeminiSdkMessage): Promise<R> - Send request and wait
  • onMessage<M, R>(predicate: (message: Partial<M>) => boolean): Promise<R> - Listen for messages
  • waitForPopupLoaded(): Promise<Window> - Wait for popup to load

Message Types

GeminiSdkEvent

Enumeration of all supported events:

  • POPUP_LOADED - Popup window has loaded
  • POPUP_UNLOADED - Popup window was closed
  • POPUP_APP_CONTEXT - App metadata sent to popup
  • SDK_CONNECT - Connect wallet request
  • SDK_DISCONNECT - Disconnect wallet request
  • SDK_SEND_TRANSACTION - Send transaction request
  • SDK_SIGN_MESSAGE - Sign message request
  • SDK_SIGN_TYPED_DATA - Sign typed data request
  • SDK_SWITCH_CHAIN - Switch chain request
  • ACCOUNTS_CHANGED - Accounts changed event
  • CHAIN_CHANGED - Chain changed event
  • DISCONNECT - Disconnect event

Supported Chains

Gemini Wallet supports the following networks:

Mainnets:

  • Ethereum (1)
  • Arbitrum One (42161) - Default
  • OP Mainnet (10)
  • Base (8453)
  • Polygon (137)

Testnets:

  • Sepolia (11155111)
  • Arbitrum Sepolia (421614)
  • OP Sepolia (11155420)
  • Base Sepolia (84532)
  • Polygon Amoy (80002)

Constants

  • SDK_BACKEND_URL: "https://keys.gemini.com"
  • DEFAULT_CHAIN_ID: 42161 (Arbitrum One)
  • SUPPORTED_CHAIN_IDS: Array of supported chain IDs
  • POPUP_WIDTH: 420
  • POPUP_HEIGHT: 650

Security Considerations

  1. Origin Validation: All messages are validated against the expected origin
  2. Request ID Matching: Responses are matched to requests using unique IDs
  3. User Consent: All actions require explicit user approval in the popup
  4. No Private Keys: The SDK never handles private keys directly

Browser Support

  • Chrome/Edge 80+
  • Firefox 78+
  • Safari 14+
  • Opera 67+

Try Gemini Wallet

Experience Gemini Wallet in action:

🔗 keys.gemini.com - Try the wallet interface and see how the SDK integrations work

Integration Examples

The core SDK enables various integration patterns:

  • ✅ EIP-1193 compatible provider for any web3 library
  • ✅ Custom storage implementations for mobile platforms
  • ✅ Event-driven architecture with TypeScript support
  • ✅ Multi-chain support with automatic chain switching
  • ✅ Error handling with user-friendly error messages

Development

This project uses Bun as the package manager and build tool.

Setup

# 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

Available Scripts

  • bun run build - Build the package for production
  • bun run dev - Build in watch mode for development
  • bun run test - Run tests
  • bun run test:watch - Run tests in watch mode
  • bun run typecheck - Run TypeScript type checking
  • bun run lint - Run ESLint (requires configuration)
  • bun run lint:fix - Fix ESLint issues automatically

Build Output

The build process generates:

  • dist/index.js - ESM bundle for Node.js
  • dist/index.d.ts - TypeScript declarations
  • dist/*.d.ts.map - Source maps for declarations

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT License - see LICENSE for details.

版本与发布记录

@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 是什么?

Core SDK for Gemini Wallet integration with popup communication

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