@megaeth-labs/wallet-wagmi-connector

wagmi connector for the MOSS Wallet SDK.

Install

pnpm add @megaeth-labs/wallet-wagmi-connector

For RainbowKit UI integration, also install RainbowKit alongside wagmi's usual React dependencies:

pnpm add @rainbow-me/rainbowkit @tanstack/react-query wagmi viem

Usage

import { createConfig, http } from 'wagmi';
import { megaeth } from 'viem/chains';

import { mossWallet } from '@megaeth-labs/wallet-wagmi-connector';

export const config = createConfig({
  chains: [megaeth],
  connectors: [
    mossWallet({
      network: 'mainnet',
    }),
  ],
  transports: {
    [megaeth.id]: http(),
  },
});

With wagmi

Wrap your app with WagmiProvider and use wagmi hooks as you would with any other connector. The connector registers with id: 'mossWallet', type: 'injected', and name "MOSS Wallet".

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { WagmiProvider } from 'wagmi';

import { config } from './wagmi';

const queryClient = new QueryClient();

export function App({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
    </WagmiProvider>
  );
}

import { useAccount, useConnect, useDisconnect } from 'wagmi';

export function ConnectButton() {
  const { address, isConnected } = useAccount();
  const { connect, connectors } = useConnect();
  const { disconnect } = useDisconnect();
  const connector = connectors.find((c) => c.id === 'mossWallet');

  if (isConnected) {
    return (
      <button type="button" onClick={() => disconnect()}>
        {address}
      </button>
    );
  }

  return (
    <button
      type="button"
      disabled={!connector}
      onClick={() => connector && connect({ connector })}
    >
      Connect MOSS Wallet
    </button>
  );
}

Standard wagmi hooks such as useSignMessage, useSignTypedData, and useSendTransaction work out of the box. For useSendTransaction, only to, value, data, and chainId are forwarded — see the notes below.

Connector Metadata

The connector function carries generic wallet metadata for connector UIs and other wallet discovery surfaces. This information is not RainbowKit-specific.

import { mossWallet } from '@megaeth-labs/wallet-wagmi-connector';

const connector = mossWallet({ network: 'testnet' });

console.log(connector.metadata.id);   // "mossWallet"
console.log(connector.metadata.name); // "MOSS Wallet"
console.log(connector.metadata.icon); // data URI icon
console.log(connector.metadata.rdns); // "com.megaeth.account"

The same id, name, type, icon, and rdns are also set directly on the connector instance — the shape wagmi and wallet-selector UIs read when listing connectors.

EIP-6963

mossWallet(...) also announces MOSS as an EIP-6963 provider, automatically — there's nothing to call, nothing to configure, and nothing to know about. This is background ecosystem compatibility, not an integration path: if you're already using mossWallet(...) / mossWalletRainbowKit(...) / getMossWalletAppKitNetwork(...) as documented above, this changes nothing about how MOSS shows up for your users.

It only matters in two narrower cases: a bare wagmi Config with no connector listed at all (wagmi's multiInjectedProviderDiscovery, on by default, turns the announcement into a working connector on its own), or some other EIP-6963-aware code in the same page (a custom wallet picker, a UI kit's "detected wallets" section) that isn't using mossWalletRainbowKit(...) / getMossWalletAppKitNetwork(...) either. RainbowKit/ConnectKit/AppKit's own curated wallet lists don't read from EIP-6963 for wallets they explicitly list, so this doesn't change anything about those sections.

Not using the wagmi connector at all (e.g. a non-wagmi dapp)? Call the underlying function directly instead:

import { announceMossWalletProvider } from '@megaeth-labs/wallet-wagmi-connector';

announceMossWalletProvider({ network: 'testnet' });

With RainbowKit

RainbowKit only lists wallets registered through its own wallet list (or browser extensions discovered via EIP-6963), so the MegaETH connector needs a small RainbowKit Wallet adapter to show up. mossWalletRainbowKit from the /rainbowkit subpath is exactly that adapter — install RainbowKit, import it, and pass it into connectorsForWallets:

import { mossWalletRainbowKit } from '@megaeth-labs/wallet-wagmi-connector/rainbowkit';
import { connectorsForWallets } from '@rainbow-me/rainbowkit';
import { http } from 'viem';
import { megaethTestnet } from 'viem/chains';
import { createConfig } from 'wagmi';

