iOS Mobile SDK - Circle Docs

The Circle iOS SDK enables user-controlled wallets within your mobile application. Three authentication methods are supported, namely social logins, email, or PIN, which includes security questions for recovery. This allows you to authenticate your users in a seamless way and create user-controlled wallets for them. By integrating this client-side SDK, your users can securely create wallets and make transactions using social accounts or email. If you choose the PIN authentication method, your users can input sensitive data, like PINs or security answers, in a secure way. Moreover, the SDK encrypts the request body sent by the application, protecting your users’ information.

Note:The Web and Mobile SDKs preserve the user keyshare with the individual, giving them complete control. You must use the SDKs with the user-controlled wallet product. Additionally, the Web and Mobile SDKs support only the user-controlled wallet product.

At Circle, we understand the importance of end-to-end security for your application and the need to create a tailored and seamless user experience for your end-users. Hence, Circle’s SDK also exposes functionality for you to customize the description and layout. See the iOS SDK UI Customization API article about customizing the SDK.

Install the SDKs

The iOS SDK supports:

iOS 13.0+
macOS 12.5+
Xcode 14.1+

*Earlier versions are not supported.

CocoaPods (recommended)

CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:

Terminal

brew install cocoapods

How to install Homebrew in MacOS: Link

To integrate into your Xcode project using CocoaPods, specify it in your Podfile:

Podfile

source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/circlefin/w3s-ios-sdk-podspecs.git'

target '<Your Target Name>' do
  pod 'CircleProgrammableWalletSDK'
end

Then, run the following command:

Terminal

pod install

Manual

You can also manually set up the iOS SDK by downloading it from GitHub: circlefin/w3s-ios-sdk.

SDK architecture

You must use Web, iOS, or Android SDKs to access the user-controlled Programmable Wallet product. The SDK secures, manages, and communicates with your server to ensure your user’s keyshare, always stays with them and is not exposed to your servers. To learn more, see SDK Architecture for User-Controlled Wallets.

SDK API references

WalletSdk

Public Methods
/// Singleton `public static let shared = WalletSdk()`
/// Set SDK configuration /// - Parameter configuration: Configure the Circle endpoint for SDK to connect and other settings. /// - Throws: An error is thrown while the configuration is invalid. `public func setConfiguration(_ configuration: Configuration) throws`
/// Execute the operations by challengeId and call the completion after sending the request to the Circle endpoint. `public func execute(userToken: String, encryptionKey: String, challengeIds: [String], completion: ExecuteCompletion? = nil)`
/// Set SDK LayoutProvider /// - Parameter provider: WalletSdkLayoutProvider `public func setLayoutProvider(_ provider: WalletSdkLayoutProvider)`
/// Set messenger for custom error messages /// - Parameter messenger: ErrorMessager `public func setErrorMessenger(_ messenger: ErrorMessenger)`
/// Set SDK delegate /// - Parameter delegate: WalletSdkDelegate `public func setDelegate(_ delegate: WalletSdkDelegate)`
/// Set up biometrics to protect PIN code /// - Parameters: /// - userToken: User token /// - encryptionKey: Encryption key /// - completion: The completion handler that will be called when biometrics setup is complete. `public func setBiometricsPin(userToken: String, encryptionKey: String, completion: ExecuteCompletion? = nil)`
/// Get device ID /// - Returns: String ex: 01234567-0123-0123-0123-012345678901 `public func getDeviceId() -> String`
/// Get the SDK version string /// - Returns: String? ex: 1.0.3 (63) `public func sdkVersion() -> String?`
/// Execute social provider login flow to get userToken, encryptionKey, refreshToken and OAuthInfo object `public func performLogin(provider: SocialProvider, deviceToken: String, encryptionKey: String, completion: LoginCompletion? = nil)`
/// Prompt OTP input UI and to verify email OTP and get userToken, encryptionKey, refreshToken `public func verifyOTP(deviceToken: String, encryptionKey: String, otpToken: String, completion: LoginCompletion? = nil)`
/// Clean login data, includes provider’s data and userSecret `public func performLogout(provider: SocialProvider, completion: LogoutCompletion? = nil)`

WalletSdk.Configuration

public struct Configuration

Fields
String	`endPoint` Init with Circle endpoint. SDK will connect to this endpoint.
String	`appId` AppID from Circle Developer Services Console
SettingsManagement	`settings` Configure other settings and features

SettingsManagement

Swift

public struct SettingsManagement {

