Guides
NEXUS
Guides
NEXUS
Start typing to search…

crossx-20-js-wagmi

CROSSx Wagmi Skill

Documentation

Dependency

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

Instructions

Identify the request category first, then make the smallest TypeScript/React changes that fit the existing wagmi project structure.

Treat the CROSSx wagmi documentation linked above as the primary source for SDK usage, integration flow, and sample patterns.

If the bundled wagmi docs do not fully answer the question or the latest SDK behavior is unclear, prefer the official cross MCP server before unrelated documentation sources.

File Discovery

Before editing, find the existing integration points for wagmi config, connector setup, provider layout, and wallet-related actions.

Check these first when they exist:

  • package.json (dependency setup)
  • wagmi config file (e.g. wagmi.config.ts, wagmi.ts)
  • chain definition file
  • App root providers setup (WagmiProvider, QueryClientProvider)
  • Existing connect, account, or transaction components

Prefer extending existing integration points over introducing new wrappers or config files.

Request Classification

Classify each request into one or more of these categories before writing code:

  • SDK setup: package install, chain definition via defineChain, wagmi config with crossxConnector or createCROSSxConnector, provider layout
  • Wallet connection: useConnect, useAccount, useDisconnect — connect/disconnect flow using CROSSx connector
  • Signing and transactions: useSignMessage, useSignTypedData, useSendTransaction, useWaitForTransactionReceipt — standard wagmi hooks
  • RPC and chain access: useBalance, useReadContract, useWriteContract, usePublicClient — standard wagmi/viem hooks
  • Advanced SDK access: keep a reference to the SDK instance for direct SDK method access (e.g. getBalance, walletRpc, getUserInfo)

If a request spans multiple categories, handle connector and provider setup before wallet connection, signing, or RPC work.

Key Types Reference

Connector Options

// Simple mode — SDK is created internally from config
type CrossxConnectorOptions = Omit<SDKConfig, 'useMockWallet'> & {
  defaultChainId?: string | number;
  getStoredWalletIndex?: () => number;
  onWalletIndexChanged?: (index: number) => void;
  openConnectOtherWallet?: () => void;
};

// Advanced mode — inject an existing SDK instance
interface CROSSxConnectorOptions {
  sdk: CROSSxSDK;
  defaultChainId?: string | number;
  getStoredWalletIndex?: () => number;
  onWalletIndexChanged?: (index: number) => void;
  openConnectOtherWallet?: () => void;
}

CROSS Chain Definitions

// Define with viem's defineChain or inline object
const crossMainnet = {
  id: 612055,
  name: 'CROSS Mainnet',
  nativeCurrency: { name: 'CROSS', symbol: 'CROSS', decimals: 18 },
  rpcUrls: {
    default: { http: ['https://rpc.crossmainnet.io'] },
  },
  blockExplorers: {
    default: { name: 'CROSSxScan', url: 'https://scan.crossmainnet.io' },
  },
} as const satisfies Chain;

const crossTestnet = {
  id: 612044,
  name: 'CROSS Testnet',
  testnet: true,
  nativeCurrency: { name: 'CROSS', symbol: 'CROSS', decimals: 18 },
  rpcUrls: {
    default: { http: ['https://rpc.crosstestnet.io'] },
  },
  blockExplorers: {
    default: { name: 'CROSSxScan (Testnet)', url: 'https://scan.crosstestnet.io' },
  },
} as const satisfies Chain;

Wagmi Exports

// From @nexus-cross/crossx-sdk-wagmi
export { crossxConnector } from './connector';         // simple mode
export { createCROSSxConnector } from './connector';   // advanced mode
export { CROSSxEIP1193Provider } from './provider';    // EIP-1193 provider

Core API Signatures

Simple Mode (recommended for most apps)

import { crossxConnector } from '@nexus-cross/crossx-sdk-wagmi';
import { createConfig, http } from 'wagmi';

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

Advanced Mode (custom SDK configuration)

import { createCROSSxConnector } from '@nexus-cross/crossx-sdk-wagmi';
import { createCROSSxSDK, ChainId } from '@nexus-cross/crossx-sdk-core';
import { createConfig, http } from 'wagmi';

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

const config = createConfig({
  chains: [crossMainnet, crossTestnet],
  connectors: [
    createCROSSxConnector({
      sdk,
      defaultChainId: ChainId.CROSS_MAINNET,
      openConnectOtherWallet: () => {
        // open external wallet modal (e.g. MetaMask)
      },
    }),
  ],
  transports: {
    [crossMainnet.id]: http(),
    [crossTestnet.id]: http(),
  },
});

Wallet Connection

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

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

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

  const crossx = connectors.find((c) => c.id === 'crossx');
  return (
    <button onClick={() => crossx && connect({ connector: crossx })}>
      Connect CROSSx
    </button>
  );
}

Standard Wagmi Hooks

// Sign message
import { useSignMessage } from 'wagmi';
const { signMessage } = useSignMessage();
signMessage({ message: 'Hello CROSSx' });

// Send transaction
import { useSendTransaction, useWaitForTransactionReceipt } from 'wagmi';
const { sendTransaction, data: hash } = useSendTransaction();
const { data: receipt } = useWaitForTransactionReceipt({ hash });

