@nexus-cross/connect-kit-wagmi

wagmi connector adapters, connector registry, and the createCrossxConfig factory that produces a dual wagmi config — one side for CROSSx wallets (embedded, CROSSx Wallet, CROSSx Extension) and one side for third-party wallets routed through Reown (MetaMask, Binance). Use this package when you want the wallet plumbing without the built-in React UI.

• With React UI: install @nexus-cross/connect-kit-react instead — it already depends on this package.
• Headless: install this package directly and build your own button / modal.

Install

pnpm add @nexus-cross/connect-kit-wagmi wagmi viem @wagmi/core

Adapter SDKs are package dependencies, not app-level optional peers. Subpath imports still decide which adapter code enters your bundle:

| Import | Enables | |--------|---------| | @nexus-cross/connect-kit-wagmi/to-nexus | cross_wallet / cross_extension over the CROSS relay. | | @nexus-cross/connect-kit-wagmi/reown | metamask / binance over Reown WalletConnect. | | @nexus-cross/connect-kit-wagmi/embedded | cross_embedded social-login wallet. Client-only; do not import from server code. |

If you use or install a package graph that includes @to-nexus/*, add the private registry entry:

@to-nexus:registry=https://package.cross-nexus.com/repository/cross-sdk-js

Quick start

Dual-side config (cross + reown)

import { createCrossxConfig } from '@nexus-cross/connect-kit-wagmi';
import { toNexusAdapter } from '@nexus-cross/connect-kit-wagmi/to-nexus';
import { reownAdapter } from '@nexus-cross/connect-kit-wagmi/reown';
import { embeddedConnectorFactory } from '@nexus-cross/connect-kit-wagmi/embedded';

export const config = createCrossxConfig({
  crossProjectId: '...',
  reownProjectId: '...',
  appMetadata: { name: 'My DApp', url: 'https://example.com' },
  networks: [crossTestnet, bscTestnet],
  defaultNetwork: crossTestnet,
  ssr: true,                       // Next.js App Router
  crossProvider: toNexusAdapter(), // hosts cross_*
  reownProvider: reownAdapter(),   // hosts metamask / binance
  embeddedConnectorFactory,        // enables cross_embedded
  pinKeyboard: 'native',           // optional: 'virtual' (default), 'native', or a function
});

// config.crossWagmiConfig  — wagmi Config for cross side (nullable)
// config.reownWagmiConfig  — wagmi Config for reown side (nullable)
// config.connectorRegistry — unified wallet list for your UI

Single-side config

Drop either adapter when your DApp only needs one ecosystem — the unused side becomes null and the registry only exposes wallets from the side you wired.

// CROSSx-only
createCrossxConfig({
  /* ... */
  crossProvider: toNexusAdapter(),
});

// Reown-only
createCrossxConfig({
  /* ... */
  reownProvider: reownAdapter(),
});

Mounting the wagmi config manually

If you use @nexus-cross/connect-kit-react, the provider handles this for you. When using this package alone, remount <WagmiProvider> when the active side swaps so session state from the other side never leaks:

<WagmiProvider key={activeProvider} config={activeWagmiConfig}>
  {/* ... */}
</WagmiProvider>

Entrypoints

| Import | Purpose | |--------|---------| | @nexus-cross/connect-kit-wagmi | Core API: createCrossxConfig, connector registry, SSR helpers, icons, utilities. | | @nexus-cross/connect-kit-wagmi/to-nexus | toNexusAdapter() — CROSS relay via @to-nexus/appkit-adapter-wagmi. | | @nexus-cross/connect-kit-wagmi/reown | reownAdapter() — standard WalletConnect relay via @reown/appkit-adapter-wagmi. | | @nexus-cross/connect-kit-wagmi/embedded | embeddedConnectorFactory — in-app CROSSx wallet (social login). Client-only; don't import from server code. |

Main API

createCrossxConfig(options)

Produces a CrossxConfig bundle with:

• crossWagmiConfig / reownWagmiConfig — per-side wagmi Config, or null when that side isn't wired.
• connectorRegistry — ordered list of ConnectorEntry with walletId, providerKind ('cross' | 'reown'), connectorId, icons, and optional guideUrl / fallbackConnectorId.
• crossProvider / reownProvider — the adapter instances (exposes beforeConnect, closeModal, subscribeModalState, teardown).
• defaultProvider — which side to mount first ('cross' when both sides are wired, unless overridden via defaultProvider option).
• activeProviderStorageKey — localStorage key for persisting the active side across reloads. Clear this during full sign-out flows.

pinKeyboard option

Controls which keyboard appears when users enter their PIN for transaction confirmation in the embedded SDK's PIN modal.

pinKeyboard: 'native'  // or 'virtual' (default), or () => 'native' | 'virtual'

| Value | Effect | |-------|--------| | 'virtual' (default) | SDK's custom numpad on mobile. Desktop: input boxes. | | 'native' | OS numeric keyboard on mobile. Desktop: input boxes. | | () => 'native' \| 'virtual' | Function resolved each time PIN modal opens — enables dynamic selection. |

Connector registry

import { resolveCurrentWallet } from '@nexus-cross/connect-kit-wagmi';

// Map a live wagmi connectorId (+ last user intent) back to a WalletId.
const walletId = resolveCurrentWallet(
  config.connectorRegistry,
  activeConnector.id,
  lastIntent,
);

ConnectorEntry.aliasConnectorIds handles EIP-6963 promotion (e.g. io.metamask elevating over wagmi's default metaMask id).

SSR helpers

// app/layout.tsx (Next.js App Router)
import { headers } from 'next/headers';
import { cookieToCrossConnectKitState } from '@nexus-cross/connect-kit-wagmi';

export default async function RootLayout({ children }) {
  const cookie = (await headers()).get('cookie');
  const initialState = cookieToCrossConnectKitState(config, cookie);
  return (
    <html><body>
      <Providers initialState={initialState}>{children}</Providers>
    </body></html>
  );
}

Requires createCrossxConfig({ ssr: true }).

Utilities

import {
  clearWalletSessionStorage,   // nukes WC / appkit / wagmi localStorage keys
  DEFAULT_SESSION_STORAGE_PREFIXES,
  detectWallets, debugDetect,  // EIP-6963 + window globals + SDK probe
  DEFAULT_WALLET_REGISTRY,     // canonical wallet descriptors
  readWalletInfoTokens,        // read --wi-* CSS custom properties
  deriveSDKThemeTokensFromWalletInfo, // map --wi-* → SDKThemeTokens
} from '@nexus-cross/connect-kit-wagmi';

Icons

Bundler-agnostic data:image/svg+xml URIs. Safe to use as <img src>:

import {
  CROSSX_ICON, EXTENSION_ICON,
  METAMASK_ICON, BINANCE_ICON, WALLETCONNECT_ICON,
  GOOGLE_ICON, APPLE_ICON,
} from '@nexus-cross/connect-kit-wagmi';

Headless example

Using this package without @nexus-cross/connect-kit-react to build a custom UI is demonstrated in examples/next-wagmi-only.

Allowed dependencies

This package may depend on: @nexus-cross/connect-kit-core (ports / types), wagmi, viem, @wagmi/core, @nexus-cross/*, @to-nexus/*, and @reown/appkit*.

It must not depend on React or @nexus-cross/connect-kit-react — the dependency direction is react → core ← wagmi.

Compatibility

• wagmi>=2 <4, viem@^2, @wagmi/core>=2 <4
• Node 18+ / modern browsers

License

MIT