Package Exports
- @gemini-wallet/wagmi
Readme
@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
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:
Remove this package:
npm uninstall @gemini-wallet/wagmi
Update your imports:
// Change from: import { gemini } from "@gemini-wallet/wagmi"; // To: import { gemini } from "@wagmi/connectors";
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/icon@2x.png"],
},
});
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 objectappMetadata
(optional): Application metadataname
: Your application namedescription
: Brief description of your appurl
: Your application URLicons
: 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 walletdisconnect()
: Disconnect from walletgetAccounts()
: Get connected accountsgetChainId()
: Get current chain IDgetProvider()
: Get the provider instanceisAuthorized()
: Check if already authorizedswitchChain({ 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
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.