Unity SDK API Reference

This page documents the public API surface of CROSSxSDK for Unity.

Configuration Types

SDKConfig

class SDKConfig
{
    string ProjectId { get; set; }                       // default: "unity-sample"
    string AppId { get; set; }                           // default: Application.identifier
    string AppName { get; set; }                         // default: "App"
    SDKLoginProvider LoginProvider { get; set; }         // default: All
    string DefaultChainId { get; set; }                  // default: "eip155:612055"
    string Locale { get; set; }                          // default: "en"

    ThemeMode Theme { get; set; }                        // default: Dark
    ThemeTokens ThemeTokens { get; set; }

    string OAuthServerUrl { get; set; }
    string AuthApiUrl { get; set; }
    string EmbeddedWalletGatewayUrl { get; set; }

    bool Debug { get; set; }                             // default: false

    string CustomUriScheme => $"crossx-{ProjectId}"      // read-only
    string WebkitCustomUriScheme => $"webkit-{ProjectId}" // read-only
}

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

• X-Project-Id: ProjectId
• X-App-Id: AppId (defaults to Application.identifier)
• X-App-Type: android / ios / windows (per build target)

enum SDKLoginProvider { All, Google, Apple }

All shows the login provider selector modal. Google and Apple go directly to that provider. Default is All.

Theme

enum ThemeMode { Light, Dark, System }

class ThemeTokens
{
    ThemeColorOverrides Light { get; set; }
    ThemeColorOverrides Dark { get; set; }
}

ThemeColorOverrides

class ThemeColorOverrides
{
    Color? Primary
    Color? Secondary
    Color? OnPrimary
    Color? BorderDefault
    Color? BorderSubtle
    Color? TextIconPrimary
    Color? TextIconSecondary
    Color? TextIconTertiary
    Color? SurfaceDefault
    Color? SurfaceSubtle
    Color? Bg
}

Color format: Unity Color struct.

Factory

static class CROSSxSDKFactory
{
    static CROSSxSDK Create(SDKConfig config)
}

Creates and returns a CROSSxSDK instance. This is the only way to instantiate the SDK — do not call new CROSSxSDK() directly.

Core API

IsInitialized

bool IsInitialized { get; }

true after InitializeAsync() has completed successfully. Methods that require initialization will throw InvalidOperationException if called before this.

InitializeAsync()

Task<AuthResult> InitializeAsync()

Returns: AuthResult if a prior session is restored, null if no session exists.

Restores an existing session at app startup. Must be called once before any other SDK method. If a stored session is found, refreshes the token if expired and returns the auth state. Sets IsInitialized to true.

EnableSignConfirmation(uiRoot, theme?, appName?)

void EnableSignConfirmation(
    VisualElement uiRoot,
    ThemeMode? theme = null,
    string appName = null)

Enables the sign confirmation modal system. Must be called before any signing or sending methods. Attaches all modal UI to the provided VisualElement and applies the CJK font fallback for Korean/Chinese/Japanese text rendering on Unity 2022.3 and earlier.

ApplyTheme(themeMode?, themeTokens?)

void ApplyTheme(ThemeMode? themeMode = null, ThemeTokens themeTokens = null)

Changes the confirmation modal theme at runtime. Takes effect on the next modal open.

SetLocale(locale)

void SetLocale(string locale)

Changes the modal UI language at runtime. Takes effect on the next modal open.

GetLocale()

string GetLocale()

Returns: Current locale string (e.g. "en" or "ko").

Returns the currently active locale used for modal UI text.

SignInAsync(provider?)

Task<AuthResult> SignInAsync(SDKLoginProvider? provider = null)

Returns: AuthResult

Opens the OAuth sign-in flow. If provider is null or All and EnableSignConfirmation() has been called, the login provider selector modal is shown. Otherwise falls back to SDKConfig.LoginProvider. Throws OperationCanceledException if the user cancels.

SignInAsync(providerOrUrl)

Task<AuthResult> SignInAsync(string providerOrUrl)

Returns: AuthResult

Signs in using a provider path string or a full OAuth URL. Useful for bypassing the modal and passing a provider programmatically.

