CROSSx React Skill

Documentation

Dependency

npm install @nexus-cross/crossx-sdk-core @nexus-cross/crossx-sdk-react

Instructions

Identify the request category first, then make the smallest React/TypeScript changes that fit the existing component and hook structure.

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

If the bundled React 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 provider setup, hook usage, and wallet-related actions.

Check these first when they exist:

package.json (dependency setup)
App entry point where CROSSxProvider is or should be placed (e.g. main.tsx, index.tsx, _app.tsx)
Components using useAuth, useWallet, or useCROSSx
Existing auth, wallet, settings, or blockchain-related components

Prefer extending existing integration points over introducing new components or wrappers.

Request Classification

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

SDK setup: package install, CROSSxProvider placement, SDKConfig options
Authentication: useAuth hook — signIn, signOut, signInWithCreate, isAuthenticated, isLoading
Wallet: useWallet hook — address, signMessage, sendTransaction
Direct SDK access: useCROSSx hook — sdk instance for any CROSSxSDK method
Theme and locale: SDKConfig theme options in CROSSxProvider

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

Key Types Reference

CROSSxProvider

interface CROSSxProviderProps {
  config: SDKConfig;
  children: React.ReactNode;
}

// Automatically calls sdk.initialize() on mount
// Subscribes to authChanged and addressChanged events
function CROSSxProvider({ config, children }: CROSSxProviderProps): JSX.Element;

useCROSSx Hook

interface CROSSxContextValue {
  sdk: CROSSxSDK | null;
  isInitialized: boolean;
  isAuthenticated: boolean;
  walletAddress: string | null;
}

function useCROSSx(): CROSSxContextValue;

useAuth Hook

function useAuth(): {
  isAuthenticated: boolean;
  isLoading: boolean;
  error: string | null;
  signIn: () => Promise<AuthResult>;
  signInWithCreate: () => Promise<SignInWithCreateResult>;
  signOut: () => Promise<void>;
};

useWallet Hook

function useWallet(): {
  address: string | null;
  isLoading: boolean;
  error: string | null;
  signMessage: (chainId: string, message: string) => Promise<SignMessageResp>;
  sendTransaction: (chainId: string, tx: EvmTransactionRequest) => Promise<SendTxResp>;
};

SDKConfig

See the Core SDK skill for full SDKConfig interface. Key fields:

interface SDKConfig {
  projectId: string;            // required
  appName: string;              // required
  theme?: 'light' | 'dark';
  autoDetectTheme?: boolean;
  themeTokens?: SDKThemeTokens;
  locale?: SDKLocale;
  // ... see Core SDK for complete list
}

Core API Signatures

Provider Setup

import { CROSSxProvider } from '@nexus-cross/crossx-sdk-react';
import type { SDKConfig } from '@nexus-cross/crossx-sdk-core';

const config: SDKConfig = {
  projectId: 'YOUR_PROJECT_ID',
  appName: 'My DApp',
};

function App() {
  return (
    <CROSSxProvider config={config}>
      <MyApp />
    </CROSSxProvider>
  );
}

Authentication with useAuth

import { useAuth } from '@nexus-cross/crossx-sdk-react';

function LoginButton() {
  const { isAuthenticated, isLoading, signIn, signInWithCreate, signOut } = useAuth();

  if (isLoading) return <p>Loading...</p>;

  if (isAuthenticated) {
    return <button onClick={signOut}>Sign Out</button>;
  }

  return <button onClick={signInWithCreate}>Sign In</button>;
}

Wallet Operations with useWallet

import { useWallet } from '@nexus-cross/crossx-sdk-react';
import { ChainId } from '@nexus-cross/crossx-sdk-core';

function WalletActions() {
  const { address, signMessage, sendTransaction } = useWallet();

  const handleSign = async () => {
    const result = await signMessage(ChainId.CROSS_MAINNET, 'Hello CROSSx');
    console.log('Signature:', result.signature);
  };

  const handleSend = async () => {
    const result = await sendTransaction(ChainId.CROSS_MAINNET, {
      to: '0xReceiverAddress',
      value: '0xDE0B6B3A7640000',
    });
    console.log('TX Hash:', result.txHash);
  };

  return (
    <div>
      <p>Address: {address}</p>
      <button onClick={handleSign}>Sign Message</button>
      <button onClick={handleSend}>Send Transaction</button>
    </div>
  );
}

