TONWalletKit for iOS

Table of contents

Installation

Xcode

https://github.com/ton-connect/kit-ios.git

Swift Package Manager

// Package.swift
dependencies: [
 .package(url: "https://github.com/ton-connect/kit-ios.git", branch: "main")
],
targets: [
 .target(
 name: "YourApp",
 dependencies: ["TONWalletKit"]
 )
]

import TONWalletKit

Configuration

import TONWalletKit
let apiClientConfig = TONWalletKitConfiguration.APIClientConfiguration(
 key: "YOUR_TONCENTER_API_KEY"
)
let configuration = TONWalletKitConfiguration(
 // One entry per network you want to support.
 networkConfigurations: [
 TONWalletKitConfiguration.NetworkConfiguration(
 network: .mainnet,
 apiClient: .toncenter(apiClientConfig)
 ),
 TONWalletKitConfiguration.NetworkConfiguration(
 network: .testnet,
 apiClient: .toncenter(apiClientConfig)
 ),
 ],
 // Your TON Connect manifest — shown to dApps that connect to your wallet.
 walletManifest: TONWalletKitConfiguration.Manifest(
 name: "My TON Wallet",
 appName: "my_ton_wallet",
 imageUrl: "https://example.com/icon.png",
 aboutUrl: "https://example.com/about",
 universalLink: "https://example.com/ton-connect",
 bridgeUrl: "https://connect.ton.org/bridge"
 ),
 // Where private keys / sessions are persisted (see "Storage").
 storage: .keychain,
 // TON Connect bridge. Pass `nil` if you don't need TON Connect.
 bridge: TONWalletKitConfiguration.Bridge(
 bridgeUrl: "https://connect.ton.org/bridge"
 ),
 // The TON Connect capabilities your wallet supports.
 features: [
 TONSendTransactionFeature(maxMessages: 255),
 TONSignDataFeature(types: [.text, .binary, .cell]),
 TONEmbeddedRequestFeature(),
 ]
)

API client per network

// TON Center (key required):
.init(network: .mainnet, apiClient: .toncenter(.init(key: "TONCENTER_KEY")))
// TON API:
.init(network: .mainnet, apiClient: .tonApi(.init(key: "TONAPI_KEY")))
// A fully custom client conforming to `TONAPIClient`:
.init(network: .mainnet, apiClient: myCustomClient)

Creating the kit

let kit = TONWalletKit(configuration: configuration)
// Optional: warm up the embedded JS core ahead of time.
try await kit.initialize()

Storage

.memory // in-memory, lost on relaunch — good for tests/demos
.keychain // persisted in the iOS/macOS Keychain (default, recommended)
.custom(myStorage) // your own type conforming to `TONWalletKitStorage`

final class MyStorage: TONWalletKitStorage {
 func set(key: String, value: String) async throws { /* ... */ }
 func get(key: String) async throws -> String? { /* ... */ }
 func remove(key: String) async throws { /* ... */ }
 func clear() async throws { /* ... */ }
}

Wallets

Create a brand-new wallet

let result = try await kit.createWallet(
 parameters: TONV5R1WalletParameters(network: .mainnet, domain: nil)
)
// IMPORTANT: back this mnemonic up securely and show it to the user once.
let mnemonic: TONMnemonic = result.mnemonic
let wallet = try await kit.add(walletAdapter: result.walletAdapter)
print("New wallet:", wallet.address.value)

Import from a mnemonic

let mnemonic = TONMnemonic(string: "word1 word2 ... word24") // 12 or 24 words
let signer = try await kit.signer(mnemonic: mnemonic)
let adapter = try await kit.walletV5R1Adapter(
 signer: signer,
 parameters: TONV5R1WalletParameters(network: .mainnet, domain: nil)
)
let wallet = try await kit.add(walletAdapter: adapter)

Import from a private key or an external signer

// From a raw 32-byte private key:
let signer = try await kit.signer(privateKey: privateKeyData)
// Or supply your own signer (e.g. a hardware/secure-enclave backed key):
final class MySigner: TONWalletSignerProtocol {
 func sign(data: Data) async throws -> TONHex { /* ... */ }
 func publicKey() -> TONHex { /* ... */ }
}

Generate a mnemonic only

let mnemonic = try await kit.generateMnemonic()

List, fetch, and remove

