@gemini-wallet/wagmi

@gemini-wallet/wagmi

Wagmi connector for seamless Gemini Wallet integration in your dApps.

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

Quick Start

Basic Setup

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

const config = createConfig({
  chains: [mainnet, polygon, arbitrum],
  connectors: [
    geminiWagmiConnector({
      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 === 'geminiWallet');

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

Advanced Usage

Custom Configuration

import { geminiWagmiConnector } from '@gemini-wallet/wagmi';

const connector = geminiWagmiConnector({
  // Required app metadata
  name: 'My DApp',
  description: 'Description of your application',
  url: 'https://mydapp.com',
  icons: [
    'https://mydapp.com/icon.png',
    'https://mydapp.com/[e-mail]'
  ]
});

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

geminiWagmiConnector(appMetadata)

Creates a Wagmi connector instance for Gemini Wallet.

Parameters

• 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: "geminiWallet"
• name: "Gemini Wallet"
• type: "geminiWallet"

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

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

Troubleshooting

Common Issues

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

Contributing

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

License

MIT License - see LICENSE for details.