Getting Started

Getting Started

This guide walks you through integrating the Hinkal iOS SDK into your app.

New to the SDK? Start with the Installation guide, then follow the steps below.

Prerequisites

• The SDK added to your project (Installation)

• A wallet your app can sign with (EVM, Solana, or Tron)

• A chain id and token address to work with

Overview

1. Implement a host wallet so the SDK can sign without holding the key.

2. Create a client and connect - this derives the shielded identity.

3. Call operations: deposit, transfer, withdraw, swap.

Basic Setup

Import the SDK

import Hinkal

Create a client

let client = MobileNewClient()

Handle errors

The framework is generated by gomobile, so throwing calls take an NSError out-parameter rather than Swift throws. A small rethrow helper turns that into idiomatic try (this is the pattern the demo app uses):

func call<T>(_ body: (_ err: inout NSError?) -> T) throws -> T {
    var err: NSError?
    let result = body(&err)
    if let err { throw err }
    return result
}

Every SDK call below is wrapped with call { ... error: &$0 }.

Connecting a Wallet

Implement MobileHostWalletProtocol so the SDK can read the address and request signatures. The key stays in your wallet. Its methods use an error: NSErrorPointer out-parameter (set it on failure).

class WalletHost: NSObject, MobileHostWalletProtocol {
    let wallet: YourWalletImplementation

    func address(_ error: NSErrorPointer) -> String { wallet.address }
    func chainID() -> Int64 { wallet.chainId }
    func personalSign(_ message: String?, error: NSErrorPointer) -> String {
        wallet.personalSign(message ?? "")
    }
    func sendTransaction(_ toHex: String?, dataHex: String?, valueDec: String?,
                         gasLimit: Int64, error: NSErrorPointer) -> String {
        wallet.sendTransaction(toHex ?? "", dataHex ?? "", valueDec ?? "", gasLimit)
    }
    func switchChain(_ chainID: Int64) throws { try wallet.switchChain(chainID) }
}

Connect - the wallet signs a session message and the SDK derives the shielded identity:

guard let client = MobileNewClient(), let hinkal = client.hinkal() else { return }
let address = try call { client.connect(WalletHost(wallet: yourWallet), error: &$0) }

For a headless connect use client.connect(withPrivateKey: key, chainID64: chainId, error: &$0).

Core Operations

Check Balance

let balance = try call {
    hinkal.getTotalBalance(chainId, userKeysSignature: signature, ethAddress: address,
                           resetCache: false, useBlockedUtxos: false, error: &$0)
}

Deposit Tokens

let wei = try call { MobileAmountToWei(chainId, tokenAddress, "1.0", &$0) }
let deposit = try call {
    hinkal.deposit(chainId, tokenAddrsJSON: "[\"\(tokenAddress)\"]",
                   amountsWeiJSON: "[\"\(wei)\"]", preEstimateGas: true, returnTxData: false, error: &$0)
}

Private Transfer

let transferWei = try call { MobileAmountToWei(chainId, tokenAddress, "0.5", &$0) }
let transfer = try call {
    hinkal.transfer(chainId, tokenAddrsJSON: "[\"\(tokenAddress)\"]", amountsWeiJSON: "[\"\(transferWei)\"]",
                    recipient: recipientPrivateAddress, feeToken: tokenAddress, feeStructureJSON: "", error: &$0)
}

Withdraw Tokens

let withdrawWei = try call { MobileAmountToWei(chainId, tokenAddress, "0.25", &$0) }
let withdraw = try call {
    hinkal.withdraw(chainId, tokenAddrsJSON: "[\"\(tokenAddress)\"]", amountsWeiJSON: "[\"\(withdrawWei)\"]",
                    recipient: recipientPublicAddress, relayerOff: false, feeToken: tokenAddress,
                    feeStructureJSON: "", error: &$0)
}

Swap Tokens

// Get quote first
let quoteJSON = try call { 
    hinkal.getEvmSwapPrices(chainId, inAmount: inWei, inTokenAddr: inToken, outTokenAddr: outToken, error: &$0) 
}

// Perform swap
let swap = try call {
    hinkal.swap(chainId, tokenAddrsJSON: "[\"\(inToken)\", \"\(outToken)\"]",
                amountsWeiJSON: "[\"\(inWei)\"]", actionID: actionID, swapData: swapData,
                feeToken: inToken, feeStructureJSON: "", error: &$0)
}