const connectors = connectorsForWallets(
  [
    {
      groupName: 'Recommended',
      wallets: [() => mossWalletRainbowKit({ network: 'testnet' })],
    },
  ],
  {
    appName: 'Your App',
    projectId: 'your-project-id',
  },
);

export const config = createConfig({
  chains: [megaethTestnet],
  connectors,
  transports: {
    [megaethTestnet.id]: http(),
  },
});

Alongside RainbowKit's default wallets

getDefaultWallets() only ships RainbowKit's own curated list (MetaMask, Coinbase, Rainbow, WalletConnect, etc.) — MOSS will not appear there on its own, and getting added to that bundled list requires a PR accepted by the RainbowKit maintainers. To show MOSS in the same modal as those wallets today, merge getDefaultWallets()'s wallet groups with your own MOSS group when calling connectorsForWallets:

import {
  connectorsForWallets,
  getDefaultWallets,
} from '@rainbow-me/rainbowkit';

const { wallets } = getDefaultWallets();

const connectors = connectorsForWallets(
  [
    {
      groupName: 'Recommended',
      wallets: [() => mossWalletRainbowKit({ network: 'testnet' })],
    },
    ...wallets,
  ],
  {
    appName: 'Your App',
    projectId: 'your-project-id',
  },
);

This is self-service: no RainbowKit approval needed, and it works today. MOSS shows up as its own entry alongside RainbowKit's default wallets, the same way any other niche wallet not bundled by RainbowKit gets added.

To use different branding in RainbowKit, spread mossWalletRainbowKit's return value and override the fields you want to customize:

wallets: [
  () => ({
    ...mossWalletRainbowKit({ network: 'testnet' }),
    iconUrl: '/custom-wallet.svg',
  }),
],

Then wrap the app with both providers and import RainbowKit's styles once:

import '@rainbow-me/rainbowkit/styles.css';
import { RainbowKitProvider } from '@rainbow-me/rainbowkit';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { WagmiProvider } from 'wagmi';

import { config } from './wagmi';

const queryClient = new QueryClient();