SignInAgainAsync()

Task<AuthResult> SignInAgainAsync()

Returns: AuthResult

Re-authenticates with the existing account after a session expiry. Uses the stored login provider from the previous session without prompting for provider selection. Equivalent to the Android SDK's signInAgain(). Falls back to SignInAsync() if no stored provider is found.

SignInWithCreateAsync(provider?)

Task<AuthResult> SignInWithCreateAsync(SDKLoginProvider? provider = null)

Returns: AuthResult (includes wallet address after wallet setup)

Convenience method that calls SignInAsync() and then SetupWalletAsync() sequentially. Handles wallet creation or migration automatically after sign-in. Equivalent to the Android SDK's signInWithCreate().

SignOutAsync()

Task SignOutAsync()

Signs out the current user. Clears the session from persistent storage and clears any cached PIN from memory. Token revocation is not performed server-side; the local token is discarded.

IsLoggedIn()

bool IsLoggedIn()

Returns: true if a session exists in storage, false otherwise.

Synchronous check based on stored session data. Does not verify token validity — use EnsureLoggedInAsync() to also validate and refresh the token.

EnsureLoggedInAsync()

Task<bool> EnsureLoggedInAsync()

Returns: true if the session is valid (refreshing the token if expired), false if no session exists or the refresh failed.

Checks whether the login session is valid and automatically refreshes the access token if it has expired. Use before performing operations that require authentication.

RefreshTokenAsync()

Task<string> RefreshTokenAsync()

Returns: The refreshed access token string.

Manually refreshes the access token. In most cases the SDK refreshes tokens automatically — this method is only needed for explicit token management. Only available in FirebaseBackend auth mode.

GetUserInfoAsync()

Task<SDKUserInfo> GetUserInfoAsync()

Returns: SDKUserInfo, or null if not logged in.

Retrieves the authenticated user's profile including ID, email, login type, and wallet addresses. Reads the session from storage and fetches the current address list from the server.

Wallet Password and Biometrics

Wallet passwords (PINs) are stored securely in memory after confirmation UI and reused for subsequent signing and sending operations within the session.

CanUseBiometric()

bool CanUseBiometric()

Returns: true if biometric authentication is hardware-available on the device.

Checks whether the device has biometric authentication capability. Currently returns false on all Unity platforms (stub for future support).

IsBiometricEnabled()

bool IsBiometricEnabled()

Returns: true if biometric authentication is enabled for this user.

Checks whether biometric authentication is enabled. Currently returns false on all Unity platforms (stub for future support).

SetBiometricEnabledAsync(enabled)

Task SetBiometricEnabledAsync(bool enabled)

Enables or disables biometric authentication. Currently a no-op on all Unity platforms (stub for future support).

Address / Wallet

CheckWalletAsync()

Task<CheckWalletResponse> CheckWalletAsync()

Returns: CheckWalletResponse with one of Exists, MigrationRequired, or NotFound set to true.

Checks the wallet status for the currently logged-in user. Equivalent to the Android SDK's checkWallet(). Use before deciding whether to call SetupWalletAsync() or CreateWalletAsync().

SetupWalletAsync(sub?)

Task<SetupWalletResult> SetupWalletAsync(string sub = null)

Returns: SetupWalletResult

Checks the wallet status and automatically enters the appropriate flow: verify an existing wallet (PIN prompt), migrate a legacy CROSSx wallet, or create a new wallet (PIN creation). All PIN/password UI is managed internally by the SDK. Equivalent to calling CreateWalletAsync(migrateAutomatically: true).

CreateWalletAsync(migrateAutomatically?)

Task<SetupWalletResult> CreateWalletAsync(bool migrateAutomatically = true)

Returns: SetupWalletResult

Equivalent to the Android SDK's createWallet(migrateAutomatically). Checks wallet state and handles exists / migration_required / not_found accordingly. When migrateAutomatically is false and migration is required, throws CROSSxException with CROSSxErrorType.MigrationRequired.

GetAddressAsync(index?)

Task<GetAddressResponse> GetAddressAsync(int index = 0)