sendTransaction({
  to: '0xReceiverAddress',
  value: parseEther('1'),
});

// Read balance
import { useBalance } from 'wagmi';
const { data: balance } = useBalance({ address });

Code Examples

Full Wagmi App Setup

// wagmi-config.ts
import { createConfig, http } from 'wagmi';
import { type Chain } from 'viem';
import { createCROSSxSDK, ChainId } from '@nexus-cross/crossx-sdk-core';
import { createCROSSxConnector } from '@nexus-cross/crossx-sdk-wagmi';

const crossMainnet = {
  id: 612055,
  name: 'CROSS Mainnet',
  nativeCurrency: { name: 'CROSS', symbol: 'CROSS', decimals: 18 },
  rpcUrls: { default: { http: ['https://rpc.crossmainnet.io'] } },
} as const satisfies Chain;

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

export const wagmiConfig = createConfig({
  chains: [crossMainnet],
  connectors: [
    createCROSSxConnector({
      sdk,
      defaultChainId: ChainId.CROSS_MAINNET,
    }),
  ],
  transports: {
    [crossMainnet.id]: http(),
  },
});
// main.tsx
import { WagmiProvider } from 'wagmi';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { wagmiConfig } from './wagmi-config';

const queryClient = new QueryClient();

function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <MyApp />
      </QueryClientProvider>
    </WagmiProvider>
  );
}

Direct SDK Access (Advanced)

For SDK-specific methods not available through wagmi hooks, use the SDK instance directly:

// Import the SDK instance from your config file
import { sdk } from './wagmi-config';

async function getUserInfo() {
  const userInfo = await sdk.getUserInfo();
  console.log('User:', userInfo);
}

async function rpcRead() {
  const balance = await sdk.getBalance(ChainId.CROSS_MAINNET);
  const gasPrice = await sdk.getGasPrice(ChainId.CROSS_MAINNET);
}

Simple Mode with openConnectOtherWallet

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

const config = createConfig({
  chains: [crossMainnet],
  connectors: [
    crossxConnector({
      projectId: 'YOUR_PROJECT_ID',
      appName: 'My DApp',
      openConnectOtherWallet: () => {
        // Trigger your external wallet connect modal
        openConnectModal();
      },
    }),
  ],
  transports: { [crossMainnet.id]: http() },
});

Preconditions

Confirm the required setup before implementing a feature.

  • Install: @nexus-cross/crossx-sdk-core, @nexus-cross/crossx-sdk-wagmi, wagmi, viem, @tanstack/react-query.
  • Use simple mode (crossxConnector) for most apps — it creates the SDK internally from config options.
  • Use advanced mode (createCROSSxConnector({ sdk })) when custom SDK configuration, event listeners, or direct SDK access are needed.
  • Both WagmiProvider and QueryClientProvider must wrap the component tree.
  • Chains must be defined as viem Chain objects and passed to createConfig.
  • Wallet connection requires the user to call connect({ connector }) where connector is the CROSSx connector from useConnect.
  • Standard wagmi hooks (useSendTransaction, useSignMessage, etc.) work normally with the CROSSx connector once connected.
  • For direct SDK access (e.g. getUserInfo, walletRpc), import the SDK instance from your config file.

Guardrails

  • Do not use createCROSSxConnector (advanced mode) when crossxConnector (simple mode) is sufficient.
  • Do not put CROSSx-specific logic into wagmi hooks when the same operation is already handled by the connector.
  • Do not use walletRpc (via the SDK instance) for transaction signing or sending — it is read-only.
  • Do not add new wrappers or architectural layers when the feature can fit existing wagmi hooks or connector config.
  • Do not guess unclear SDK behavior when the latest documentation or MCP resources should be checked first.
  • Do not generate fallback values for projectId or appName. Ask the user if they are missing.
  • Do not define chains with incorrect RPC URLs — use the actual CROSS Mainnet (id: 612055, https://rpc.crossmainnet.io) or Testnet (id: 612044, https://rpc.crosstestnet.io) values.

Implementation Workflow

  1. Identify the feature category and the affected files.
  2. Inspect the existing wagmi config and provider layout before making changes.
  3. Confirm the required packages, chain definitions, and connector setup are in place.
  4. Apply the smallest code change that fits the existing architecture and style.
  5. Use the correct wagmi hooks and connector APIs.
  6. Review the affected files for integration gaps before finalizing.

Validation Checklist

Before finalizing CROSSx wagmi SDK changes, verify the following:

  • The change matches the requested feature scope without unnecessary refactoring.
  • projectId and appName are present in the connector config.
  • Chains are defined as valid viem Chain objects and included in both createConfig chains and transports.
  • Both WagmiProvider and QueryClientProvider wrap the app.
  • Wallet connection flow uses the CROSSx connector from useConnect.
  • Standard wagmi hooks are used for signing/sending where possible.
  • Direct SDK calls are only used when standard wagmi hooks cannot satisfy the requirement.
  • walletRpc is only used for read-only scenarios.

Updated about 20 hours ago

© 2025 NEXUS Co., Ltd. All Rights Reserved.