export function App({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <RainbowKitProvider>{children}</RainbowKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

import { ConnectButton } from '@rainbow-me/rainbowkit';

export function RainbowKitConnect() {
  return <ConnectButton accountStatus="full" chainStatus="full" showBalance />;
}

The demo keeps both flows visible: a plain useConnect button and a separate RainbowKit ConnectButton, both backed by the same MegaETH connector.

With ConnectKit

ConnectKit is also wagmi-based, so pass the MegaETH connector through ConnectKit's getDefaultConfig(...). Watch out: passing connectors to getDefaultConfig replaces ConnectKit's own default connector list entirely — there's no merging — so connectors: [mossWallet(...)] on its own silently drops MetaMask, Coinbase Wallet, WalletConnect, and Safe, leaving MOSS as the only option. Build the array yourself with mossWallet(...) and ConnectKit's own getDefaultConnectors to keep them, with MOSS first — that way you stay in full control of exactly which wallets are included:

pnpm add connectkit @tanstack/react-query wagmi viem

import { mossWallet } from '@megaeth-labs/wallet-wagmi-connector';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import {
  ConnectKitButton,
  ConnectKitProvider,
  getDefaultConfig,
  getDefaultConnectors,
} from 'connectkit';
import { http } from 'viem';
import { megaethTestnet } from 'viem/chains';
import { createConfig, WagmiProvider } from 'wagmi';

const queryClient = new QueryClient();
const appName = 'Your App';
const walletConnectProjectId = 'your-walletconnect-project-id';

export const config = createConfig(
  getDefaultConfig({
    chains: [megaethTestnet],
    transports: {
      [megaethTestnet.id]: http(),
    },
    walletConnectProjectId,
    appName,
    appDescription: 'Your app description',
    appUrl: 'https://yourapp.example',
    appIcon: 'https://yourapp.example/icon.png',
    connectors: [
      mossWallet({ network: 'testnet' }),
      ...getDefaultConnectors({
        app: { name: appName },
        walletConnectProjectId,
      }),
    ],
  }),
);

export function App({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <ConnectKitProvider>
          <ConnectKitButton />
          {children}
        </ConnectKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

Only want MOSS and, say, WalletConnect? Skip getDefaultConnectors and list exactly the connectors you want instead — this pattern doesn't lock you into ConnectKit's default set.

With Reown AppKit (formerly Web3Modal)

For a controlled wagmi setup, pass the MegaETH connector as a custom connector to WagmiAdapter. AppKit doesn't accept viem Chain objects directly, so getMossWalletAppKitNetwork from the /appkit subpath converts whichever network you pass into the network shape AppKit expects, and getMossWalletConnectorImages maps MOSS's id/rdns to its icon for you.

pnpm add @reown/appkit @reown/appkit-adapter-wagmi @tanstack/react-query wagmi viem

import { mossWallet } from '@megaeth-labs/wallet-wagmi-connector';
import {
  getMossWalletAppKitNetwork,
  getMossWalletConnectorImages,
} from '@megaeth-labs/wallet-wagmi-connector/appkit';
import { createAppKit } from '@reown/appkit/react';
import { WagmiAdapter } from '@reown/appkit-adapter-wagmi';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { WagmiProvider } from 'wagmi';

const projectId = 'your-walletconnect-project-id';
const queryClient = new QueryClient();
const megaethTestnetNetwork = getMossWalletAppKitNetwork('testnet');

const wagmiAdapter = new WagmiAdapter({
  projectId,
  networks: [megaethTestnetNetwork],
  connectors: [mossWallet({ network: 'testnet' })],
});

createAppKit({
  adapters: [wagmiAdapter],
  projectId,
  networks: [megaethTestnetNetwork],
  metadata: {
    name: 'Your App',
    description: 'Your app description',
    url: 'https://yourapp.example',
    icons: ['https://yourapp.example/icon.png'],
  },
  connectorImages: getMossWalletConnectorImages(),
});

export function App({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={wagmiAdapter.wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <appkit-button />
        {children}
      </QueryClientProvider>
    </WagmiProvider>
  );
}

Custom Wallet Methods

Non-standard SDK methods are available through the provider request API:

const provider = await config.connectors[0].getProvider();

const balances = await provider.request({
  method: 'wallet_balances',
  params: [
    {
      tokens: ['0x4200000000000000000000000000000000000006'],
    },
  ],
});

These methods are also available as convenience methods on the provider — equivalent to the request() form above, and dispatched through the same handler:

const balances = await provider.balances({
  tokens: ['0x4200000000000000000000000000000000000006'],
});

Supported custom methods:

• wallet_authenticate
• wallet_balances
• wallet_callContract
• wallet_deposit
• wallet_getFromContract
• wallet_getPermissions
• wallet_grantPermissions
• wallet_manageAccount
• wallet_open
• wallet_revokePermissions
• wallet_send
• wallet_signData
• wallet_swap
• wallet_transfer

Notes

• mossWallet is the connector factory; megaWallet (and megaWalletRainbowKit, getMegaWalletAppKitNetwork, getMegaWalletConnectorImages) are kept as deprecated aliases of their mossWallet-prefixed equivalents for backwards compatibility — switch over when convenient, no rush.
• The connector advertises type: 'injected' so wallet-selector UIs (e.g. ConnectKit) treat the always-available embedded wallet as installed instead of prompting to install a browser extension. Wallet identity stays on id (mossWallet), name, and rdns — not on type.
• The connector is fixed-network per instance and does not support programmatic chain switching.
• The underlying wallet SDK can only be initialized once per page load, so one MegaETH connector configuration should be active at a time.
• If RainbowKit's connecting modal overlaps the wallet iframe, raise the MegaETH wallet iframe above the RainbowKit modal. The demo includes a scoped CSS override for the hosted and local wallet iframe URLs.
• wallet_callContract supports single and batch SDK requests.
• eth_sendTransaction is implemented through wallet-sdk.callContract(...) using the { address, data, value } path the wallet now supports.
• eth_sendTransaction intentionally rejects unsupported transaction fields instead of silently ignoring them.
• personal_sign supports plain text and hex payloads that can be decoded to UTF-8.

Commands

• pnpm build
• pnpm dev
• pnpm typecheck
• pnpm test
• pnpm check