# iOS

## Wallet SDK - iOS

The Wallet SDK provides an easy way to connect to user wallets and manage user sessions.

💡ROLLUPS THIS SDK SUPPORTS

* XpansionChain

⚠️THIS SDK IS UNSTABLEThis SDK is not yet at v1.0 so its public interface should not be considered final. Future releases may include breaking changes without further notice. We will do our best to keep this documentation updated providing visibility on breaking changes planned.CONTENTS

* <mark style="color:blue;">Installation</mark>
  * <mark style="color:blue;">Supported wallet providers</mark>
  * <mark style="color:blue;">Prerequisites</mark>
  * <mark style="color:blue;">Cocoapods</mark>
* <mark style="color:blue;">Connect wallet</mark>
  * <mark style="color:blue;">Connect via WalletConnect</mark>
  * <mark style="color:blue;">Restart existing session</mark>
* <mark style="color:blue;">Disconnect wallet</mark>
* <mark style="color:blue;">Handle callbacks</mark>
  * <mark style="color:blue;">Set callback</mark>
  * <mark style="color:blue;">Pending states</mark>
  * <mark style="color:blue;">Remove callback</mark>
* <mark style="color:blue;">Usage with the Core SDK</mark>
* <mark style="color:blue;">Further documentation</mark>

***

📚SDK LINKS

* <mark style="color:blue;">SDK reference</mark>
* <mark style="color:blue;">Github repository</mark>

### Installation[​](https://docs.x.immutable.com/docs/sdks/wallet/ios#installation) <a href="#installation" id="installation"></a>

This SDK is closed source and only available as a XCTFramework through Cocoapods.

#### Supported wallet providers[​](https://docs.x.immutable.com/docs/sdks/wallet/ios#supported-wallet-providers) <a href="#supported-wallet-providers" id="supported-wallet-providers"></a>

* Any wallet that supports <mark style="color:blue;">WalletConnect v1.0</mark>

#### Prerequisites[​](https://docs.x.immutable.com/docs/sdks/wallet/ios#prerequisites) <a href="#prerequisites" id="prerequisites"></a>

* iOS 13.0
* Swift 5.7

#### Cocoapods[​](https://docs.x.immutable.com/docs/sdks/wallet/ios#cocoapods) <a href="#cocoapods" id="cocoapods"></a>

In your `Podfile`:

```
# Important: ensure this source is specified in the Podfile
source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '13.0'
use_frameworks!

target 'MyApp' do
  pod 'XpansionChainWallet'
end
```

### Connect wallet[​](https://docs.x.immutable.com/docs/sdks/wallet/ios#connect-wallet) <a href="#connect-wallet" id="connect-wallet"></a>

#### Connect via WalletConnect[​](https://docs.x.immutable.com/docs/sdks/wallet/ios#connect-via-walletconnect) <a href="#connect-via-walletconnect" id="connect-via-walletconnect"></a>

```
try await XpansionChainWallet.shared.connect(
    to: .walletConnect(
        config: .init(
            appURL: URL(string: "https://XpansionChain.com")!,
            appName: "XpansionChain Sample",
            // The Universal Link or URL Scheme of the chosen wallet to be connected.
            walletDeeplink: "https://metamask.app.link"
        )
    )
)
```

> **NOTE**: the async methods that require user actions with the chosen wallet app will only complete when the requested action has been performed (i.e. accepted or denied).

If you want to use your own bridge server instead of the default provide it via `bridgeServer` when connecting. For more info on how WalletConnect and the bridge works <mark style="color:blue;">see here.</mark>

#### Restart existing session[​](https://docs.x.immutable.com/docs/sdks/wallet/ios#restart-existing-session) <a href="#restart-existing-session" id="restart-existing-session"></a>

The user's previous wallet sessions will be automatically restored when the app is launched, however it can also be manually triggered.

```
try await XpansionChainWallet.shared.restartSession()
```

### Disconnect wallet[​](https://docs.x.immutable.com/docs/sdks/wallet/ios#disconnect-wallet) <a href="#disconnect-wallet" id="disconnect-wallet"></a>

