Core SDK — API Reference

This page documents the public API surface of CROSSxSDK for JavaScript/TypeScript.

Factory

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

const sdk = createCROSSxSDK(config: SDKConfig): CROSSxSDK

Configuration Types

SDKConfig

interface SDKConfig {
  projectId: string
  appName: string
  useMockWallet?: boolean
  logger?: LoggerPort
  theme?: 'light' | 'dark'
  autoDetectTheme?: boolean
  themeTokens?: SDKThemeTokens
  locale?: 'ko' | 'en'   // default: 'en'
  debug?: boolean
  receiptPolling?: {
    intervalMs?: number   // default: 2000
    timeoutMs?: number    // default: 60000
  }
  migration?: {
    allowSkip?: boolean   // default: true
  }
  showConnectOtherWallets?: boolean  // default: false
}

SDKThemeTokens

interface SDKThemeTokens {
  light?: SDKColorOverrides
  dark?: SDKColorOverrides
}

SDKColorOverrides

interface SDKColorOverrides {
  primary?: string
  secondary?: string
  onPrimary?: string
  borderDefault?: string
  borderSubtle?: string
  textIconPrimary?: string
  textIconSecondary?: string
  textIconTertiary?: string
  surfaceDefault?: string
  surfaceSubtle?: string
  bg?: string
  error?: string
}

Color format: CSS color string (e.g. '#FF6B35', 'rgba(18,18,18,0.5)').

SignInOptions

interface SignInOptions {
  provider?: 'google' | 'apple'
}

SignOptions

interface SignOptions {
  index?: number
  dappName?: string
  accountName?: string
}

Core API

• async initialize(opts?): Promise<AuthResult | null>
  • opts?: { preferredWalletIndex?: number } — specify which wallet index to use on session restore
• async signIn(options?: SignInOptions): Promise<AuthResult>
• async signInWithCreate(options?: SignInOptions): Promise<SignInWithCreateResult>
• async signInWithJWT(accessToken: string, refreshToken?: string): Promise<AuthResult>
• async signOut(): Promise<void>
• isAuthenticated(): boolean
• isLoggedIn(): boolean — alias for isAuthenticated()
• async ensureLoggedIn(): Promise<boolean>
• async getUserInfo(): Promise<SDKUserInfo>
• get currentAddress: string | null — synchronous getter
• get currentUserId: string | null — synchronous getter

Return notes

• initialize() → AuthResult if restored, null if no session. Pass preferredWalletIndex to select a specific wallet on restore.
• signIn() → AuthResult
• signInWithCreate() → SignInWithCreateResult (AuthResult + addresses array). Handles wallet creation and migration automatically.
• signInWithJWT() → AuthResult. Authenticates using a pre-obtained JWT access token (e.g. from your own backend). Useful for server-side auth flows.
• ensureLoggedIn() → true if session valid, false if login needed

Address / Wallet

• async getAddress(index?: number): Promise<{ address: string; index: number } | null>
• async getAddresses(): Promise<Array<{ address: string; index: number }>>
• async createWallet(): Promise<{ address: string }>
• async selectWallet(currentAddress?: string): Promise<{ address: string; index: number } | null> — opens wallet selector modal. If currentAddress is provided, the matching wallet is highlighted with a "selected" tag.

Chain

• async getChains(): Promise<ChainInfo[]> — all supported chains (no auth required, only initialize())
• async getChain(chainId: string): Promise<ChainInfo> — specific chain info

Signing (UI confirm flow)

All methods display a user confirmation modal.

• signMessage(chainId, message, opts?)
  • chainId: string — CAIP-2 chain ID
  • message: string
  • params: SignOptions
• signTypedData(chainId, typedData, opts?)
  • typedData: unknown — EIP-712 typed data object
  • params: SignOptions
• signTypedDataOffchain(typedData, opts?)
  • typedData: unknown — EIP-712 typed data object without domain.chainId
  • params: SignOptions
• signTransaction(chainId, tx, opts?)
  • tx: EvmTransactionRequest
  • params: SignOptions

For signTypedData(...), pass chainId as CAIP-2 eip155:<number>. When typedData.domain.chainId is present, it should match the numeric part of the requested chain ID. For off-chain signatures (no domain.chainId), use signTypedDataOffchain().

Transactions

• sendTransaction(chainId, tx, opts?)
  • tx: EvmTransactionRequest
  • params: SignOptions