Direct SDK Access with useCROSSx

import { useCROSSx } from '@nexus-cross/crossx-sdk-react';
import { ChainId } from '@nexus-cross/crossx-sdk-core';

function AdvancedComponent() {
  const { sdk, isInitialized, isAuthenticated, walletAddress } = useCROSSx();

  const getBalance = async () => {
    if (!sdk) return;
    const balance = await sdk.getBalance(ChainId.CROSS_MAINNET);
    console.log('Balance:', balance.formatted);
  };

  const getRpcData = async () => {
    if (!sdk) return;
    const gasPrice = await sdk.getGasPrice(ChainId.CROSS_MAINNET);
    const nonce = await sdk.getNonce(ChainId.CROSS_MAINNET);
  };

  if (!isInitialized) return <p>Initializing...</p>;
  // ...
}

Code Examples

Full App Setup

// main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { CROSSxProvider } from '@nexus-cross/crossx-sdk-react';
import type { SDKConfig } from '@nexus-cross/crossx-sdk-core';
import App from './App';

const config: SDKConfig = {
  projectId: 'YOUR_PROJECT_ID',
  appName: 'My DApp',
  theme: 'light',
  autoDetectTheme: true,
};

ReactDOM.createRoot(document.getElementById('root')!).render(
  <CROSSxProvider config={config}>
    <App />
  </CROSSxProvider>
);

Auth-Gated Component

import { useAuth, useWallet } from '@nexus-cross/crossx-sdk-react';

function Dashboard() {
  const { isAuthenticated, isLoading } = useAuth();
  const { address } = useWallet();

  if (isLoading) return <p>Loading...</p>;
  if (!isAuthenticated) return <p>Please sign in</p>;

  return <p>Connected: {address}</p>;
}

Preconditions

Confirm the required setup before implementing a feature.

Both @nexus-cross/crossx-sdk-core and @nexus-cross/crossx-sdk-react must be installed.
CROSSxProvider must wrap the component tree at the app root before any CROSSx hooks are used.
CROSSxProvider accepts a config prop with at minimum projectId and appName.
CROSSxProvider automatically calls sdk.initialize() on mount, so no manual initialization is needed.
Wallet and signing hooks require the user to be authenticated first (isAuthenticated from useAuth).
signInWithCreate() from useAuth handles sign-in and wallet setup in a single call.
walletRpc (accessible via useCROSSx) is read-only; do not use it for transaction sign/send flows.
All chain IDs must use CAIP-2 eip155:<number> format or ChainId constants.

Guardrails

Do not place CROSSxProvider inside a component that remounts frequently — it should be at the app root.
Do not call SDK methods directly on the SDK instance when a hook provides the same capability.
Do not use wallet or signing features before confirming isAuthenticated from useAuth.
Do not use walletRpc for transaction signing or sending.
Do not add new wrappers or architectural layers when the feature can fit existing hooks or components.
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.

Implementation Workflow

Identify the feature category and the affected components.
Inspect the existing project structure before making changes.
Confirm CROSSxProvider is in place and configured before adding hook usage.
Apply the smallest code change that fits the existing component architecture and style.
Use the correct hooks and SDK APIs, CAIP-2 chain IDs, and parameter requirements.
Review the affected components for integration gaps before finalizing.

Validation Checklist

Before finalizing CROSSx React SDK changes, verify the following:

The change matches the requested feature scope without unnecessary refactoring.
CROSSxProvider is present at the app root with projectId and appName in config.
Hooks are only called inside components that are children of CROSSxProvider.
Wallet and signing operations are gated behind isAuthenticated from useAuth.
After sign-in, wallet-dependent flows confirm a wallet exists; use signInWithCreate() for one-step login + wallet setup.
Chain-aware APIs use CAIP-2 eip155:<number> format or ChainId constants.
walletRpc is only used for read-only scenarios.
Loading states (isLoading / isInitialized) are handled in components to avoid rendering before session restore completes.