npm package: @gemini-wallet/wagmi
Description: Wagmi connector for Gemini Wallet integration
Author: Gemini
Latest version: 0.2.1

# @gemini-wallet/wagmi

**⚠️ Temporary Package Notice**

This is a temporary standalone package that provides Gemini Wallet support for Wagmi, default connector is included wagmi@2.16.3, and @wagmi/connectors@5.9.3

**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

```bash
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:**

   ```bash
   npm uninstall @gemini-wallet/wagmi
   ```

2. **Update your imports:**

   ```typescript
   // 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

```typescript
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

```tsx
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

```typescript
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/icon@2x.png"],
  },
});
```

### Handling Events

```typescript
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

```typescript
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

```typescript
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

```typescript
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](https://github.com/wevm/wagmi/pull/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](https://github.com/gemini/gemini-wallet-wagmi/issues).

## License

MIT License - see [LICENSE](LICENSE) for details.