    /// Enable biometrics to protect PIN code
    let enableBiometricsPin: Bool

    public init(enableBiometricsPin: Bool = false)
}

💡 Notice:Important: In any app that uses biometrics, include the NSFaceIDUsageDescription key in the app’s Info.plist file. Without this key, the system won’t allow your app to use biometrics (Face ID).

ExecuteCompletion

Swift

public typealias ExecuteCompletion = ((ExecuteCompletionStruct) -> Void)

ExecuteCompletionStruct

Swift

public struct ExecuteCompletionStruct {
    public let challenges: [String]
    public let result: Result<ExecuteResult, ApiError>
    public let onErrorController: UINavigationController?
    public let onWarning: ExecuteWarning?
}

When receiving an error or warning, we will not close the current page by default.
You will get the onErrorController in the callback, and then you can decide to dismiss/push the page by your error-handling strategy.

ExecuteResult

Swift

public struct ExecuteResult {

  /// The type of the operation that the challenge represents.
  public let resultType: ChallengeType

  /// The execute result
  public let status: ChallengeStatus

  /// The data of the execution. (optional)
  public private(set) var data: ExecuteResultData? = nil
}

ChallengeType

Swift

public enum ChallengeType: String, Decodable {
  case SET_PIN
  case CHANGE_PIN
  case RESTORE_PIN
  case SET_SECURITY_QUESTIONS
  case SET_BIOMETRICS_PIN
  case CREATE_WALLET
  case CREATE_TRANSACTION
  case ACCELERATE_TRANSACTION
  case CANCEL_TRANSACTION
  case CONTRACT_EXECUTION
  case SIGN_MESSAGE
  case SIGN_TYPEDDATA
  case SIGN_TRANSACTION
  case INITIALIZE
  case WALLET_UPGRADE
  case UNKNOWN
}

ChallengeStatus

Swift

public enum ChallengeStatus: String, Decodable {
  case PENDING
  case IN_PROGRESS
  case COMPLETE
  case FAILED
  case EXPIRED
}

ExecuteResultData

Swift

public struct ExecuteResultData: Decodable {

    /// The signature for SIGN_MESSAGE and SIGN_TYPEDDATA
    public let signature: String?

    /// For SIGN_TRANSACTION
    public let signedTransaction: String?

    /// For SIGN_TRANSACTION
    public let txHash: String?

    /// For SIGN_TRANSACTION and only returned for ECDSA chains
    public let v: String?

    /// For SIGN_TRANSACTION and only returned for ECDSA chains
    public let r: String?

    /// For SIGN_TRANSACTION and only returned for ECDSA chains
    public let s: String?

}

ExecuteWarning

Swift

public struct ExecuteWarning {

    /// The warning type of the operation (the challenge execution is success)
    public let warningType: WarningType

    /// Description of the warning type
    public var warningString: String
}

WarningType

Swift

public enum WarningType: Int {

    // Biometrics

    case deviceNotSupportBiometrics = 155709
    case biometricsKeyPermanentlyInvalidated = 155710   // For Android
    case biometricsUserSkip = 155711
    case biometricsUserDisableForPin = 155712
    case biometricsUserLockout = 155713                 // For Android
    case biometricsUserLockoutPermanent = 155714
    case biometricsUserNotAllowPermission = 155715
    case biometricsInternalError = 155716
}

LoginCompletion

Swift

public typealias LoginCompletion = ((LoginCompletionStruct) -> Void)

LoginCompletionStruct

Swift

public struct LoginCompletionStruct {
    public let result: Result<LoginResult, ApiError>
    public let onErrorController: UIViewController?
}

LoginResult

Swift

public struct LoginResult {
    public let userToken: String
    public let encryptionKey: String
    public let refreshToken: String
    public let oauthInfo: OauthInfo?
}

OauthInfo

OauthInfo for Social login

public struct OauthInfo: Decodable {
    public let provider: String
    public let scope: [String]?
    public let socialUserUUID: String
    public let socialUserInfo: SocialUserInfo?
}

SocialUserInfo

SocialUserInfo for Social login

Swift

public struct OauthInfo: Decodable {
    public struct SocialUserInfo: Decodable {
        public let name: String?
        public let email: String?
        public let phone: String?
    }

    public let provider: String
    public let scope: [String]?
    public let socialUserUUID: String
    public let socialUserInfo: SocialUserInfo?
}

LogoutCompletion

Swift

