@gemini-wallet/wagmi

⚠️ Temporary Package Notice

This is a temporary standalone package that provides Gemini Wallet support for Wagmi, default connector is included [email protected], and @wagmi/[email protected]

please migrate to using the official @wagmi/connectors package instead of this one. The API is identical, so migration will be seamless.

Overview

@gemini-wallet/wagmi provides a Wagmi connector that enables easy integration of Gemini Wallet into applications using Wagmi and viem. It handles all the complexity of wallet connection, transaction signing, and account management.

Features

• 🔌 Drop-in Wagmi Connector: Works seamlessly with existing Wagmi setup
• 🔐 Secure Communication: Built on top of @gemini-wallet/core
• 🔄 Auto-reconnection: Maintains wallet state across page reloads
• 📱 Cross-Platform: Works on desktop and mobile browsers
• ⚡ TypeScript Support: Full type safety and IntelliSense

Installation

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

Migration Path

When the official Wagmi integration is available, simply:

1. Remove this package:

   npm uninstall @gemini-wallet/wagmi

2. Update your imports:

   // Change from:
   import { gemini } from "@gemini-wallet/wagmi";
   
   // To:
   import { gemini } from "@wagmi/connectors";

3. Keep everything else the same - the API is identical!

Quick Start

Basic Setup

import { createConfig, http } from "wagmi";
import { mainnet, polygon, arbitrum } from "wagmi/chains";
import { gemini } from "@gemini-wallet/wagmi";

const config = createConfig({
  chains: [mainnet, polygon, arbitrum],
  connectors: [
    gemini({
      appMetadata: {
        name: "My DApp",
        description: "My awesome decentralized application",
        url: "https://mydapp.com",
        icons: ["https://mydapp.com/icon.png"],
      },
    }),
  ],
  transports: {
    [mainnet.id]: http(),
    [polygon.id]: http(),
    [arbitrum.id]: http(),
  },
});

With React

import { WagmiProvider } from "wagmi";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { useConnect, useAccount, useDisconnect } from "wagmi";

const queryClient = new QueryClient();

function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <ConnectButton />
      </QueryClientProvider>
    </WagmiProvider>
  );
}

function ConnectButton() {
  const { connect, connectors } = useConnect();
  const { address, isConnected } = useAccount();
  const { disconnect } = useDisconnect();

  if (isConnected) {
    return (
      <div>
        <p>Connected: {address}</p>
        <button onClick={() => disconnect()}>Disconnect</button>
      </div>
    );
  }

  const geminiConnector = connectors.find((c) => c.id === "gemini");

  return (
    <button onClick={() => connect({ connector: geminiConnector })}>
      Connect Gemini Wallet
    </button>
  );
}

Advanced Usage

Custom Configuration

import { gemini } from "@gemini-wallet/wagmi";

const connector = gemini({
  appMetadata: {
    name: "My DApp",
    description: "Description of your application",
    url: "https://mydapp.com",
    icons: ["https://mydapp.com/icon.png", "https://mydapp.com/[email protected]"],
  },
});

Handling Events

import { useAccount, useChainId } from "wagmi";
import { useEffect } from "react";

function MyComponent() {
  const { address, connector } = useAccount();
  const chainId = useChainId();

  useEffect(() => {
    if (!connector) return;

    const handleAccountsChanged = (accounts: string[]) => {
      console.log("Accounts changed:", accounts);
    };

    const handleChainChanged = (chainId: number) => {
      console.log("Chain changed:", chainId);
    };

    const provider = connector.getProvider();
    provider.then((p) => {
      p.on("accountsChanged", handleAccountsChanged);
      p.on("chainChanged", handleChainChanged);
    });

    return () => {
      provider.then((p) => {
        p.removeListener("accountsChanged", handleAccountsChanged);
        p.removeListener("chainChanged", handleChainChanged);
      });
    };
  }, [connector]);

  return <div>Current chain: {chainId}</div>;
}

Sending Transactions

import { useSendTransaction } from "wagmi";
import { parseEther } from "viem";

function SendTransaction() {
  const { sendTransaction } = useSendTransaction();

  const handleSend = () => {
    sendTransaction({
      to: "0x742d35Cc6634C0532925a3b844Bc9e7595f7F1eD",
      value: parseEther("0.01"),
    });
  };

  return <button onClick={handleSend}>Send 0.01 ETH</button>;
}

Signing Messages

import { useSignMessage } from "wagmi";

function SignMessage() {
  const { signMessage, data, isSuccess } = useSignMessage();

  const handleSign = () => {
    signMessage({ message: "Hello from Gemini Wallet!" });
  };

  return (
    <div>
      <button onClick={handleSign}>Sign Message</button>
      {isSuccess && <p>Signature: {data}</p>}
    </div>
  );
}

API Reference

gemini(parameters)

Creates a Wagmi connector instance for Gemini Wallet.

Parameters

• parameters (optional): Configuration object
  • appMetadata (optional): Application metadata
    • name: Your application name
    • description: Brief description of your app
    • url: Your application URL
    • icons: Array of icon URLs

Returns

A Wagmi connector instance with the following properties:

• id: "gemini"
• name: "Gemini Wallet"
• type: "gemini"
• icon: Gemini Wallet logo

Connector Methods

All standard Wagmi connector methods are supported:

• connect({ chainId? }): Connect to wallet
• disconnect(): Disconnect from wallet
• getAccounts(): Get connected accounts
• getChainId(): Get current chain ID
• getProvider(): Get the provider instance
• isAuthorized(): Check if already authorized
• switchChain({ chainId }): Switch to a different chain

Supported Chains

Gemini Wallet supports all EVM-compatible chains. Configure your desired chains in the Wagmi config.

Error Handling

import { useConnect } from "wagmi";

function ConnectWithErrorHandling() {
  const { connect, error, isError } = useConnect();

  const handleConnect = async () => {
    try {
      await connect({ connector: geminiConnector });
    } catch (err) {
      if (err.message.includes("user rejected")) {
        console.log("User cancelled connection");
      }
    }
  };

  return (
    <div>
      <button onClick={handleConnect}>Connect</button>
      {isError && <p>Error: {error?.message}</p>}
    </div>
  );
}

Best Practices

1. Always provide app metadata: This helps users identify your application
2. Handle disconnection gracefully: Listen for disconnect events
3. Check chain compatibility: Ensure your app supports the user's selected chain
4. Implement proper error handling: Provide clear feedback to users

Troubleshooting

Common Issues

1. Popup blocked: Ensure popups are enabled for wallet connection
2. Chain not configured: Add required chains to your Wagmi config
3. Connection rejected: User cancelled the connection request

Status & Roadmap

• ✅ Current: Standalone package providing Gemini Wallet support
• 🚧 In Progress: Official Wagmi integration PR #4759 under review
• 🎯 Future: Migrate to official @wagmi/connectors when available

This package will be deprecated once the official Wagmi integration is merged. We'll provide clear migration instructions and support during the transition.

Contributing

Since this is a temporary package, we recommend contributing to the main Wagmi repository instead. However, if you find issues with this temporary implementation, please report them in our issues.

License

MIT License - see LICENSE for details.