```
try await XpansionChainWallet.shared.disconnect()
```

### Handle callbacks[​](https://docs.x.immutable.com/docs/sdks/wallet/ios#handle-callbacks) <a href="#handle-callbacks" id="handle-callbacks"></a>

All the XpansionChain`Wallet` methods (connect, disconnect, etc.) are asynchronous, and will only return when they've completed the operation. If a user is taken to a wallet app for a connection or signature and does not perform the required operation, the request will not complete, leading to a pending state that is communicated via the callback.

Status callbacks are also useful for listening to status updates triggered from different screens.

#### Set callback[​](https://docs.x.immutable.com/docs/sdks/wallet/ios#set-callback) <a href="#set-callback" id="set-callback"></a>

```
XpansionChainWallet.shared
    .setStatusCallbackForId("unique identifier") { status in
        switch status {
        case .connecting:
            // Waiting for a provider to connect or restarting a previous session.
            break

        case .pendingConnection:
            // Emitted when the app has returned to the foreground after triggering a connection request but doesn't have a
            // result yet.
            break

        case .pendingSignature:
            // Emitted when the app has returned to the foreground after triggering a signature request but doesn't have a
            // result yet.
            break

        case .connected:
            // An L1 wallet is connected and an L2 wallet is successfully derived.
            break

        case .disconnecting:
            // Waiting for a provider to disconnect.
            break

        case .disconnected:
            // A wallet moves from Connected to Disconnected. Failure to connect will throw an error.
            break
        }
}
```

#### Pending states[​](https://docs.x.immutable.com/docs/sdks/wallet/ios#pending-states) <a href="#pending-states" id="pending-states"></a>

If a wallet app has been launched to connect or sign and your app has resumed but no result has arrived, `.pendingConnection` or `.pendingSignature` will be sent to the callback.

This allows you to handle this scenario flexibly; you could re-launch their wallet and complete the flow, show a popup or continue showing a waiting state, for example.

#### Remove callback[​](https://docs.x.immutable.com/docs/sdks/wallet/ios#remove-callback) <a href="#remove-callback" id="remove-callback"></a>

You may unregister from all callbacks

```
XpansionChainWallet.shared.removeAllStatusCallbacks()
```

or remove a specific one

```
XpansionChainWallet.shared.removeStatusCallbackForId("unique identifier")
```

### Usage with the Core SDK[​](https://docs.x.immutable.com/docs/sdks/wallet/ios#usage-with-the-core-sdk) <a href="#usage-with-the-core-sdk" id="usage-with-the-core-sdk"></a>

This Wallet SDK is designed to be used in tandem with the <mark style="color:blue;">XpansionChain Core SDK for Swift.</mark>

Once you connect a user's wallet with the Wallet SDK you can provide the `Signer` and `StarkSigner` instances to Core SDK workflows.

```
guard let signer = XpansionChainWallet.shared.signer, 
    let starkSigner = XpansionChainWallet.shared.starkSigner else {
    // handle not connected
    return
}

let result = try await XpansionChain.shared.createTrade(
    orderId: orderId, 
    signer: signer, 
    starkSigner: starkSigner
)
```

### Further documentation[​](https://docs.x.immutable.com/docs/sdks/wallet/ios#further-documentation) <a href="#further-documentation" id="further-documentation"></a>

Check out the <mark style="color:blue;">UI guide for implementing user wallet interactions</mark>.

* See the <mark style="color:blue;">Developer homepage</mark> for general information on building on XpansionChain.
* Build on XpansionChain zkEVM:
  * <mark style="color:blue;">Documentation</mark>
  * <mark style="color:blue;">API reference</mark>
  * <mark style="color:blue;">Support</mark>
* Build on XpansionChain:
  * <mark style="color:blue;">Documentation</mark>
  * <mark style="color:blue;">API reference</mark>
  * <mark style="color:blue;">Support</mark>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://xpansionchain-1.gitbook.io/xpansionchain/sdks/wallet-sdk/ios.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.