public typealias LogoutCompletion = ((Result<Void, Error>) -> Void)

ApiError

public struct ApiError

Fields
ApiError.ErrorCode	`errorCode`
String	`errorString` /// Error string from the SDK
String	`displayString` /// Error string for UI display

ApiError.ErrorCode

public enum

Enum Cases

case undefined(code: Int) // Error code defined dynamically by server, not in SDK.

case unknown = -1
case success = 0
case apiParameterMissing = 1
case apiParameterInvalid = 2
case forbidden = 3
case unauthorized = 4
case retry = 9
case customerSuspended = 10
case pending = 11
case invalidSession = 12
case invalidPartnerId = 13
case invalidMessage = 14
case invalidPhone = 15
case userAlreadyExisted = 155101
case userNotFound = 155102
case userTokenNotFound = 155103
case userTokenExpired = 155104
case invalidUserToken = 155105
case userWasInitialized = 155106
case userHasSetPin = 155107
case userHasSetSecurityQuestion = 155108
case userWasDisabled = 155109
case userDoesNotSetPinYet = 155110
case userDoesNotSetSecurityQuestionYet = 155111
case incorrectUserPin = 155112
case incorrectDeviceId = 155113
case incorrectAppId = 155114
case incorrectSecurityAnswers = 155115
case invalidChallengeId = 155116
case invalidApproveContent = 155117
case invalidEncryptionKey = 155118
case userPinLocked = 155119
case securityAnswersLocked = 155120
case walletIsFrozen = 155501
case maxWalletLimitReached = 155502
case walletSetIdMutuallyExclusive = 155503
case metadataUnmatched = 155504
case userCanceled = 155701
case launchUiFailed = 155702
case pinCodeNotMatched = 155703
case insecurePinCode = 155704
case hintsMatchAnswers = 155705
case networkError = 155706
case biometricsSettingNotEnabled = 155708
case deviceNotSupportBiometrics = 155709
case biometricsKeyPermanentlyInvalidated = 155710 // For Android
case biometricsUserSkip = 155711
case biometricsUserDisableForPin = 155712
case biometricsUserLockout = 155713 // For Android
case biometricsUserLockoutPermanent = 155714
case biometricsUserNotAllowPermission = 155715
case biometricsInternalError = 155716
case invalidUserTokenFormat = 155718
case userTokenMismatch = 155719
case socialLoginFailed = 155720
case loginInfoMissing = 155721
case walletIdNotFound = 156001
case tokenIdNotFound = 156002
case transactionIdNotFound = 156003
case entityCredentialNotFound = 156004
case walletSetIdNotFound = 156005

SocialProvider

Specify a social provider to operate on. See WalletSdk.performLogin and WalletSdk.performLogout.

Swift

public enum SocialProvider: String {
    case Google
    case Facebook
    case Apple
}

WalletSdkLayoutProvider

Set WalletSdkLayoutProvider for layout customization.

Swift

public protocol WalletSdkLayoutProvider: AnyObject {
  /// Set security question list
  ///
  /// - Returns: [SecurityQuestion]
  func securityQuestions() -> [SecurityQuestion]

  /// Set security question required count (default is 2), used in SecurityQuestionsViewController
  ///
  /// - Returns: Int
  func securityQuestionsRequiredCount() -> Int

  /// Set security confirm item list
  ///
  /// - Returns: [SecurityConfirmItem]
  func securityConfirmItems() -> [SecurityConfirmItem]

  /// Set local and remote images
  ///
  /// - Returns: ImageStore
  func imageStore() -> ImageStore

  /// Set theme font programmatically
  ///
  /// - Returns: ThemeFont
  func themeFont() -> ThemeConfig.ThemeFont?

  /// Set the date format for display date strings. (Default is "yyyy-MM-dd")
  /// Reference: https://stackoverflow.com/a/52297497
  ///
  /// - Returns: Date format string
  func displayDateFormat() -> String
}

SecurityQuestion

public struct SecurityQuestion

Fields
String	title The question string
SecurityQuestion.InputType	inputType The input type of the question.

SecurityQuestion.InputType

public enum InputType

Enum Cases

text
datePicker
...

SecurityConfirmItem

public struct SecurityConfirmItem

Fields
UIImage?	Image The drawable resource ID for the introduction item.
URL?	url The remote image url
String	Text The Text for the introduction item.

ImageStore

public struct ImageStore

Fields
[Img: UIImage]	local The images from local
[Img: URL]	remote The images from remote