• sendTransactionWithWaitForReceipt(chainId, tx, opts?)
  • opts?: { intervalMs?, timeoutMs? }
• getTransactionReceipt(txHash, chainId) → TransactionReceipt | null
• waitForTxAndGetReceipt(txHash, chainId, opts?) → TransactionReceipt

For transaction sign/send flows, tx.from must be provided (non-empty).

Gas

• async getGasPrice(chainId): Promise<string> — hex gas price (Wei)
• async estimateGas(tx, chainId): Promise<string> — hex estimated gas limit
• async getBaseFeePerGas(chainId): Promise<string | null> — hex base fee, null on legacy chains
• async getMaxPriorityFeePerGas(chainId): Promise<string> — hex priority fee (tip)

Balance / Nonce / RPC

• async getBalance(chainId): Promise<{ wei: string; formatted: string; chainId: string }>
• async getNonce(chainId): Promise<number>
• async walletRpc(method, params, chainId): Promise<any>

walletRpc is for read-only calls only (eth_call, eth_getBalance, etc.).

Provider

• getProvider(chainId): CROSSxEthereumProvider

Returns an EIP-1193 compatible provider.

const provider = sdk.getProvider('eip155:612044')

// ethers.js v6
const ethersProvider = new ethers.BrowserProvider(provider)

// viem
const client = createWalletClient({ transport: custom(provider) })

Theme & Locale

• applyTheme(themeMode?, themeTokens?): void

Changes confirmation modal theme at runtime.

• applyLocale(locale?): void

Changes confirmation modal language at runtime. Takes effect on the next modal open.

sdk.applyLocale('ko')
sdk.applyLocale('en')

PIN Management

• setPin(pin: string): void — cache PIN in memory for signing flows
• clearPin(): void — clear cached PIN from memory
• hasPin(): boolean — check if a PIN is cached
• async changePin(oldPin: string, newPin: string): Promise<void> — change PIN on the server

When a PIN is required but not cached, the SDK displays a PIN input modal automatically.

Migration

• async migrateWallet(pin: string): Promise<MigrateResult>

Migrates a CROSSx wallet to Embedded Wallet using a 4-digit PIN.

Events

CROSSxSDK extends TypedEventEmitter<SDKEventMap> and supports typed event subscription:

• on(event, listener): () => void — returns unsubscribe function
• off(event, listener): void

Event Types

const unsub = sdk.on('authChanged', (event) => {
  console.log(event.isAuthenticated, event.address)
})

// Cleanup
unsub()

Lifecycle

• dispose(): void

Cleans up SDK resources. The instance cannot be used after this call.

Response Types

AuthResult

SignInWithCreateResult

Extends AuthResult with additional fields:

SDKUserInfo

ChainInfo

EvmTransactionRequest

SignMessageResp

SignTypedDataResp

SignTxResp

SendTxResp

TransactionWithReceipt

TransactionReceipt

MigrateResult

Error Handling

import { CROSSxError, ErrorCode } from '@nexus-cross/crossx-sdk-core'

try {
  await sdk.signTransaction(chainId, tx)
} catch (error) {
  if (error instanceof CROSSxError) {
    console.log(error.code)     // ErrorCode enum
    console.log(error.message)  // Human-readable message
    console.log(error.details)  // Original error
  }
}

Error Codes

Chain ID Constants

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

Public Type Exports

import type {
  SDKConfig,
  SDKThemeTokens,
  SDKColorOverrides,
  AuthResult,
  SignInWithCreateResult,
  SignInOptions,
  SignOptions,
  SDKUserInfo,
  UserInfo,
  EvmTransactionRequest,
  SignMessageResp,
  SignTypedDataResp,
  SignTxResp,
  SendTxResp,
  TransactionWithReceipt,
  MigrateResult,
  ChainInfo,
  ChainIdValue,
  AddressInfo,
  SDKEventMap,
  AuthChangedEvent,
  AddressChangedEvent,
  InitializedEvent,
  ConnectExternalWalletEvent,
  PrepareAction,
  PrepareContext,
  PrepareResult,
} from '@nexus-cross/crossx-sdk-core'

import {
  createCROSSxSDK,
  CROSSxSDK,
  CROSSxEthereumProvider,
  ChainId,
  CROSSxError,
  ErrorCode,
} from '@nexus-cross/crossx-sdk-core'