Wagmi SDK — Getting Started

Skill — Download

This guide shows the minimum setup to use CROSSx with wagmi v2+.

Requirements

React 18+
wagmi v2+
viem v2+
@tanstack/react-query

1) Install

::: code-group

npm install @nexus-cross/crossx-sdk-core @nexus-cross/crossx-sdk-wagmi wagmi viem @tanstack/react-query

pnpm add @nexus-cross/crossx-sdk-core @nexus-cross/crossx-sdk-wagmi wagmi viem @tanstack/react-query

:::

2) Define chain

import { defineChain } from 'viem'

export const crossMainnet = defineChain({
  id: 612055,
  name: 'CROSS Mainnet',
  nativeCurrency: { name: 'CROSS', symbol: 'CROSS', decimals: 18 },
  rpcUrls: {
    default: { http: ['https://mainnet.crosstoken.io:22001'] },
  },
})

export const crossTestnet = defineChain({
  id: 612044,
  name: 'CROSS Testnet',
  nativeCurrency: { name: 'tCROSS', symbol: 'tCROSS', decimals: 18 },
  rpcUrls: {
    default: { http: ['https://testnet.crosstoken.io:22001'] },
  },
})

3) Configure wagmi

Simple mode (recommended)

SDK is created internally — just pass config options:

// wagmi.config.ts
import { createConfig, http } from 'wagmi'
import { crossxConnector } from '@nexus-cross/crossx-sdk-wagmi'
import { crossMainnet, crossTestnet } from './chains'

export const wagmiConfig = createConfig({
  connectors: [
    crossxConnector({
      projectId: 'YOUR_PROJECT_ID',
      appName: 'My DApp',
    }),
  ],
  chains: [crossMainnet, crossTestnet],
  transports: {
    [crossMainnet.id]: http(),
    [crossTestnet.id]: http(),
  },
})

Advanced mode (SDK injection)

For full control, create the SDK yourself and inject it:

// wagmi.config.ts
import { createConfig, http } from 'wagmi'
import { createCROSSxSDK } from '@nexus-cross/crossx-sdk-core'
import { createCROSSxConnector } from '@nexus-cross/crossx-sdk-wagmi'
import { crossMainnet } from './chains'

const sdk = createCROSSxSDK({
  projectId: 'YOUR_PROJECT_ID',
  appName: 'My DApp',
  theme: 'dark',
  debug: true,
})

export const wagmiConfig = createConfig({
  connectors: [createCROSSxConnector({ sdk })],
  chains: [crossMainnet],
  transports: { [crossMainnet.id]: http() },
})

4) Set up Providers

// main.tsx
import { WagmiProvider } from 'wagmi'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { wagmiConfig } from './wagmi.config'
import App from './App'

const queryClient = new QueryClient()

ReactDOM.createRoot(document.getElementById('root')!).render(
  <WagmiProvider config={wagmiConfig}>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </WagmiProvider>
)

5) Connect wallet

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

function App() {
  const { connectors, connect } = useConnect()
  const { address, isConnected } = useAccount()
  const { disconnect } = useDisconnect()

  const crossx = connectors.find(c => c.id === 'crossx')

  if (isConnected) {
    return (
      <div>
        <p>Address: {address}</p>
        <button onClick={() => disconnect()}>Disconnect</button>
      </div>
    )
  }

  return (
    <button onClick={() => connect({ connector: crossx! })}>
      Connect with CROSSx
    </button>
  )
}

Simple vs Advanced mode

Feature	Simple (`crossxConnector`)	Advanced (`createCROSSxConnector`)
SDK creation	Automatic	Manual
Custom adapters	Not available	Full control
Setup complexity	Minimal	More code
Recommended for	Most apps	Apps needing custom SDK config

Connector options

crossxConnector({
  projectId: 'YOUR_PROJECT_ID',
  appName: 'My DApp',            // required
  theme: 'dark',                  // optional, 'light' | 'dark'
})

See Core SDK Config for all available options.