ImageStore.Img

public enum Img

Enum Cases

naviClose
naviBack

securityIntroMain
selectCheckMark
dropdownArrow
errorInfo
securityConfirmMain

biometricsAllowMain

showPin
hidePin

transactionTokenIcon
networkFeeTipIcon
showLessDetailArrow
showMoreDetailArrow
requestIcon

WalletSdkDelegate

Methods for managing CircleProgrammableWalletSDK process and customizing controllers.

Swift

public protocol WalletSdkDelegate: AnyObject {
  /// Tells the delegate that the SDK is about to be present the controller.
  /// You can customize the layout as you wish dynamically.
  ///
  /// - Parameter controller: The UIViewController to be presented
  func walletSdk(willPresentController controller: UIViewController)

  /// Tells the delegate that the forget PIN button was selected in the controller
  ///
  /// - Parameter controller: Current controller
  /// - Parameter onSelect: Void
  func walletSdk(controller: UIViewController, onForgetPINButtonSelected onSelect: Void)

  /// Tells the delegate that the send again button was selected in the controller
  ///
  /// - Parameter controller: Current controller
  /// - Parameter onSelect: Void
  func walletSdk(controller: UIViewController, onSendAgainButtonSelected onSelect: Void)
}

ErrorMessenger

Define the customized error description. All error codes are listed in ApiError.ErrorCode.

Swift

public protocol ErrorMessenger {
  func getErrorString(_ code: ApiError.ErrorCode) -> String?
}

Static Resources

Localized String

Provide with a strings file CirclePWLocalizable.strings

Swift

"circlepw_show_pin" = "Show PIN";
"circlepw_hide_pin" = "Hide PIN";
"circlepw_continue" = "Continue";
"circlepw_next" = "Next";
...

Theme

provide with a JSON file CirclePWTheme.json

Swift

{
    "font": {
        "regular": "Arial",
        "medium": "",
        "semibold": "",
        "bold": "Arial-BoldMT",
        ...
    },

    "color": {
        "background": "#FFFFFF",
        "divider": "#F0EFEF",
        "success": "#0073C3",
        "error": "#F55538",
        "error_background": "#FDF2F2",
        ...
    }
}

ThemeConfig

public struct ThemeConfig

Fields
ThemeFontConfig?	fontConfig The struct of the theme font
ThemeColorConfig?	colorConfig The struct of the theme color

ThemeFontConfig

public struct ThemeFontConfig

Fields
String?	ultraLight The font name for ultraLight of UIFont.Weight
String?	thin The font name for thin of UIFont.Weight
String?	light The font name for light of UIFont.Weight
String?	regular The font name for regular of UIFont.Weight
String?	medium The font name for medium of UIFont.Weight
…	…

ThemeColorConfig

public struct ThemeColorConfig (see Color Reference)

Fields
String?	textMain The hex format of theme text main
String?	error The hex format of theme error
…	…

Sample Code

Set endpoint

Swift

let configuration = WalletSdk.Configuration(endPoint: endPoint, appId: appId)

do {
    try WalletSdk.shared.setConfiguration(configuration)
} catch {
    // error handling
}

Set endpoint and enable biometrics

Swift

let settings: WalletSdk.SettingsManagement = .init(enableBiometricsPin: true)
let configuration = WalletSdk.Configuration(endPoint: endPoint, appId: _appId, settingsManagement: settings)

do {
    try WalletSdk.shared.setConfiguration(configuration)
} catch {
    // error handling
}

Execute

Swift

Wallets.shared.execute(userToken: "USERTOKEN",
                       encryptionKey: "ENCRYPTIONKEY",
                       challengeIds: ["challengeId_1", "challengeId_2"])

Set Biometrics Pin

Swift

WalletSdk.shared.setBiometricsPin(userToken: "USERTOKEN",
                                  encryptionKey: "ENCRYPTIONKEY")

WalletSdkLayoutProvider

Swift

class SomeClass: WalletSdkLayoutProvider {

    func securityQuestions() -> [SecurityQuestion] {
        return [...]
    }

    func securityConfirmItems() -> [SecurityConfirmItem] {
        return [...]
    }

    func imageStore() -> ImageStore {
        let local: [ImageStore.Img: UIImage] =  [...]
        let remote: [ImageStore.Img : URL] = [...]
        return ImageStore(local: local, remote: remote)
    }

    func displayDateFormat() -> String {
        return "dd/MM/yyyy"
    }
}

