Android SDK API Reference

Public CROSSxSDK API reference.

Configuration

SDKConfig

SDK initialization configuration object.

// Convenience constructor — appId and appVersion are derived from context
SDKConfig(
    context = application,
    projectId = "...",
    appName = "...",
    callbackScheme = SDKConfig.defaultScheme(projectId),
    theme = SDKThemeMode.Light,
    themeTokens = SDKThemeTokens(),
    logger = null
)

// Primary constructor — provide appId explicitly
SDKConfig(
    projectId = "...",
    appId = "com.example.myapp",   // Gradle applicationId (including flavor suffix)
    appName = "...",
    appVersion = "1.0.0",          // sent as X-App-Version header
    callbackScheme = SDKConfig.defaultScheme(projectId)
)

SDKSignInProvider

Selects the OAuth provider shown during signIn() / signInWithCreate().

enum class SDKSignInProvider {
    All,
    Google,
    Apple
}

All shows the provider selection sheet; Google / Apple skip directly to that provider.

Theme

SDKThemeMode / SDKThemeTokens

enum class SDKThemeMode { Light, Dark, System }

data class SDKThemeTokens(
    val light: SDKColorOverrides = SDKColorOverrides(),
    val dark: SDKColorOverrides = SDKColorOverrides()
)

Pass to SDKConfig or applyTheme() to control the visual appearance of SDK modals.

SDKColorOverrides

Per-mode color overrides. All fields are optional; unset fields fall back to SDK defaults. Colors use 0xAARRGGBB.

data class SDKColorOverrides(
    val primary: Long? = null,
    val secondary: Long? = null,
    val onPrimary: Long? = null,
    val borderDefault: Long? = null,
    val borderSubtle: Long? = null,
    val textIconPrimary: Long? = null,
    val textIconSecondary: Long? = null,
    val textIconTertiary: Long? = null,
    val surfaceDefault: Long? = null,
    val surfaceSubtle: Long? = null,
    val bg: Long? = null
)

Core

config

val config: SDKConfig

Read-only configuration provided at construction.

handleUrl()

fun handleUrl(url: String): Boolean

Routes an incoming deep-link URL to the SDK's OAuth callback handler. Call this from your Activity.onNewIntent() or Activity.onCreate() when the URL matches your callbackScheme.

Returns true if the URL was handled by the SDK, false otherwise.

initialize()

suspend fun initialize(): AuthResult?

Attempts to restore a previously stored session. Also calls applyTheme() with the current config values.

• If a valid session is found and backend wallet validation succeeds, returns an AuthResult.
• If backend validation fails, the local session may be cleared and null is returned.
• Call this on app start before checking isLoggedIn().

Returns AuthResult? — restored session info, or null if no session could be restored.

applyTheme()

fun applyTheme(
    themeMode: SDKThemeMode = config.theme,
    themeTokens: SDKThemeTokens = config.themeTokens
)

Applies theme configuration to SDK modals. If not called, SDK UI uses its built-in default palette. initialize() calls this automatically with the config values; call manually only when changing the theme at runtime.

signIn()

suspend fun signIn(provider: SDKSignInProvider = SDKSignInProvider.All): AuthResult

Launches the OAuth sign-in flow. Shows the provider selection sheet (or skips directly to the given provider) and suspends until the user completes or cancels. Does not create or migrate a wallet.

Returns AuthResult — auth state and user info.

signInAgain()

suspend fun signInAgain(): AuthResult

Re-runs the sign-in flow for an already-authenticated user without showing the full OAuth provider selection. Use this to re-validate an expired session without forcing the user to choose a provider again.

Returns AuthResult after re-authentication.

signInWithJWT()

suspend fun signInWithJWT(
    idToken: String,
    providerSub: String? = null,
    provider: String? = null
): AuthResult

Signs in using a Firebase ID Token obtained externally (e.g. from React Native or a custom auth flow). The SDK exchanges the token with the backend /cross-auth/social/login and creates a session identical to a standard signIn(). All getUserInfo() fields are populated normally after this call.

Returns AuthResult.

Throws CROSSxError.AuthFailed if the backend token exchange or validation fails.

signInWithCreate()

suspend fun signInWithCreate(provider: SDKSignInProvider = SDKSignInProvider.All): AuthResult

Same OAuth flow as signIn(), then automatically continues with wallet creation or migration after authentication completes. If wallet creation fails, the session is signed out and the error is thrown.

Returns AuthResult with the resolved wallet address.

signOut()

suspend fun signOut()

Clears the local session, access/refresh tokens, and OAuth state. Subsequent calls to isLoggedIn() will return false.

refreshToken()

suspend fun refreshToken(): String

Forces a token refresh using the stored refresh token.

Returns the new access token as a String.

Throws CROSSxError.NotAuthenticated if no refresh token is stored.

isLoggedIn()

fun isLoggedIn(): Boolean

Returns true if a stored access token exists and has not expired. This is a local check — no network call is made. For a full session restore with server validation, call initialize().

ensureLoggedIn()

suspend fun ensureLoggedIn(): Boolean

Ensures the current session is usable:

• If the local access token is still valid, returns true immediately.
• Otherwise attempts session restore and refresh via initialize().
• Returns false when no restorable session exists.

Returns Boolean — true if a valid session is available, false if the user must sign in.

getUserInfo()

suspend fun getUserInfo(): SDKUserInfo

Builds SDKUserInfo from the JWT payload, persisted OAuth tokens, and the user's wallet address list. The addresses list may be empty if the wallet password is not set yet and address lookup is blocked by CROSSxError.WalletPasswordRequired.

Returns SDKUserInfo with provider info, tokens, email, sub, and wallet addresses.

Wallet Password and Biometrics

Wallet passwords are stored securely after confirmation UI and reused for later signing and sending operations.

canUseBiometric()

fun canUseBiometric(): Boolean

Returns true if biometric hardware (fingerprint, face) is available and enrolled on the device.

isBiometricEnabled()

fun isBiometricEnabled(): Boolean

Returns true if biometric unlock is currently enabled for the current user's wallet.

setBiometricEnabled()

suspend fun setBiometricEnabled(enabled: Boolean)

Enables or disables biometric unlock for wallet operations. When enabling, the user is prompted for their existing wallet password to register the biometric credential.

Addresses / Wallet

getAddress()

suspend fun getAddress(index: Int? = null): GetAddressResp

Returns the wallet address at the given index. Pass null (default) to get the first/default address.

getAddresses()

suspend fun getAddresses(): GetAddressesResp

Returns all wallet addresses associated with the current user.

setAddressNames()

suspend fun setAddressNames(names: List<AddressNameEntry>): Unit

Bulk sets or deletes address labels.

• names must contain at most 10 entries.
• Each non-empty name must be 4–24 characters and must not contain: `< > " ' ; \ $ & | ``
• An empty string for AddressNameEntry.name deletes the label for that address.
• Addresses not found in the server's DB are silently ignored.

Throws CROSSxError.InvalidAddressName if any name fails validation.

selectWallet()

suspend fun selectWallet(activity: Activity, currentAddress: String? = null): SelectedWallet

Presents a wallet selection UI to the user.

Returns SelectedWallet with the chosen address and index.

checkWallet()

suspend fun checkWallet(): WalletCheckResp

Queries the server for the current wallet state without creating or modifying any wallet. Useful to branch logic before calling createWallet().

Returns WalletCheckResp — result is one of exists | migration_required | not_found.

createWallet()

suspend fun createWallet(migrateAutomatically: Boolean = true): CreateWalletResp

Creates a new wallet or migrates an existing one, with UI for password/PIN entry.

Branches:

• exists — returns the existing wallet address.
• migration_required + migrateAutomatically = true — migrates and returns the new address.
• migration_required + migrateAutomatically = false — throws CROSSxError.MigrationRequired.
• not_found — creates a new wallet and returns the address.

Returns CreateWalletResp with the resolved address.

The public crossx-sdk-core artifact does not expose mnemonic export, private key export, password change, or account deletion APIs.

Signing / Sending

All signing and sending methods require activity and chainId. Prefer CAIP-2 format eip155:<number> for chainId (e.g. eip155:1, eip155:612044).

If dappName is blank, SDKConfig.appName is used. from must not be empty for sign and send flows.

signMessage()

suspend fun signMessage(
    activity: Activity,
    message: String,
    chainId: String,
    from: String? = null,
    dappName: String = "",
    accountName: String = "Account"
): SignMessageResp

Shows a confirmation dialog and signs a plain-text message with the user's wallet.

signTypedData() — JSON string

suspend fun signTypedData(
    activity: Activity,
    typedDataJson: String,
    chainId: String,
    from: String? = null,
    dappName: String = "",
    accountName: String = "Account"
): SignTypedDataResp

Shows a confirmation dialog and signs EIP-712 typed data supplied as a JSON string. May perform extra RPC calls (e.g. eth_call) for token metadata.

For on-chain typed data, align chainId to eip155:<n> and match domain.chainId in the payload to the same numeric chain ID.

signTypedData() — Eip712TypedData object

suspend fun signTypedData(
    activity: Activity,
    typedData: Eip712TypedData,
    chainId: String,
    from: String? = null,
    dappName: String = "",
    accountName: String = "Account"
): SignTypedDataResp

Same as above, but accepts a pre-parsed Eip712TypedData object instead of a JSON string.

signTypedDataOffchain()

// JSON string overload
suspend fun signTypedDataOffchain(
    activity: Activity,
    typedDataJson: String,
    from: String? = null,
    dappName: String = "",
    accountName: String = "Account"
): SignTypedDataResp

// Eip712TypedData object overload
suspend fun signTypedDataOffchain(
    activity: Activity,
    typedData: Eip712TypedData,
    from: String? = null,
    dappName: String = "",
    accountName: String = "Account"
): SignTypedDataResp

Signs EIP-712 typed data for off-chain use cases where domain.chainId is absent. Internally uses chainId = "0".

Use this instead of signTypedData() when the payload omits domain.chainId. Sending an on-chain payload here will cause the server to return -10026 (domain chainId mismatch).

signTransaction()

// UnsignedTx overload
suspend fun signTransaction(
    activity: Activity,
    unsignedTx: UnsignedTx,
    chainId: String,
    dappName: String = "",
    networkName: String? = null,
    estimatedFee: String? = null,
    amount: String? = null
): SignTxResp

// WalletUnsignedTransaction overload
suspend fun signTransaction(
    activity: Activity,
    unsignedTx: WalletUnsignedTransaction,
    chainId: String,
    dappName: String = "",
    networkName: String? = null,
    estimatedFee: String? = null,
    amount: String? = null
): SignTxResp

Shows a confirmation dialog and signs a transaction. The signed transaction is not broadcast to the network — use sendTransaction() to sign and broadcast in one step.

sendTransaction()

// UnsignedTx overload
suspend fun sendTransaction(
    activity: Activity,
    unsignedTx: UnsignedTx,
    chainId: String,
    dappName: String = "",
    networkName: String? = null,
    estimatedFee: String? = null,
    amount: String? = null
): SendTxResp

// WalletUnsignedTransaction overload
suspend fun sendTransaction(
    activity: Activity,
    unsignedTx: WalletUnsignedTransaction,
    chainId: String,
    dappName: String = "",
    networkName: String? = null,
    estimatedFee: String? = null,
    amount: String? = null
): SendTxResp

Shows a confirmation dialog, signs, and broadcasts the transaction to the network.

sendTransactionWithWaitForReceipt()

suspend fun sendTransactionWithWaitForReceipt(
    activity: Activity,
    unsignedTx: UnsignedTx,           // or WalletUnsignedTransaction
    chainId: String,
    dappName: String = "",
    networkName: String? = null,
    estimatedFee: String? = null,
    amount: String? = null,
    timeoutMs: Long = 30_000,
    pollIntervalMs: Long = 1_000
): TransactionReceipt

Same as sendTransaction() but also polls for the on-chain transaction receipt before returning. Available for both UnsignedTx and WalletUnsignedTransaction.

Throws CROSSxError.Timeout if the receipt is not confirmed within timeoutMs.

RPC / Helpers

walletRpc()

suspend fun walletRpc(request: JsonRpcRequest, chainId: String): String

Generic JSON-RPC request routed through the gateway chain resolver. Resolves the chain RPC URL via the gateway, caches it in memory, and sends the request directly to the node.

Use this for reads and calls (e.g. eth_call). For signing and broadcasting, use the dedicated APIs.

JsonRpcRequest.params must be a JSON array string (e.g. [], ["0xabc","latest"]).

Returns the raw JSON-RPC response as a String.

getBalance()

suspend fun getBalance(
    address: String,
    chainId: String,
    blockTag: String = "latest"
): String

Calls eth_getBalance(address, blockTag) against the resolved chain RPC URL.

Returns hex string balance in wei, e.g. "0x0".

getNonce()

suspend fun getNonce(
    address: String,
    chainId: String,
    blockTag: String = "pending"
): String

Calls eth_getTransactionCount(address, blockTag) against the resolved chain RPC URL. Use "pending" (default) to include pending transactions — recommended before signing or sending.

Returns hex string nonce, e.g. "0x0".

waitForTxAndGetReceipt()

suspend fun waitForTxAndGetReceipt(
    txHash: String,
    chainId: String,
    timeoutMs: Long = 30_000,
    pollIntervalMs: Long = 1_000
): TransactionReceipt

Polls the chain for a transaction receipt until the transaction is confirmed or the timeout is reached. Use this when you already have a txHash from a prior sendTransaction() call and want to wait for confirmation separately.

Throws CROSSxError.Timeout if not confirmed within timeoutMs.

Legacy Entry Points

These remain for backward compatibility with older integrations. Prefer the wallet-centric APIs above in new code.

signMessage() (legacy)

suspend fun signMessage(message: String, networkId: NetworkId): SignatureResult

sendTransaction() (legacy)

suspend fun sendTransaction(params: TransactionParams): TransactionResult

Types

UnsignedTx

WalletUnsignedTransaction.EvmEip155

WalletUnsignedTransaction.Tron

Reserved for future use. Not currently supported by the backend.

Eip712TypedData / Eip712Field

Typed data structure and field definitions for EIP-712 signing.

TransactionReceipt

AddressNameEntry

SelectedWallet

JsonRpcRequest

AuthResult

UserInfo

SDKUserInfo

SDKUserInfoData fields: provider, accessToken, idToken, email, sub, providerSub

Convenience properties on SDKUserInfo: id, email, provider, accessToken, idToken, sub, providerSub (delegated from data).

WalletCheckResp

Errors

All SDK errors are variants of CROSSxError.

Auth errors

User action

Wallet errors

Sign / send errors

Other errors

Message strings may vary with SDK resources and locale.

Wallet gateway error codes