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

Creates and returns a CROSSxSDK instance. This is the only way to instantiate the SDK — do not use new CROSSxSDK() directly.

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

initialize(opts?)

async initialize(opts?: { preferredWalletIndex?: number }): Promise<AuthResult | null>

Returns: AuthResult if a prior session is restored, null if no session exists.

Initializes the SDK and restores a prior session from persistent storage if available. Must be called once at startup before any other SDK method. When a session is restored, the returned AuthResult reflects the user's previous sign-in state.

signIn(options?)

async signIn(options?: SignInOptions): Promise<AuthResult>

Returns: AuthResult

Opens the OAuth sign-in flow. If options.provider is not specified, a provider selection modal is displayed. On success, creates a session and returns auth state. Throws if the user cancels.

signInWithCreate(options?)

async signInWithCreate(options?: SignInOptions): Promise<SignInWithCreateResult>

Returns: SignInWithCreateResult

Signs in and automatically creates an embedded wallet if the user does not already have one. Also handles CROSSx wallet migration automatically. Use this method for most onboarding flows.

signInWithJWT(accessToken, refreshToken?)

async signInWithJWT(accessToken: string, refreshToken?: string): Promise<AuthResult>

Returns: AuthResult

Authenticates using a pre-obtained JWT access token. Useful for React Native WebView scenarios where Firebase Auth is handled natively and the token is passed to the JS SDK. The JWT signature is verified via JWKS.

signOut()

async signOut(): Promise<void>

Signs out the current user and clears the session from persistent storage. Emits an authChanged event with isAuthenticated: false.

isAuthenticated()

isAuthenticated(): boolean

Returns: true if the user has an active authenticated session, false otherwise.

Synchronous check of the current auth state. Does not trigger a network request.

isLoggedIn()

isLoggedIn(): boolean

Alias for isAuthenticated(). Returns the same value.

ensureLoggedIn()

async ensureLoggedIn(): Promise<boolean>

Returns: true if the session is valid, false if a sign-in is needed.

Verifies that the current session is still valid (e.g. token not expired). Use before operations that require authentication.

getUserInfo()

async getUserInfo(): Promise<SDKUserInfo>

Returns: SDKUserInfo

Retrieves the authenticated user's profile including ID, email, login type, and wallet addresses. Throws AUTH_NOT_AUTHENTICATED if not signed in.

currentAddress

get currentAddress: string | null

Synchronous getter returning the currently active wallet address, or null if not authenticated or no wallet is selected.

currentUserId

get currentUserId: string | null

Synchronous getter returning the authenticated user's ID (JWT sub claim), or null if not authenticated.

Address / Wallet

getAddress(index?)

async getAddress(index?: number): Promise<{ address: string; index: number } | null>

Returns: { address: string; index: number } or null if no wallet exists at that index.

Returns the address for a specific HD wallet derivation index. If no index is specified, returns the active wallet's address.

getAddresses()

async getAddresses(): Promise<Array<{ address: string; index: number }>>

Returns: Array of all wallet addresses for the current user, each with its derivation index.

Retrieves all HD wallet addresses derived for this user's account.

createWallet()

async createWallet(): Promise<{ address: string }>

Returns: { address: string } — the newly created wallet address.

Derives a new HD wallet address for the current user. Requires the user to be authenticated.

selectWallet(currentAddress?)

async selectWallet(currentAddress?: string): Promise<{ address: string; index: number } | null>

Returns: { address: string; index: number } for the wallet the user selected, or null if the user dismisses the modal.

Opens the wallet selector modal, allowing the user to switch between multiple HD wallets. If currentAddress is provided, the matching wallet entry is highlighted with a "selected" tag.

Chain

getChains()

async getChains(): Promise<ChainInfo[]>

Returns: Array of ChainInfo for all supported chains.

Returns all chains configured for the current project. Does not require authentication — only initialize() must have been called.

getChain(chainId)

async getChain(chainId: string): Promise<ChainInfo>

Returns: ChainInfo for the specified chain.