WalletSdk.shared.setLayoutProvider(SomeClass())

Set Error Messages

Swift

class CustomErrorMessenger: ErrorMessenger {

    func getErrorString(_ code: ApiError.ErrorCode) -> String? {
        switch code {
        case .pinCodeNotMatched:
            return "The code you entered is not the same as the first one."

        case .insecurePinCode:
            return "Your PIN can’t have repeating or consecutive numbers."

        case .hintsMatchAnswers:
            return "Your hint can’t be the same as the answer."

        case .undefined(let code):
            if code == 155134 {
                return "Please check if the OTP value and OTP token match."
            } else {
                return nil
            }

        default:
            return nil
        }
    }
}

WalletSdk.shared.setErrorMessenger(CustomErrorMessenger())

Confirm the delegate for customizing the UI

Swift

class SomeClass: WalletSdkDelegate {
func walletSdk(willPresentController controller: UIViewController) {

// You can customize the controller's UI here

        if let vc = controller as? SecurityIntrosViewController {
            vc.introImageView.sd_setImage(with: URL(string: "https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png"), placeholderImage: UIImage(named: "imangeName"))
            vc.introLink = "https://www.google.com"
            vc.introDescLabel.text = "Test Desc here"
        }
    }
}

PerformLogin Flow

Swift

WalletSdk.shared.performLogin(provider: ”SOCIAL_PROVIDER”,
                              deviceToken: “DEVICE_TOKEN”,
                              encryptionKey: “DEVICE_ENCRYPTION_KEY”) { response in
......
}

VerifyOTP flow

Swift

WalletSdk.shared.verifyOTP(deviceToken: “DEVICE_TOKEN”,
                           encryptionKey: “DEVICE_ENCRYPTION_KEY”
                           otpToken: ”OTP_TOKEN”) { response in
    ......
}

PerformLogout Flow

Swift

WalletSdk.shared.performLogout(provider:  ”SOCIAL_PROVIDER”) { result in
    ......
}

See our sample app guides.

Wallets

Contracts

CCTP

CCTP V1

Gateway

Paymaster

References

​Install the SDKs

​CocoaPods (recommended)

​Manual

​SDK architecture

​SDK API references

​WalletSdk

​WalletSdk.Configuration

​SettingsManagement

​ExecuteCompletion

​ExecuteCompletionStruct

​ExecuteResult

​ChallengeType

​ChallengeStatus

​ExecuteResultData

​ExecuteWarning

​WarningType

​LoginCompletion

​LoginCompletionStruct

​LoginResult

​OauthInfo

​SocialUserInfo

​LogoutCompletion

​ApiError

​ApiError.ErrorCode

​SocialProvider

​WalletSdkLayoutProvider

​SecurityQuestion

​SecurityQuestion.InputType

​SecurityConfirmItem

​ImageStore

​ImageStore.Img

​WalletSdkDelegate

​ErrorMessenger

​Static Resources

​Localized String

​Theme

​ThemeConfig

​ThemeFontConfig

​ThemeColorConfig

​Sample Code

​Set endpoint

​Set endpoint and enable biometrics

​Execute

​Set Biometrics Pin

​WalletSdkLayoutProvider

​Set Error Messages

​Confirm the delegate for customizing the UI

​PerformLogin Flow

​VerifyOTP flow

​PerformLogout Flow

Install the SDKs

CocoaPods (recommended)

Manual

SDK architecture

SDK API references

WalletSdk

WalletSdk.Configuration

SettingsManagement

ExecuteCompletion

ExecuteCompletionStruct

ExecuteResult

ChallengeType

ChallengeStatus

ExecuteResultData

ExecuteWarning

WarningType

LoginCompletion

LoginCompletionStruct

LoginResult

OauthInfo

SocialUserInfo

LogoutCompletion

ApiError

ApiError.ErrorCode

SocialProvider

WalletSdkLayoutProvider

SecurityQuestion

SecurityQuestion.InputType

SecurityConfirmItem

ImageStore

ImageStore.Img

WalletSdkDelegate

ErrorMessenger

Static Resources

Localized String

Theme

ThemeConfig

ThemeFontConfig

ThemeColorConfig

Sample Code

Set endpoint

Set endpoint and enable biometrics

Execute

Set Biometrics Pin

WalletSdkLayoutProvider

Set Error Messages

Confirm the delegate for customizing the UI

PerformLogin Flow

VerifyOTP flow

PerformLogout Flow