Guides
NEXUS
Guides
NEXUS
Start typing to search…

API Reference

Unreal SDK API Reference

Summary of the public UCROSSxSdkSubsystem API.

FCROSSxSdkConfig

USTRUCT(BlueprintType)
struct FCROSSxSdkConfig
{
    FString ProjectId = TEXT("unreal-host");
    FString AppId;                                          // required — application identifier for gateway whitelist
    FString AppName = TEXT("CROSSx Unreal");
    FString DefaultChainId = TEXT("eip155:1");
    ECROSSxSdkEnvironment Environment = Development;        // resolves URLs automatically
    ECROSSxLoginProvider LoginProvider = Google;
    ECROSSxThemeMode Theme = Dark;
    FString Locale = TEXT("en");
    bool bEnableDebugLogs = false;

    // Optional URL overrides (resolved from Environment if empty)
    FString OAuthServerUrl;
    FString AuthApiUrl;
    FString EmbeddedWalletGatewayUrl;

    FString GetCustomUriScheme() const;                     // "crossx-{ProjectId}"
};

Gateway whitelist headers are added automatically on authenticated wallet/RPC calls:

  • X-Project-Id: ProjectId
  • X-App-Id: AppId
  • X-App-Type: platform identifier
UENUM(BlueprintType)
enum class ECROSSxLoginProvider : uint8 { All, Google, Apple };

UENUM(BlueprintType)
enum class ECROSSxSdkEnvironment : uint8 { Development, Staging, Production, Custom };

Theme

UENUM(BlueprintType)
enum class ECROSSxThemeMode : uint8 { Light, Dark, System };

USTRUCT(BlueprintType)
struct FCROSSxThemeTokens
{
    FCROSSxColorOverrides Light;
    FCROSSxColorOverrides Dark;
};

FCROSSxColorOverrides

USTRUCT(BlueprintType)
struct FCROSSxColorOverrides
{
    FLinearColor Primary;
    FLinearColor Secondary;
    FLinearColor OnPrimary;
    FLinearColor BorderDefault;
    FLinearColor BorderSubtle;
    FLinearColor TextIconPrimary;
    FLinearColor TextIconSecondary;
    FLinearColor TextIconTertiary;
    FLinearColor SurfaceDefault;
    FLinearColor SurfaceSubtle;
    FLinearColor Bg;
    // Each has a corresponding bool bOverride_* flag
};

Core

  • void Configure(const FCROSSxSdkConfig& InConfig) — Set SDK configuration
  • bool IsConfigured() const
  • FCROSSxAuthResult InitializeSdk() — Restore stored session
  • bool IsInitialized() const
  • bool IsLoggedIn() const
  • bool EnsureLoggedInAndRefresh() — Ensure usable session (includes refresh)
  • void ApplyTheme(ECROSSxThemeMode NewTheme)
  • void ApplyTheme(ECROSSxThemeMode NewTheme, const FCROSSxThemeTokens& InTokens)
  • void SetLocale(const FString& NewLocale)
  • FString GetLocale() const
  • void EnableSignConfirmation(const FString& AppName, ECROSSxThemeMode ThemeOverride = Dark, bool bApplyTheme = false)
  • void DisableSignConfirmation()
  • bool IsSignConfirmationEnabled() const

Authentication (sync)

  • FCROSSxAuthResult SignIn(ECROSSxLoginProvider Provider)
  • FCROSSxAuthResult SignInWithProvider(const FString& ProviderOrUrl)
  • void SignOut()

Authentication (async)

  • void SignInAsync(ECROSSxLoginProvider Provider, const FCROSSxAuthResultDelegate& OnComplete)
  • void SignInWithProviderAsync(const FString& ProviderOrUrl, const FCROSSxAuthResultDelegate& OnComplete)
  • void SignInAgainAsync(const FCROSSxAuthResultDelegate& OnComplete) — Re-authenticate after session expiry
  • void SignOutAsync(const FCROSSxBoolDelegate& OnComplete)

UI-integrated auth

  • void SignInWithUIAsync(const FCROSSxAuthResultDelegate& OnComplete)
  • void SignInWithCreateAsync(ECROSSxLoginProvider Provider, const FCROSSxAuthResultDelegate& OnComplete) — Sign in + wallet creation

Behavior summary

  • InitializeSdk() — Tries to restore a stored session. Returns FCROSSxAuthResult with bSuccess = false if no session or validation fails.
  • SignInAgainAsync() — Re-runs sign-in for an already-authenticated user (e.g. after session expiry) without going through the full OAuth provider selection.
  • SignInWithCreateAsync() — Completes OAuth and continues with wallet creation/migration.

Wallet password and biometrics

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

  • bool CanUseBiometric() const
  • bool IsBiometricEnabled() const
  • void SetBiometricEnabled(bool bEnabled)

Addresses / wallet

Sync

  • FCROSSxGetAddressResponse GetAddress(int32 Index = 0)
  • FCROSSxGetAddressesResponse GetAddresses()

Async

  • void GetAddressAsync(int32 Index, const FCROSSxGetAddressDelegate& OnComplete)
  • void GetAddressesAsync(const FCROSSxGetAddressesDelegate& OnComplete)
  • void CheckWalletAsync(const FCROSSxCheckWalletDelegate& OnComplete)
  • void CreateWalletWithMigrateAsync(bool bMigrateAutomatically, const FCROSSxCreateWalletDelegate& OnComplete)

UI-integrated wallet

  • void SetupWalletWithUIAsync(const FString& Sub, const FCROSSxCreateWalletDelegate& OnComplete)
  • void GetAddressWithUIAsync(int32 Index, const FCROSSxGetAddressDelegate& OnComplete)
  • void SelectWalletWithUIAsync(const FString& CurrentSelectedAddress, const FCROSSxWalletSelectionDelegate& OnComplete)

CreateWalletWithMigrateAsync() branches

  • The SDK checks wallet state and handles exists / migration_required / not_found accordingly.
  • If migration_required and bMigrateAutomatically == false, returns a failure result.
  • PIN input and wallet found modals are managed internally by the SDK.

Signing / sending (confirmation UI required)

All require ChainId. Prefer CAIP-2 eip155:<number> format (e.g. eip155:1, eip155:612044).

Low-level (sync, requires manual Prepare call)

  • FCROSSxSignTxResponse SignTransaction(const FString& Uuid, const FCROSSxUnsignedTx& UnsignedTx)
  • FCROSSxSendTxResponse SendTransaction(const FString& Uuid, const FCROSSxUnsignedTx& UnsignedTx)
  • FCROSSxSignMessageResponse SignMessage(const FString& Uuid, const FString& From, const FString& Message, const FString& ChainId)
  • FCROSSxSignTypedDataResponse SignTypedData(const FString& Uuid, const FString& From, const FString& TypedDataJson, const FString& ChainId)
  • FCROSSxSignTypedDataResponse SignTypedDataOffchain(const FString& From, const FString& TypedDataJson)

UI-integrated (recommended)

  • void SignMessageWithUIAsync(Message, ChainId, From, OnComplete, DappName, AccountName)
  • void SignTypedDataWithUIAsync(From, TypedDataJson, ChainId, OnComplete, DappName, AccountName)
  • void SignTypedDataOffchainWithUIAsync(From, TypedDataJson, OnComplete, DappName, AccountName)
  • void SignTransactionWithUIAsync(UnsignedTx, ChainId, OnComplete, DappName, Amount, EstimatedFee)
  • void SendTransactionWithUIAsync(UnsignedTx, ChainId, OnComplete, DappName, Amount, EstimatedFee, ReceiptTimeoutMs, ReceiptPollIntervalMs)
  • void SendTransactionWithWaitForReceiptWithUIAsync(UnsignedTx, ChainId, OnComplete, DappName, Amount, EstimatedFee, ReceiptTimeoutMs, ReceiptPollIntervalMs)

Use UI-integrated APIs by default. Low-level APIs require manual Prepare() which is a private internal method. From must not be empty for sign/send flows.

Return types

  • SignMessage → FCROSSxSignMessageResponse (Signature)
  • SignTypedData → FCROSSxSignTypedDataResponse (Signature)
  • SignTransaction → FCROSSxSignTxResponse (SignedTx, optional TxHash)
  • SendTransaction → FCROSSxSendTxResponse (TxHash)
  • SendTransactionWithWaitForReceipt → FCROSSxTxReceiptResponse

Transaction receipt

  • FCROSSxTxReceiptResponse WaitForTxReceipt(TxHash, ChainId, TimeoutMs = 30000, PollIntervalMs = 1000)
  • void WaitForTxReceiptAsync(TxHash, ChainId, TimeoutMs, PollIntervalMs, OnComplete)
  • void SendTransactionWithReceiptAsync(UnsignedTx, ChainId, ReceiptTimeoutMs, ReceiptPollIntervalMs, OnComplete)

RPC / helpers

  • FCROSSxJsonRpcResponse WalletRpc(const FCROSSxJsonRpcRequest& Request, const FString& ChainId)
  • void WalletRpcAsync(const FCROSSxJsonRpcRequest& Request, const FString& ChainId, const FCROSSxJsonRpcDelegate& OnComplete)
  • FString GetBalance(const FString& Address, const FString& ChainId, const FString& BlockTag = "latest")
  • FString GetNonce(const FString& Address, const FString& ChainId, const FString& BlockTag = "pending")

WalletRpc is for reads and calls (e.g. eth_call). Use dedicated APIs for signing and broadcasting. FCROSSxJsonRpcRequest.Params must be a JSON array string (e.g. [], ["0xabc","latest"]).

Token

  • bool IsTokenExpired()
  • FCROSSxRefreshTokenResult RefreshToken()
  • void RefreshTokenAsync(const FCROSSxRefreshTokenDelegate& OnComplete)

Session cache

  • FCROSSxWalletInfo GetCachedWalletInfo() const
  • FCROSSxSdkUserInfo GetCachedUserInfo() const
  • void GetUserInfoAsync(const FCROSSxUserInfoDelegate& OnComplete)

Events

  • FCROSSxOnAuthComplete OnSignInComplete — Broadcast after successful sign-in
  • FCROSSxOnSignOutComplete OnSignOutComplete — Broadcast after sign-out
  • FCROSSxOnSessionExpired OnSessionExpired — Broadcast when session expires

Main types

FCROSSxUnsignedTx

  • ChainId, From, To, Value, Data, Nonce, GasLimit, GasPrice, MaxFeePerGas, MaxPriorityFeePerGas

FCROSSxWalletUnsignedTransaction

  • ChainId, From, To, Value, Data, Nonce, GasLimit, GasPrice, MaxFeePerGas, MaxPriorityFeePerGas
  • FCROSSxUnsignedTx ToUnsignedTx() const — Convert to low-level format

FCROSSxEip712TypedData / FCROSSxEip712Field

  • Typed data structure and field definitions for EIP-712.
  • FString ToJson() const — Serialize to JSON string

FCROSSxTxReceiptResponse

  • TransactionHash, BlockHash, BlockNumber, From, To, GasUsed, EffectiveGasPrice, Status, TransactionIndex, Type, ReceiptJson

FCROSSxCheckWalletResponse

  • Result: exists | migration_required | not_found
  • bExists, bMigrationRequired, bNotFound

FCROSSxAuthResult

  • bSuccess, WalletAddress, Email, LoginType, ErrorMessage, ErrorCode, bNeedsMigration

FCROSSxSdkUserInfo

  • Id, Email, LoginType, Addresses

FCROSSxWalletSelectionResult

  • Address, Index

FCROSSxJsonRpcRequest

  • Id, Jsonrpc, Method, Params (JSON array string)

Errors

ECROSSxErrorType

Common error variants (matching Android CROSSxError):

  • 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. The SDK shows a session expired modal allowing the user to sign in again or sign out.
  • InvalidPassword — wrong wallet password entered.
  • PasswordLocked — too many wrong password attempts; check FCROSSxPinLockInfo for lockout details.
  • MigrationRequired — returned when CreateWalletWithMigrateAsync(false) encounters a migration-required wallet.

Error information is communicated through result structs (bSuccess, ErrorMessage, ErrorCode) rather than exceptions, consistent with Unreal Engine patterns.

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 about 18 hours ago

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