Core SDK — API Reference

This page documents the public API surface of CROSSxSDK for JavaScript/TypeScript (current version: 2.4.0). The wallet product's display brand is ONEpocket (formerly CROSSx); the package and class names are unchanged.

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.

Rebrand alias: createONEpocketSDK is exported as an alias of createCROSSxSDK (identical behavior). See Rebrand aliases.

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
  connectOtherWallets?: ConnectOtherWalletItem[]
  persistWalletPreference?: boolean  // default: true
  enableRNBridgeAutoLogin?: boolean  // default: true
  displayDecimals?: number           // default: 6
  pinKeyboard?: 'virtual' | 'native' | (() => 'virtual' | 'native')
}

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

SignInWithCreateOptions

interface SignInWithCreateOptions extends SignInOptions {
  /** Wallet address to auto-select. If present in the wallet list, the selectWallet() modal is skipped. */
  preferredWalletAddress?: string
}

SignOptions

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

Core API

initialize(opts?)

async initialize(opts?: { preferredWalletIndex?: number; preferredWalletAddress?: string }): 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.

whenReady()

async whenReady(): Promise<boolean>

Returns: true once initialization has completed, false if initialization has not been started or failed.

Waits for SDK initialization to finish. Prevents race conditions where isAuthenticated() is checked while initialize() is still in flight (e.g. frameworks that do not await connector setup). If initialization has already completed, resolves immediately with true; if it is in progress, resolves when it finishes; if it was never started, resolves immediately with false.

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?: SignInWithCreateOptions): Promise<SignInWithCreateResult>

Returns: SignInWithCreateResult

Signs in and automatically creates an embedded wallet if the user does not already have one. Also handles legacy CROSSx wallet migration automatically. When the user has two or more wallets, the wallet selector modal is shown (unless preferredWalletAddress matches an existing wallet). Use this method for most onboarding flows.

signInWithOAuthToken(firebaseToken)

async signInWithOAuthToken(firebaseToken: string): Promise<SignInWithCreateResult>

Returns: SignInWithCreateResult

Completes sign-in with an externally obtained Firebase ID token instead of opening the OAuth popup — used when the OAuth flow is performed outside the SDK (e.g. a React Native host app passes the token via deeplink; see parseOAuthDeeplink). Behaves like signInWithCreate() afterwards: creates the wallet if needed and shows the wallet selector when the user has multiple wallets. The resulting authChanged event carries source: 'external'.

signInAgain()

async signInAgain(): Promise<AuthResult>

Returns: AuthResult on success, { success: false } on failure.

Re-authenticates the same account after session expiry (SESSION_EXPIRED). Opens OAuth again and verifies that the same account was used; if a different account signs in, the SDK signs it out and prompts the user to retry with the original account.

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; name?: string }>>

Returns: Array of all wallet addresses for the current user, each with its derivation index and optional user-defined wallet name.

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; name?: string } | null>

Returns: { address: string; index: number; name? } 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. Polling starts at the base interval (1000 ms by default) and backs off exponentially — doubling after each attempt, capped at 10000 ms. 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.

isPinRequired()

isPinRequired(): boolean

Returns: true if the next sign/send operation will require PIN entry (no PIN cached in memory), false otherwise.

Use this to decide whether to show your own PIN prompt before a signing flow:

if (sdk.isPinRequired()) {
  const pin = await showPinModal()
  sdk.setPin(pin)
}
await sdk.signMessage(chainId, message)

setPinKeyboard(mode)

setPinKeyboard(mode: 'virtual' | 'native' | (() => 'virtual' | 'native')): void

Changes the PIN input modal's keyboard mode at runtime. Takes effect on the next PIN modal open. Also configurable at creation time via SDKConfig.pinKeyboard.

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.

Token History

registerTokenHistory(chainId, txHash, clientVersion)

async registerTokenHistory(
  chainId: string,
  txHash: string,
  clientVersion: string
): Promise<void>

Registers a wallet-sent coin/ERC-20 transfer in the token history service. The transaction must already be indexed, have succeeded (status == 1), and be an ERC-20 transfer (0xa9059cbb) or coin transfer (0x00000000). Throws CROSSxError on validation or API errors.

getTokenHistory(options?)

async getTokenHistory(options?: {
  lastTimestamp?: number
  lastTxIndex?: number
}): Promise<TokenHistoryItem[]>

Returns: TokenHistoryItem[]

Fetches transactions previously registered via registerTokenHistory(). Supports cursor-based pagination:

const history = await sdk.getTokenHistory()

if (history.length > 0) {
  const last = history[history.length - 1]
  const nextPage = await sdk.getTokenHistory({
    lastTimestamp: last.timestamp,
    lastTxIndex: last.tx_index,
  })
}

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

TokenHistoryItem

GetTokenHistoryResponse

RegisterTokenHistoryRequest

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'

ChainId.CROSS_MAINNET / ChainId.CROSS_TESTNET were renamed to ChainId.ONE_MAINNET / ChainId.ONE_TESTNET. The CAIP-2 values are unchanged.

Public Type Exports

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

import {
  createCROSSxSDK,
  CROSSxSDK,
  CROSSxEthereumProvider,
  ChainId,
  CROSSxError,
  ErrorCode,
  MNEMONIC_ADDRESS_LIMIT,   // 100 — max derivable addresses (ADDRESS_LIMIT_EXCEEDED)
  WALLET_BRAND_NAME,        // 'ONEpocket' — user-facing wallet brand name
  parseOAuthDeeplink,       // parse OAuth deeplinks (RN WebView integration)
  getWalletBrowserInfo,     // detect the wallet in-app browser
  isWalletInAppBrowser,
  waitForWalletBrowser,
  ConnectOtherWalletItem,   // external wallet IDs for SDKConfig.connectOtherWallets
  CONNECT_OTHER_WALLET_DISPLAY_ORDER,
  getConnectOtherWalletLabel,
} from '@nexus-cross/crossx-sdk-core'

Rebrand aliases

The wallet's display brand is ONEpocket (formerly CROSSx). The following exports are aliases of the CROSSx names — identical values/classes, both names remain available: