WalletConnect connector for wagmi
npm install @walletconnect/wagmi-connector


Official WalletConnect connector for wagmi.
``bashUsing pnpm
pnpm add @walletconnect/wagmi-connector
Usage
$3
`typescript
import { createConfig, http } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'
import { injected } from 'wagmi/connectors'
import { walletConnect } from '@walletconnect/wagmi-connector'export const config = createConfig({
chains: [mainnet, sepolia],
connectors: [
injected(),
walletConnect({
projectId: 'YOUR_WALLETCONNECT_PROJECT_ID' // dashboard.reown.com
}),
],
transports: {
[mainnet.id]: http(),
},
})
`$3
`typescript
walletConnect({
projectId: string // Required: Your WalletConnect project ID
showQrModal?: boolean // Optional: Show QR modal (default: true)
isNewChainsStale?: boolean // Optional: Treat new chains as stale (default: true)
metadata?: { // Optional: App metadata
name: string
description: string
url: string
icons: string[]
}
qrModalOptions?: { // Optional: QR modal configuration
enableMobileFullScreen?: boolean
}
})
`$3
If you're migrating from the built-in wagmi connector:
Before:
`typescript
import { walletConnect } from 'wagmi/connectors'
`After:
`typescript
import { walletConnect } from '@walletconnect/wagmi-connector'
`That's it! The API is exactly the same.
Local Development & Testing
$3
`bash
Install dependencies
pnpm installBuild the package
pnpm buildClean build artifacts
pnpm clean
`$3
1. In the connector package directory (
~/Code/wagmi-connector):
`bash
# Build the package
pnpm build
# Link it globally
pnpm link --global
`2. In your test application:
`bash
# Link the connector
pnpm link --global @walletconnect/wagmi-connector
`3. Update your imports:
`typescript
// Replace wagmi/connectors import
import { walletConnect } from '@walletconnect/wagmi-connector'
`4. Test the functionality:
- Run your dev server
- Test WalletConnect connection
- Verify all features work correctly
$3
`bash
In your test app
pnpm unlink @walletconnect/wagmi-connectorIn the connector package
pnpm unlink --global
`Requirements
- wagmi: ^2.0.0
- viem: ^2.0.0
- @wagmi/core: ^2.22.0
- TypeScript: >=5.0.4 (optional)
TypeScript
This package is built with TypeScript and includes type definitions. All types are exported from the main entry point:
`typescript
import { walletConnect, type WalletConnectParameters } from '@walletconnect/wagmi-connector'
`API Reference
$3
Creates a WalletConnect connector instance.
#### Parameters
-
projectId (required): Your WalletConnect Cloud project ID. Get one at cloud.walletconnect.com
- showQrModal (optional): Whether to show the QR modal for connection. Default: true
- isNewChainsStale (optional): How to handle newly added chains. Default: true
- true: Disconnect and require reconnection when new chains are added
- false: Attempt to continue connection (may error if wallet doesn't support dynamic chains)
- metadata (optional): Application metadata shown in wallet during connection
- qrModalOptions (optional): Configuration options for the QR modal
- enableMobileFullScreen: Enable full-screen mode on mobile devices#### Returns
A wagmi connector instance that can be used in
createConfig.Examples
$3
`typescript
walletConnect({
projectId: 'YOUR_PROJECT_ID',
metadata: {
name: 'My DApp',
description: 'My awesome decentralized app',
url: 'https://myapp.com',
icons: ['https://myapp.com/icon.png']
}
})
`$3
`typescript
walletConnect({
projectId: 'YOUR_PROJECT_ID',
showQrModal: false
})
`$3
`typescript
walletConnect({
projectId: 'YOUR_PROJECT_ID',
isNewChainsStale: false // Allow dynamic chain additions
})
`$3
`typescript
walletConnect({
projectId: 'YOUR_PROJECT_ID',
qrModalOptions: {
enableMobileFullScreen: true // Enable full-screen on mobile
}
})
`Troubleshooting
$3
Make sure you've installed
@walletconnect/ethereum-provider:
`bash
pnpm add @walletconnect/ethereum-provider
`$3
Ensure you have the correct peer dependencies installed:
`bash
pnpm add wagmi viem @wagmi/core
`$3
1. Verify your WalletConnect project ID is correct
2. Check that your chains are properly configured in wagmi
3. Ensure your RPC endpoints are accessible
License
See LICENSE.md for details. This project is licensed under the WalletConnect Community License Agreement.
$3
Portions © 2025 Reown, Inc. All Rights Reserved
This project includes code derived from wagmi, which is licensed under the MIT License. See NOTICE for full attribution details.
Links
- WalletConnect Documentation
- wagmi Documentation
- Get a Project ID
Contributing
This package is maintained by WalletConnect. We welcome contributions! Please follow these guidelines:
$3
1. Clone the repository:
`bash
git clone https://github.com/walletconnect/wagmi-connector.git
cd wagmi-connector
`2. Install dependencies:
`bash
pnpm install
`3. Build the package:
`bash
pnpm build
`$3
`bash
Run tests once
pnpm testRun tests in watch mode
pnpm test:watchRun tests with coverage
pnpm test:coverage
`$3
Before submitting a PR, ensure your code passes all checks:
`bash
Type checking
pnpm typecheckLinting
pnpm lintFormat code
pnpm formatCheck formatting
pnpm prettier:check
`$3
1. Fork the repository
2. Create a feature branch (
git checkout -b feature/amazing-feature)
3. Make your changes
4. Run all tests and linting checks
5. Commit your changes using Conventional Commits
6. Push to your fork and submit a Pull Request$3
This project uses Changesets for version management.
1. Make your changes
2. Add a changeset:
`bash
pnpm changeset
``The repository uses GitHub Actions for continuous integration:
- PR Checks: Runs on all pull requests, testing build, linting, type checking, and tests on Node.js 18.x and 20.x
- Publish: Automatically publishes to npm when version PRs are merged to main
- Canary Releases: Manual workflow for publishing canary versions
Please open an issue in the repository to report bugs or request features.