Returns configuration for a specific chain. Throws INVALID_CHAIN if chainId is not in CAIP-2 format, or CHAIN_NOT_SUPPORTED if the chain is not registered.

Signing

All signing methods display a user confirmation modal before executing.

signMessage(chainId, message, opts?)

async signMessage(
  chainId: string,
  message: string,
  opts?: SignOptions
): Promise<SignMessageResp>

Returns: SignMessageResp

Signs a UTF-8 message using EIP-191 personal sign. Displays a confirmation modal showing the message content and signer address before proceeding.

signTypedData(chainId, typedData, opts?)

async signTypedData(
  chainId: string,
  typedData: unknown,
  opts?: SignOptions
): Promise<SignTypedDataResp>

Returns: SignTypedDataResp

Signs EIP-712 typed structured data for on-chain use. Requires typedData.domain.chainId to match the numeric part of chainId. Throws TYPED_DATA_CHAIN_ID_MISMATCH on mismatch. For typed data without a chain ID, use signTypedDataOffchain().

signTypedDataOffchain(typedData, opts?)

async signTypedDataOffchain(
  typedData: unknown,
  opts?: SignOptions
): Promise<SignTypedDataResp>

Returns: SignTypedDataResp with chainId: '0'

Signs EIP-712 typed data for off-chain use cases (e.g. permit signatures, order books). Use when typedData.domain.chainId is absent or zero.

signTransaction(chainId, tx, opts?)

async signTransaction(
  chainId: string,
  tx: EvmTransactionRequest,
  opts?: SignOptions
): Promise<SignTxResp>

Returns: SignTxResp

Signs a transaction without broadcasting it. Gas fields (gasLimit, gasPrice / maxFeePerGas) are resolved automatically if not provided. Returns the RLP-encoded signed transaction and its hash.

Transactions

sendTransaction(chainId, tx, opts?)

async sendTransaction(
  chainId: string,
  tx: EvmTransactionRequest,
  opts?: SignOptions
): Promise<SendTxResp>

Returns: SendTxResp

Signs and broadcasts a transaction. Displays a confirmation modal before signing. Gas fields are auto-resolved if not provided. Returns immediately after broadcast with status: 'pending'.

sendTransactionWithWaitForReceipt(chainId, tx, opts?)

async sendTransactionWithWaitForReceipt(
  chainId: string,
  tx: EvmTransactionRequest,
  opts?: SignOptions & { intervalMs?: number; timeoutMs?: number }
): Promise<TransactionWithReceipt>

Returns: TransactionWithReceipt

Signs, broadcasts, and waits for the transaction receipt. Displays a transaction progress modal showing pending and mined states. Polling interval and timeout default to the values set in SDKConfig.receiptPolling.

getTransactionReceipt(txHash, chainId)

async getTransactionReceipt(txHash: string, chainId: string): Promise<TransactionReceipt | null>

Returns: TransactionReceipt if mined, null if still pending.

Fetches the receipt for a specific transaction hash. Returns null if the transaction has not been mined yet.

waitForTxAndGetReceipt(txHash, chainId, opts?)

async waitForTxAndGetReceipt(
  txHash: string,
  chainId: string,
  opts?: { intervalMs?: number; timeoutMs?: number }
): Promise<TransactionReceipt>

Returns: TransactionReceipt

Polls for a transaction receipt until it is mined or the timeout is reached. Throws if the timeout expires before the receipt is available.

Gas

getGasPrice(chainId)

async getGasPrice(chainId: string): Promise<string>

Returns: Hex-encoded gas price in Wei (e.g. '0x3b9aca00').

Fetches the current gas price via eth_gasPrice. Use for legacy (pre-EIP-1559) transactions. For EIP-1559 chains, prefer getMaxPriorityFeePerGas() and getBaseFeePerGas().

estimateGas(tx, chainId)

async estimateGas(tx: EvmTransactionRequest, chainId: string): Promise<string>

Returns: Hex-encoded estimated gas limit (e.g. '0x5208').

Calls eth_estimateGas on the specified chain. The estimate reflects gas required at the current block state. Throws GAS_ESTIMATION_FAILED if the call reverts.

getBaseFeePerGas(chainId)

async getBaseFeePerGas(chainId: string): Promise<string | null>

Returns: Hex-encoded base fee in Wei, or null on chains that do not support EIP-1559.

Fetches the base fee per gas from the latest block header. Returns null on legacy chains.

getMaxPriorityFeePerGas(chainId)

async getMaxPriorityFeePerGas(chainId: string): Promise<string>

Returns: Hex-encoded EIP-1559 priority fee (tip) in Wei.

Fetches the suggested miner priority fee via eth_maxPriorityFeePerGas. Use with getBaseFeePerGas() to construct EIP-1559 transaction fee fields.

Balance / Nonce / RPC

getBalance(chainId)

async getBalance(chainId: string): Promise<{ wei: string; formatted: string; chainId: string }>

Returns:

Fetches the native token balance for the current wallet on the specified chain.

getNonce(chainId)

async getNonce(chainId: string): Promise<number>

Returns: Current transaction count (nonce) as a number.

Returns the number of transactions sent from the current wallet address via eth_getTransactionCount. Unlike the mobile SDKs, this returns a number rather than a hex string.

walletRpc(method, params, chainId)

async walletRpc(method: string, params: any[], chainId: string): Promise<any>

Returns: JSON-RPC result.

Sends a raw JSON-RPC read-only request to the specified chain's RPC endpoint. Intended for read operations (eth_call, eth_getBalance, eth_getCode, etc.). Do not use for signing or sending transactions.

Provider

getProvider(chainId)

getProvider(chainId: string): CROSSxEthereumProvider

Returns: CROSSxEthereumProvider — an EIP-1193 compatible provider.

Returns an EIP-1193 provider bound to the specified chain. Compatible with ethers.js v6, viem, and other libraries that accept an EIP-1193 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?)

applyTheme(themeMode?: 'light' | 'dark', themeTokens?: SDKThemeTokens): void

Changes the confirmation modal theme at runtime. Takes effect on the next modal open. Useful for responding to system dark mode changes dynamically.

applyLocale(locale?)

applyLocale(locale?: 'ko' | 'en'): void

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

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

PIN Management

setPin(pin)

setPin(pin: string): void

Caches the user's PIN in memory so that signing flows can proceed without displaying a PIN input modal. The PIN is kept only in memory and cleared on clearPin() or signOut().

clearPin()

clearPin(): void

Clears the cached PIN from memory. Subsequent signing flows that require a PIN will prompt the user via the SDK modal.

hasPin()

hasPin(): boolean

Returns: true if a PIN is currently cached in memory, false otherwise.

Checks whether a PIN is cached without exposing the PIN value.

changePin(oldPin, newPin)

async changePin(oldPin: string, newPin: string): Promise<void>

Changes the user's PIN on the server. The new PIN must satisfy format requirements (no sequential or repeated digit patterns). Throws PIN_WRONG if oldPin is incorrect, or PIN_INVALID / PIN_REPEATED_PATTERN if the new PIN is rejected.

Migration

migrateWallet(pin)

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

Returns: MigrateResult

Migrates a legacy CROSSx wallet to an Embedded Wallet using the original 4-digit PIN. After migration, the wallet is accessible via the standard wallet API. Throws MIGRATION_FAILED on failure or MIGRATION_PIN_LOCKED after too many incorrect PIN attempts.

Events

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

on(event, listener)

on(event: string, listener: Function): () => void

Subscribes to an SDK event. Returns an unsubscribe function.

off(event, listener)

off(event: string, listener: Function): void

Removes an event listener.

Event Types

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

// Cleanup
unsub()

Lifecycle

dispose()

dispose(): void

Cleans up SDK resources including event listeners and internal state. The instance cannot be used after this call. Call this when unmounting an SDK host component or tearing down the application.

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'