Returns: GetAddressResponse containing address and index.

Retrieves the wallet address for a specific derivation index. Prompts the user for PIN if not already cached in memory. Throws OperationCanceledException if the user cancels PIN input.

GetAddressesAsync()

Task<GetAddressesResponse> GetAddressesAsync()

Returns: GetAddressesResponse containing addresses[] — all cached wallet addresses.

Retrieves the list of all cached wallet addresses for the current user without requiring PIN input.

SelectWalletAsync(selectedAddress?)

Task<WalletSelectionResult> SelectWalletAsync(string selectedAddress = null)

Returns: WalletSelectionResult with Address and Index, or null if the user cancels.

Opens the wallet selection modal, allowing the user to switch between multiple HD wallets or add a new one. If selectedAddress is provided, the matching wallet entry is highlighted. Requires EnableSignConfirmation() to have been called.

Signing / Sending

All sign/send methods display the SDK confirmation modal before executing. chainId must be in CAIP-2 eip155:<number> format (e.g. eip155:612044). From must be non-empty for transaction sign/send flows.

SignMessageAsync(...)

Task<SignMessageResponse> SignMessageAsync(
    string message,
    string chainId = null,
    string from = null,
    string dappName = null,
    string accountName = "Account")

Returns: SignMessageResponse containing signature.

Signs a UTF-8 message using EIP-191 personal sign. Displays a confirmation modal with the message and signer address before proceeding.

SignTypedDataAsync(...)

// object overload
Task<SignTypedDataResponse> SignTypedDataAsync(
    object typedData,
    string chainId,
    string from = null,
    string dappName = null,
    string accountName = "Account")

// Eip712TypedData overload
Task<SignTypedDataResponse> SignTypedDataAsync(
    Eip712TypedData typedData,
    string chainId,
    string from = null,
    string dappName = null,
    string accountName = "Account")

Returns: SignTypedDataResponse containing signature.

Signs EIP-712 typed structured data for on-chain use. Throws ArgumentException if typedData.domain.chainId is missing or does not match chainId. Use when typedData.domain.chainId is present (on-chain typed data).

SignTypedDataOffchainAsync(...)

// object overload
Task<SignTypedDataResponse> SignTypedDataOffchainAsync(
    object typedData,
    string from = null,
    string dappName = null,
    string accountName = "Account")

// Eip712TypedData overload
Task<SignTypedDataResponse> SignTypedDataOffchainAsync(
    Eip712TypedData typedData,
    string from = null,
    string dappName = null,
    string accountName = "Account")

Returns: SignTypedDataResponse containing signature.

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. Throws ArgumentException if typedData.domain.chainId is present and non-zero.

SignTransactionAsync(...)

// WalletUnsignedTransaction overload (Recommended)
Task<SignTxResponse> SignTransactionAsync(
    WalletUnsignedTransaction walletTx,
    string dappName = null,
    string networkName = null,
    string estimatedFee = null,
    string amount = null)

// UnsignedTx overload
Task<SignTxResponse> SignTransactionAsync(
    UnsignedTx unsignedTx,
    string chainId = null,
    string dappName = null,
    string networkName = null,
    string estimatedFee = null,
    string amount = null)

Returns: SignTxResponse containing signedTx and optional txHash.

Signs a transaction without broadcasting. Displays the sign confirmation modal before proceeding. Gas fields are resolved automatically if not provided. Use WalletUnsignedTransaction by default; use UnsignedTx only when you need low-level gateway payload control.

SendTransactionAsync(...)

// WalletUnsignedTransaction overload (Recommended)
Task<SendTxResponse> SendTransactionAsync(
    WalletUnsignedTransaction walletTx,
    string dappName = null,
    string networkName = null,
    string estimatedFee = null,
    string amount = null,
    long receiptTimeoutMs = 30000,
    long receiptPollIntervalMs = 1000)

// UnsignedTx overload
Task<SendTxResponse> SendTransactionAsync(
    UnsignedTx unsignedTx,
    string chainId = null,
    string dappName = null,
    string networkName = null,
    string estimatedFee = null,
    string amount = null,
    long receiptTimeoutMs = 30000,
    long receiptPollIntervalMs = 1000)

Returns: SendTxResponse containing txHash.

Signs and broadcasts a transaction. Displays a send confirmation modal followed by a transaction progress modal showing pending and mined states. Gas fields are auto-resolved if not provided.

SendTransactionWithWaitForReceiptAsync(...)

// WalletUnsignedTransaction overload (Recommended)
Task<JObject> SendTransactionWithWaitForReceiptAsync(
    WalletUnsignedTransaction walletTx,
    string dappName = null,
    string networkName = null,
    string estimatedFee = null,
    string amount = null,
    long timeoutMs = 30000,
    long pollIntervalMs = 1000)

// UnsignedTx overload
Task<JObject> SendTransactionWithWaitForReceiptAsync(
    UnsignedTx unsignedTx,
    string chainId = null,
    string dappName = null,
    string networkName = null,
    string estimatedFee = null,
    string amount = null,
    long timeoutMs = 30000,
    long pollIntervalMs = 1000)

Returns: JObject — the raw receipt JSON (access fields with receipt["transactionHash"], receipt["status"], etc.)

Signs, broadcasts, and waits for the transaction receipt. Internally calls SendTransactionAsync() and then fetches the receipt. The send confirmation modal and transaction progress modal are shown as part of SendTransactionAsync().

RPC / Helpers

WalletRpcAsync(request, chainId)

Task<JsonRpcResponse> WalletRpcAsync(JsonRpcRequest request, string chainId)

Returns: JsonRpcResponse with id, jsonrpc, result, and optional error (all camelCase fields).

Sends a JSON-RPC read-only request to the specified chain's RPC endpoint. Equivalent to the Android SDK's walletRpc(). Use for contract read calls (eth_call, etc.). Do not use for transaction signing or sending — use SignTransactionAsync() / SendTransactionAsync() instead.

chainId is mandatory and must be in CAIP-2 eip155:<number> format.

GetBalanceAsync(address, chainId, blockTag?)

Task<string> GetBalanceAsync(string address, string chainId, string blockTag = "latest")

Returns: Hex-encoded balance in Wei (e.g. "0xde0b6b3a7640000").

Queries the native token balance for the given address via eth_getBalance.

GetNonceAsync(address, chainId, blockTag?)

Task<string> GetNonceAsync(string address, string chainId, string blockTag = "pending")

Returns: Hex-encoded nonce (e.g. "0x5").

Returns the transaction count (nonce) for the given address via eth_getTransactionCount. Defaults to "pending" block to include mempool transactions.

WaitForTxAndGetReceiptAsync(txHash, chainId, timeoutMs?, pollIntervalMs?)

Task<JObject> WaitForTxAndGetReceiptAsync(
    string txHash,
    string chainId,
    long timeoutMs = 30000,
    long pollIntervalMs = 1000)

Returns: JObject — the raw receipt JSON (access fields with receipt["transactionHash"], receipt["status"], etc.)

Polls for a transaction receipt until it is mined or the timeout is reached. Throws TimeoutException if the timeout expires before the receipt is available. Throws if the transaction reverts (status 0x0).

Key Object Details

UnsignedTx

• chainId: string?
• from: string (required for transaction sign/send flows)
• to: string?
• value: string?
• data: string?
• nonce: string?
• gasLimit: string?
• gasPrice: string?
• maxFeePerGas: string?
• maxPriorityFeePerGas: string?

WalletUnsignedTransaction

Abstract base. Use the nested class directly:

var walletTx = new WalletUnsignedTransaction.EvmEip155("eip155:612044")
{
    From = "0xYourAddress",
    To   = "0xRecipient",
    Value = "0xde0b6b3a7640000",
    Data  = "0x"
};

• EvmEip155(string chainId): EVM EIP-155 transaction
  • ChainId: string (required, set via constructor)
  • From: string (required for sign/send flows)
  • To, Value, Data, Nonce, GasLimit, GasPrice, MaxFeePerGas, MaxPriorityFeePerGas
• Tron(string raw, string chainId = null): placeholder, not yet supported

Eip712TypedData

• Types: Dictionary<string, List<Eip712Field>>
• PrimaryType: string
• Domain: object
• Message: object

Eip712Field

• Name: string
• Type: string

TransactionReceipt

• TransactionHash: string
• BlockHash: string
• BlockNumber: string
• From: string
• To: string
• GasUsed: string
• EffectiveGasPrice: string
• Status: string
• TransactionIndex: string
• Type: string
• Logs: object
• RawJson: string

CheckWalletResponse

• result: string — raw value: "exists" | "migration_required" | "not_found"
• Exists: bool
• MigrationRequired: bool
• NotFound: bool

SetupWalletResult

• Status: WalletSetupStatus — Verified | Created | Migrated | Skipped
• Address: string?
• IsReady: bool — true when Status is Verified, Created, or Migrated

WalletSelectionResult

• Address: string
• Index: int

AuthResult

• Success: bool
• WalletAddress: string?
• User: UserInfo?
• NeedsMigration: bool?

SDKUserInfo

• Id: string
• Email: string?
• LoginType: string?
• Addresses: List<string>

SignRequestType (confirmation modal type)

• PersonalSign
• TypedData
• Transaction
• SendTransaction

JsonRpcRequest

• id: string
• jsonrpc: string
• method: string
• @params: object[] (JSON array — use new object[] { ... })

Errors

CROSSxException

class CROSSxException : Exception
{
    CROSSxErrorType ErrorType { get; }
    int? ErrorCode { get; }
    PinLockInfo LockInfo { get; }
}

CROSSxErrorType

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 (e.g. refresh token expired). Requires sign-out or re-authentication via SignInAgainAsync().
• AccountMismatch — user signed in with a different account than expected.
• InvalidPassword — wrong wallet password entered.
• PasswordLocked — too many wrong password attempts; check CROSSxException.LockInfo for lockout details.
• MigrationRequired — thrown when CreateWalletAsync(migrateAutomatically: false) encounters a migration-required wallet.

SessionExpiredException

Thrown when both access and refresh tokens are expired. The SDK shows a session expired modal allowing the user to sign in again or sign out.

GatewayException

Thrown for wallet gateway API errors with ErrorCode and ErrorData.

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)

WebView

OpenWebViewAsync(url)

Task<WebkitResult> OpenWebViewAsync(string url)

Returns: WebkitResult with Success and optional ErrorMessage.

Opens the specified URL using the bundled CROSSx Webkit SDK. Requires InitializeAsync() to have been called.

CROSS Pay

Architecture note: Checkout creation and payment status polling are game-server responsibilities. The server holds the Merchant API Key, creates the checkout, and returns checkoutUrl + checkoutId to the client. The SDK handles only the in-app WebView and deep-link callback flow.

For full CROSS Pay integration details, see the CROSS Pay documentation.

OpenCrossPayAndWaitResultAsync(checkoutUrl, checkoutId, timeoutMs?)

Task<CrossPayCallbackResult> OpenCrossPayAndWaitResultAsync(
    string checkoutUrl,
    string checkoutId,
    long timeoutMs = 300000)

Returns: CrossPayCallbackResult — decoded deep-link callback envelope.

Opens the checkout URL in WebView and waits for the deep-link callback. Throws TimeoutException if the callback does not arrive within timeoutMs.

Types

CrossPayCallbackResult — decoded deep-link callback envelope

• Status: string — envelope-level status: "success" | "cancel" | "failed" (from wallet web) or raw PG status (e.g. "PAID")
• State: string? — echoed CSRF state
• Data: JObject? — payment data from PG (fields vary by provider)
• Error: string? — error message when IsFailed
• RawParams: IReadOnlyDictionary<string, string>? — all raw query/fragment params from the callback URL (e.g. checkout_id, payment_id, tx_hash)
• IsSuccess: bool — true when Status == "success"
• IsCancel: bool — true when Status == "cancel"
• IsFailed: bool — true when Status == "failed"

Port Interfaces

The SDK follows hexagonal architecture. All external dependencies are abstracted through ports: