Core SDK — Getting Started

Skill — Download

This guide shows the minimum setup to run OAuth login and wallet actions with the CROSSx JavaScript SDK.

Requirements

Node.js 18+ or modern browser
TypeScript recommended (JavaScript also supported)
A project ID from the CROSSx management console

1) Install

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

pnpm add @nexus-cross/crossx-sdk-core

yarn add @nexus-cross/crossx-sdk-core

2) Create SDK instance

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

const sdk = createCROSSxSDK({
  projectId: 'YOUR_PROJECT_ID',
  appName: 'My DApp',
  theme: 'light',
  debug: true,
  receiptPolling: {
    intervalMs: 2000,
    timeoutMs: 60000,
  },
})

3) Initialize (restore session)

const session = await sdk.initialize()

if (session) {
  console.log('Session restored:', session.address)
} else {
  console.log('No previous session')
}

// Or specify which wallet to use on restore
const session = await sdk.initialize({ preferredWalletIndex: 1 })

initialize() attempts to restore a stored session on page load. Returns AuthResult if successful, null otherwise. You can pass preferredWalletIndex to select a specific wallet on restore.

4) Basic auth flow

// Ensure session is usable (restore/refresh if needed)
const ok = await sdk.ensureLoggedIn()

// Open OAuth (popup)
const result = await sdk.signIn()
// or with specific provider:
const result = await sdk.signIn({ provider: 'google' })

// Sign out
await sdk.signOut()

5) Basic wallet flow

const chainId = 'eip155:612044'

const address = await sdk.getAddress()
const { wei, formatted } = await sdk.getBalance(chainId)
console.log(`Balance: ${formatted}`)

Configuration options

Option	Type	Default	Description
`projectId`	`string`	—	Required. Project ID from management console
`appName`	`string`	—	Required. Application name displayed in confirmation modals
`theme`	`string?`	`'light'`	Confirmation modal theme: `'light'` \| `'dark'`
`autoDetectTheme`	`boolean?`	`false`	Auto-detect system dark mode via `prefers-color-scheme`
`themeTokens`	`SDKThemeTokens?`	—	Per-mode color overrides
`locale`	`'ko' \| 'en'?`	`'en'`	Modal UI language
`debug`	`boolean?`	`true`	Enable debug log output (only effective in dev builds)
`receiptPolling`	`object?`	—	`{ intervalMs, timeoutMs }`
`migration`	`object?`	—	`{ allowSkip?: boolean }` — set `allowSkip: false` to force migration (no skip button)
`logger`	`LoggerPort?`	—	Custom logger for routing SDK logs (always called regardless of dev/prod)
`showConnectOtherWallets`	`boolean?`	`false`	Show "Connect with Other Wallets" button in login selector modal
`useMockWallet`	`boolean?`	`false`	Enable mock wallet for testing

Localization

The SDK ships with built-in English (en) and Korean (ko) message packs for confirmation modals.

Select a built-in language

const sdk = createCROSSxSDK({
  projectId: 'YOUR_PROJECT_ID',
  appName: 'My DApp',
  locale: 'ko', // 'en' (default) | 'ko'
})

Change language at runtime

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