iOS SDK — Getting Started

Skill — Download

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

Requirements

iOS 15.0+
Xcode 15.0+
Swift 5.9+

1) Install (Swift Package Manager)

Add the dependency to Package.swift:

dependencies: [
    .package(url: "https://github.com/to-nexus/crossy-sdk-ios.git", from: "2.0.0")
]

Or in Xcode: File → Add Package Dependencies and enter the repository URL.

2) Configure project ID and app name

appName is required — it is shown in signing and sending confirmation UI as the default dApp label.

let config = SDKConfig(
    projectId: "your-project-id",
    appName: "My App"
)

projectId — issued from the CROSS management console. Included as X-Project-Id header in all API requests.
appName — displayed in sign/send confirmation dialogs (e.g. "My App is requesting a Signature").

The callback scheme is automatically derived as crossx-{projectId}. To override it, pass callbackScheme explicitly:

let config = SDKConfig(
    projectId: "your-project-id",
    appName: "My App",
    callbackScheme: "my-custom-scheme"
)

3) Register URL scheme callback

OAuth completes in ASWebAuthenticationSession and redirects to {callbackScheme}://....

Add a URL scheme in Info.plist:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>crossx-your-project-id</string>
        </array>
    </dict>
</array>

Forward callback URL to SDK in your AppDelegate or SceneDelegate:

func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
    return sdk.handleURL(url)
}

4) Create SDK instance

let config = SDKConfig(
    projectId: "your-project-id",
    appName: "My App",
    theme: .system,   // optional, default .system
    debug: true       // optional, default true
)

let sdk = try CROSSxSDK(config: config)

Theme customization

Pass SDKThemeTokens to override the default design tokens:

let config = SDKConfig(
    projectId: "your-project-id",
    appName: "My App",
    theme: .dark,
    themeTokens: SDKThemeTokens(
        light: SDKColorOverrides(primary: "#FF6B35", background: "#F5F0EB"),
        dark: SDKColorOverrides(primary: "#FF6B35", background: "#1A0A00")
    )
)

You can also change the theme at runtime:

sdk.applyTheme(themeMode: .dark)
sdk.applyTheme(
    themeMode: .dark,
    themeTokens: SDKThemeTokens(
        dark: SDKColorOverrides(primary: "#4D9FFF", background: "#121212")
    )
)

5) Basic auth flow

// app launch: attempt restore
let restored = try await sdk.initialize() // AuthResult? (nil if no restorable session)

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

// open OAuth (ASWebAuthenticationSession)
let auth = try await sdk.signIn()

// one-step login + wallet creation
let authWithWallet = try await sdk.signInWithCreate()

// sign out
try await sdk.signOut()

6) Basic wallet flow

let chainId = "eip155:612044"

let addr = try await sdk.getAddress()
let balanceHex = try await sdk.getBalance(
    address: addr.address,
    chainId: chainId
)

// For sign/send flows, see wallet docs.