Guides
NEXUS
Guides
NEXUS
Start typing to search…

API Reference

Android SDK API Reference

Summary of the public CROSSxSDK API.

SDKConfig

// Convenience constructor — appId is derived from context.applicationContext.packageName
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 = "...",
    callbackScheme = SDKConfig.defaultScheme(projectId)
)
enum class SDKSignInProvider {
    All,
    Google,
    Apple
}

Choose the provider UI at runtime in signIn / signInWithCreate. All shows the provider selection sheet.

Theme

enum class SDKThemeMode { Light, Dark, System }

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

SDKColorOverrides

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
)

Colors use 0xAARRGGBB.

Core

  • val config: SDKConfig — Read-only configuration from initialization

  • fun handleUrl(url: String): Boolean — Handle OAuth callback URL

  • suspend fun initialize(): AuthResult?

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

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

  • suspend fun signInAgain(): AuthResult

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

  • suspend fun signOut()

  • suspend fun refreshToken(): String

  • fun isLoggedIn(): Boolean

  • suspend fun ensureLoggedIn(): Boolean

  • suspend fun getUserInfo(): SDKUserInfo

Behavior summary

  • initialize() — Tries to restore a stored session. If backend wallet session validation fails after restore, local session may be cleared and null returned.
  • signIn() / signInWithCreate() — Return AuthResult after OAuth. signInWithCreate() continues with wallet creation or migration after auth.
  • signInAgain() — Re-runs the sign-in flow for an already-authenticated user (e.g. to re-validate the session after expiry) without going through the full OAuth provider selection.
  • getUserInfo() — Builds SDKUserInfo from JWT, storage, and wallet address list. The address list may be empty if the wallet password is not set yet and address lookup is blocked.

Wallet password and biometrics

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

  • fun canUseBiometric(): Boolean
  • fun isBiometricEnabled(): Boolean
  • suspend fun setBiometricEnabled(enabled: Boolean)

Addresses / wallet

  • suspend fun getAddress(index: Int? = null): GetAddressResp
  • suspend fun getAddresses(): GetAddressesResp
  • suspend fun selectWallet(activity: Activity, currentAddress: String? = null): SelectedWallet
  • suspend fun checkWallet(): WalletCheckResp
  • suspend fun createWallet(migrateAutomatically: Boolean = true): CreateWalletResp

createWallet() branches

  • The SDK checks wallet state and handles exists / migration_required / not_found accordingly.
  • If migration_required and migrateAutomatically == false, throws CROSSxError.MigrationRequired.
  • CreateWalletResp now contains the resolved address only.

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

Signing / sending (confirmation UI required)

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

If dappName is blank, SDKConfig.appName is used.

  • suspend fun signMessage(activity, message, chainId, from, dappName, accountName): SignMessageResp
  • suspend fun signTypedData(activity, typedDataJson, chainId, from, dappName, accountName): SignTypedDataResp
  • suspend fun signTypedData(activity, typedData: Eip712TypedData, chainId, ...): SignTypedDataResp
  • suspend fun signTypedDataOffchain(activity, typedDataJson, from, ...): SignTypedDataResp
  • suspend fun signTypedDataOffchain(activity, typedData: Eip712TypedData, from, ...): SignTypedDataResp
  • suspend fun signTransaction(activity, unsignedTx: UnsignedTx, chainId, ...): SignTxResp
  • suspend fun signTransaction(activity, unsignedTx: WalletUnsignedTransaction, chainId, ...): SignTxResp
  • suspend fun sendTransaction(activity, unsignedTx: UnsignedTx, chainId, ...): SendTxResp
  • suspend fun sendTransaction(activity, unsignedTx: WalletUnsignedTransaction, chainId, ...): SendTxResp
  • suspend fun sendTransactionWithWaitForReceipt(...): TransactionReceipt — Same overloads as above plus timeoutMs, pollIntervalMs

from must not be empty for send and sign flows.

signTypedData may perform extra RPC (e.g. eth_call) for token metadata; chainId is still required.

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

Off-chain: use signTypedDataOffchain(...). Off-chain payloads often omit domain.chainId.

Server may return -10026 (domain chainId mismatch) on domain mismatch.

RPC / helpers

  • suspend fun walletRpc(request: JsonRpcRequest, chainId: String): String
  • suspend fun getBalance(address, chainId, blockTag = "latest"): String
  • suspend fun getNonce(address, chainId, blockTag = "pending"): String
  • suspend fun waitForTxAndGetReceipt(txHash, chainId, timeoutMs = 30_000, pollIntervalMs = 1_000): TransactionReceipt

walletRpc is for reads and calls (e.g. eth_call). Use dedicated APIs for signing and broadcasting transactions.

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

Legacy / other entry points

These remain for older integrations; prefer the wallet-centric APIs above in new code.

  • suspend fun signMessage(message: String, networkId: NetworkId): SignatureResult
  • suspend fun sendTransaction(params: TransactionParams): TransactionResult

Main types

UnsignedTx

  • chainId, from, to, value, data, nonce, gasLimit, gasPrice, maxFeePerGas, maxPriorityFeePerGas

WalletUnsignedTransaction.EvmEip155

  • chainId, from, to, value, data, nonce, gasLimit, gasPrice, maxFeePerGas, maxPriorityFeePerGas

WalletUnsignedTransaction.Tron

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

Eip712TypedData / Eip712Field

  • Typed data structure and field definitions.

TransactionReceipt

  • transactionHash, blockHash, blockNumber, from, to, gasUsed, effectiveGasPrice, status, transactionIndex, type, logsJson, rawJson

SelectedWallet

  • address, index

JsonRpcRequest

  • id, jsonrpc, method, params (JSON array string)

AuthResult

  • success, walletAddress, user: UserInfo?, needsMigration: Boolean?

UserInfo

  • id, email, provider, accessToken, idToken, sub

SDKUserInfo

  • status, data: SDKUserInfoData, loginType, addresses
  • SDKUserInfoData: provider, accessToken, idToken, email, sub, providerSub
  • Convenience properties: id, email, provider, accessToken, idToken, sub, providerSub (from data)

WalletCheckResp

  • result: exists | migration_required | not_found (WalletCheckResult)

Errors

Common CROSSxError variants:

  • Auth: NotAuthenticated, AuthFailed, TokenExpired, SessionExpired, OAuthFailed, AccountMismatch
  • User cancel: UserRejected
  • Wallet: MigrationRequired, WalletPasswordRequired, WalletPasswordChanged, WalletInconsistentState, MigrationPinFailed, WalletPinFailed, InvalidPassword, PasswordLocked
  • Sign / send: SignFailed, TransactionFailed, Timeout
  • Other: NetworkError, InvalidConfig, Unknown

Notes:

  • SessionExpired — access token is unusable and refresh failed (e.g. refresh token expired). Requires sign-out.
  • AccountMismatch — user signed in with a different account than expected.
  • InvalidPassword — wrong wallet password entered.
  • PasswordLocked — too many wrong password attempts; check PasswordLocked.info for lockout details.

Message strings may vary with SDK resources and locale.

Wallet gateway integrations may also surface:

  • -10040 — HMAC validation failed (for example a missing X-HMAC-Signature)
  • -10041 — HMAC validation failed (for example an invalid X-HMAC-Signature)

Updated 1 day ago

© 2025 NEXUS Co., Ltd. All Rights Reserved.