Wagmi SDK — API Reference

This page documents the public API surface of @nexus-cross/crossx-sdk-wagmi.

Exports

import {
  crossxConnector,         // Simple mode — SDK auto-created
  createCROSSxConnector,   // Advanced mode — inject your own SDK
  CROSSxEIP1193Provider,   // EIP-1193 Provider (rarely used directly)
} from '@nexus-cross/crossx-sdk-wagmi'

import type {
  CrossxConnectorOptions,
  CROSSxConnectorOptions,
  EIP1193RequestArguments,
} from '@nexus-cross/crossx-sdk-wagmi'

crossxConnector(options)

Creates a wagmi connector with an internally managed SDK instance.

import { crossxConnector } from '@nexus-cross/crossx-sdk-wagmi'

const connector = crossxConnector({
  projectId: 'YOUR_PROJECT_ID',
  appName: 'My DApp',
  theme: 'dark',
})

CrossxConnectorOptions

All fields from SDKConfig (except useMockWallet) plus:

defaultChainId accepts both CAIP-2 format ('eip155:612055') and numeric format (612055).

By default, wallet index is automatically persisted in localStorage (key: crossx-wallet-index). Provide custom callbacks only if you need a different storage mechanism (e.g. cookies for SSR).

createCROSSxConnector(options)

Creates a wagmi connector using an externally created SDK instance.

import { createCROSSxConnector } from '@nexus-cross/crossx-sdk-wagmi'
import { createCROSSxSDK } from '@nexus-cross/crossx-sdk-core'

const sdk = createCROSSxSDK({ projectId: 'YOUR_PROJECT_ID', appName: 'My DApp' })
const connector = createCROSSxConnector({ sdk })

CROSSxConnectorOptions

defaultChainId accepts both CAIP-2 format ('eip155:612055') and numeric format (612055).

By default, wallet index is automatically persisted in localStorage (key: crossx-wallet-index). Provide custom callbacks only if you need a different storage mechanism.

Connector Properties

Connector Methods

EIP-1193 Provider — Supported RPC Methods

Off-chain typed data signing: when domain.chainId is absent or 0, signTypedDataOffchain() is used internally.

EIP-1193 Provider — Helper Methods

These methods are available on the provider instance returned by connector.getProvider(). They are used to manage the active wallet index for multi-wallet scenarios.

Chain Configuration

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'] },
  },
})

Difference from @nexus-cross/crossx-sdk-core

Connect with Other Wallets Behavior

When showConnectOtherWallets is enabled in the SDK config, the login selector modal includes a "Connect with Other Wallets" button. When clicked:

1. SDK emits connectExternalWallet event
2. SDK throws CROSSxError(EXTERNAL_WALLET_REQUESTED)
3. Connector catches the error and converts it to UserRejectedRequestError
4. wagmi's connect() fails gracefully — isConnected stays false

The DApp should register an event listener to handle external wallet connections:

sdk.on('connectExternalWallet', () => {
  // Open MetaMask, WalletConnect, or any other connector
})

See Authentication — Connect with Other Wallets for full example.

Reconnect Behavior (v1.2.5+)

wagmi internally calls connector.setup() without await. In earlier SDK versions, this caused isAuthorized() to return false before SDK initialization completed, breaking automatic reconnection after page refresh.

Since v1.2.5, the connector's isAuthorized() automatically awaits sdk.whenReady() before checking authentication state. This eliminates the race condition — no workaround code is needed in your DApp.

// Internal connector behavior (automatic)
async isAuthorized() {
  await sdk.whenReady()          // waits for setup() → initialize() to finish
  return sdk.isAuthenticated()   // returns correct state
}

See Troubleshooting for details and migration from older versions.

Related

• Getting Started
• Authentication
• Wallet
• Troubleshooting
• Core SDK API Reference