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'

Rebrand aliases (ONEpocket)

As part of the ONEpocket rebrand, every crossx* export also ships under a ONEpocket name. The aliases are identical in behavior — pick one naming and use it consistently:

crossxConnector(options)

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

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

Creates a wagmi connector with an internally managed SDK instance. Use this for most setups — the connector handles SDK creation, initialization, and lifecycle automatically. For cases where you need to share a single SDK instance across wagmi and non-wagmi code, use createCROSSxConnector() instead.

CrossxConnectorOptions

All fields from SDKConfig (except useMockWallet) plus:

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

By default, the wallet index and the active wallet address are automatically persisted in localStorage (keys: crossx-wallet-index, crossx-wallet-address). Provide custom callbacks only if you need a different storage mechanism (e.g. cookies for SSR).

createCROSSxConnector(options)

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 })

Creates a wagmi connector using an externally created SDK instance. Use this when you need to share a single SDK instance between wagmi and other parts of your application (e.g. a React context, a React Native bridge, or server-side code).

CROSSxConnectorOptions

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

By default, the wallet index and the active wallet address are automatically persisted in localStorage (keys: crossx-wallet-index, crossx-wallet-address). Provide custom callbacks only if you need a different storage mechanism.

Connector Properties

The returned connector exposes the following identity properties, used by wagmi internally to identify the connector.

connector.name follows the wallet brand name (WALLET_BRAND_NAME from @nexus-cross/crossx-sdk-core), which is 'ONEpocket' since the rebrand. connector.id remains 'crossx' for backward compatibility — keep using connectors.find(c => c.id === 'crossx').

Connector Methods

These methods conform to the wagmi connector interface. In most cases you interact with them indirectly through wagmi hooks (useConnect, useDisconnect, useSwitchChain, etc.).

EIP-1193 Provider — Supported RPC Methods

The EIP-1193 provider returned by connector.getProvider() handles the following JSON-RPC methods. Signing and transaction methods route through the SDK confirmation modal flow; read methods are proxied to the chain RPC.

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 manage the active wallet index for multi-wallet scenarios and are called by the connector internally after wallet selection.

Chain Configuration

Use defineChain from viem to configure ONEchain for wagmi:

import { defineChain } from 'viem'

export const oneMainnet = defineChain({
  id: 612055,
  name: 'ONEchain Mainnet',
  nativeCurrency: { name: 'ONE', symbol: 'ONE', decimals: 18 },
  rpcUrls: {
    default: { http: ['https://mainnet.onechain.nexus:22001'] },
  },
})

export const oneTestnet = defineChain({
  id: 612044,
  name: 'ONEchain Testnet',
  nativeCurrency: { name: 'tONE', symbol: 'tONE', decimals: 18 },
  rpcUrls: {
    default: { http: ['https://testnet.onechain.nexus: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

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

Since v1.2.5 — and in every 2.x release — the connector's isAuthorized() automatically ensures SDK initialization (including session restore) before checking authentication state. This eliminates the race condition — no workaround code is needed in your DApp.

// Internal connector behavior (automatic)
async isAuthorized() {
  await ensureSdkInitialized()   // waits for 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