let wallets = try await kit.wallets() // [any TONWalletProtocol]
let wallet = try await kit.wallet(id: walletID)
try await kit.remove(walletId: walletID)

Reading balance & assets

let address = wallet.address.value // user-friendly string
let balance = try await wallet.balance() // TONBalance (nano-units)
// Format nano-units into a human string:
let formatter = TONBalanceFormatter()
print("Balance:", formatter.string(from: balance) ?? "0", "TON")
// Jettons (tokens) and NFTs:
let jettons = try await wallet.jettons(limit: 50)
let nfts = try await wallet.nfts(limit: 50)
let usdtBalance = try await wallet.jettonBalance(
 jettonAddress: try TONUserFriendlyAddress(value: "EQ...jettonMaster")
)

Sending TON

let request = TONTransferRequest(
 transferAmount: TONBalanceFormatter().amount(from: "1.5")!, // 1.5 TON
 recipientAddress: try TONUserFriendlyAddress(value: "EQ...recipient"),
 comment: "Thanks!"
)
let transaction = try await wallet.transferTONTransaction(request: request)
// Optional: emulate before sending.
let preview = try await wallet.preview(transactionRequest: transaction)
let response = try await wallet.send(transactionRequest: transaction)
print("Sent. Normalized hash:", response.normalizedHash.value)

try await kit.send(transaction: transaction, from: wallet)

TON Connect

Handle a connection link

try await kit.connect(url: "tc://connect?v=2&id=...")

Register an event handler

import TONWalletKit
final class WalletEventsHandler: TONBridgeEventsHandler {
 func handle(event: TONWalletKitEvent) throws {
 switch event {
 case .connectRequest(let request):
 // Show approval UI, then approve with the wallet the user chose:
 Task {
 try await request.approve(walletId: chosenWalletID)
 // or: try await request.reject(reason: "User cancelled")
 }
 case .transactionRequest(let request):
 Task { _ = try await request.approve() } // or request.reject(reason:)
 case .signMessageRequest(let request):
 Task { _ = try await request.approve() }
 case .signDataRequest(let request):
 Task { _ = try await request.approve() }
 case .disconnect(let event):
 print("dApp disconnected:", event)
 }
 }
}
let handler = WalletEventsHandler()
try kit.add(eventsHandler: handler) // may be called before initialize(); it's queued

Streaming live updates

import Combine
let streaming = try await kit.streaming()
// Register a provider for the network you want to watch (once):
let provider = try await kit.streamingProvider(
 config: TONTonCenterStreamingProviderConfig(
 network: .mainnet,
 apiKey: "YOUR_STREAMING_API_KEY"
 )
)
try streaming.register(provider: provider)
try streaming.connect()
// Subscribe to live balance updates:
let cancellable = streaming
 .balance(network: .mainnet, address: wallet.address.value)
 .sink(
 receiveCompletion: { completion in
 if case .failure(let error) = completion { print("stream error:", error) }
 },
 receiveValue: { update in
 print("New balance:", update.balance)
 }
 )

DeFi: swap, staking, gasless

// Swap
let swap = try await kit.swap()
let omniston = try await kit.omnistonSwapProvider(config: nil)
try swap.register(provider: omniston)
// let dedust = try await kit.dedustSwapProvider(config: nil)
// quote / build a swap transaction via `swap.quote(...)` and `swap.swapTransaction(params:)`
// Staking
let staking = try await kit.staking()
let stakers = try await kit.stakingProvider(config: TONTonStakersProviderConfig(/* ... */))
try staking.register(provider: stakers)
// Gasless (pay fees in jettons)
let gasless = try await kit.gasless()
let gaslessProvider = try await kit.tonApiGaslessProvider(config: TONTonApiGaslessProviderConfig(/* ... */))
try gasless.register(provider: gaslessProvider)
// Jettons metadata/utilities
let jettons = try await kit.jettons()

Working with amounts & addresses

Error handling

do {
 let wallet = try await kit.wallet(id: walletID)
 _ = try await wallet.balance()
} catch let error as TONWalletKitError {
 // .notInitialized, .bridgeUnavailable, .streamingNetworkUnavailable, .bridgeRequestTimeout
 print("WalletKit error:", error.localizedDescription)
} catch {
 print("Unexpected:", error.localizedDescription)
}

Development

make js # build from the pinned walletkit source
make js WALLETKIT_PATH=<local_path> # build from a local checkout

DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcrun swift test