API Reference

Complete API reference for the Hinkal iOS SDK.

The SDK exposes free functions as Mobile-prefixed Swift symbols, and a stateful surface through two classes: MobileClient (connection and session) and MobileHinkal (operations). Data crosses the boundary as JSON strings and primitives.

The framework is generated by gomobile, so a failing call takes a trailing error: NSErrorPointer out-parameter rather than Swift throws. Signatures below show throws for readability; at the call site pass error: &err (or wrap with the call helper from Getting Started).

MobileClient

The entry point. Create it, connect a wallet, then obtain the operations handle.

MobileNewClient

func MobileNewClient() -> MobileClient?

Creates a client with default configuration. Use MobileNewClientWithConfig(_:) to pass a JSON config.

connect

func connect(_ host: MobileHostWalletProtocol?) throws -> String

Runs the session handshake: the wallet signs a message that unlocks the shielded account. Returns the connected wallet address.

connectSolana

func connectSolana(_ host: MobileHostSolanaSignerProtocol?, chainID: Int64) throws -> String

Connects a Solana wallet.

connectTron

func connectTron(_ host: MobileHostTronSignerProtocol?, chainID: Int64) throws -> String

Connects a Tron wallet.

connect(withPrivateKey:chainID64:)

func connect(withPrivateKey privateKeyHex: String?, chainID64: Int64, error: NSErrorPointer) -> String

Headless EVM connect for tests and backends. Solana/Tron variants: connect(withSolanaPrivateKey:chainID:), connect(withTronPrivateKey:chainID:).

hinkal

func hinkal() -> MobileHinkal?

Returns the operations handle for deposits, transfers, and the rest.

disconnect

func disconnect() throws

Clears the session.

getFeeStructureJSON

func getFeeStructureJSON(_ chainID64: Int64, feeTokenAddr: String?, tokenAddrsJSON: String?,
                         actionID: String?, callsJSON: String?, variableRateWei: String?,
                         solanaParamsJSON: String?, error: NSErrorPointer) -> String

Builds a fee structure for an operation. Pass the result as feeStructureJSON to a spend.

calculateTotalFee / calculateWithdrawalAmount

func calculateTotalFee(_ amountWei: String?, feeStructureJSON: String?, error: NSErrorPointer) -> String
func calculateWithdrawalAmount(_ amountWithFeeWei: String?, feeStructureJSON: String?, error: NSErrorPointer) -> String

Fee math helpers: total fee for an amount, and the net withdrawal amount after fees.

getGasTokenSymbols

func getGasTokenSymbols(_ chainID64: Int64, error: NSErrorPointer) -> String

Returns the gas token symbols for a chain.

MobileHinkal

Obtained from client.hinkal(). All amounts are base units (wei); token and amount lists are JSON-array strings.

Deposits

deposit

func deposit(_ chainID: Int64, tokenAddrsJSON: String?, amountsWeiJSON: String?,
             preEstimateGas: Bool, returnTxData: Bool) throws -> String

Public to private. Signed and broadcast through your host wallet. Returns the transaction hash (or tx data when returnTxData is true).

deposit(forOther:)

func deposit(forOther chainID: Int64, tokenAddrsJSON: String?, amountsWeiJSON: String?,
                     recipientInfo: String?, preEstimateGas: Bool, returnTxData: Bool) throws -> String

Deposit into another user's shielded balance. recipientInfo is their recipient-info string (from getRecipientInfo).

depositSolana / depositSolanaForOther

func depositSolana(_ chainID: Int64, tokenAddr: String?, amountWei: String?, returnTxData: Bool) throws -> String
func depositSolanaForOther(_ chainID: Int64, tokenAddr: String?, amountWei: String?,
                           recipientInfo: String?, returnTxData: Bool) throws -> String

Solana deposit variants (single token).

prooflessDeposit

func prooflessDeposit(_ chainID: Int64, tokenAddrsJSON: String?, amountsWeiJSON: String?,
                      stealthAddressStructuresJSON: String?, createBlockedUtxos: Bool,
                      feeStructureJSON: String?, orderID: String?, returnTxData: Bool) throws -> String

Deposit that defers proof generation (used by scheduled deposit-and-withdraw flows). See also prooflessDepositWithPublicFee(...).

Withdrawals & Transfers

withdraw

func withdraw(_ chainID: Int64, tokenAddrsJSON: String?, amountsWeiJSON: String?,
              recipient: String?, relayerOff: Bool, feeToken: String?,
              feeStructureJSON: String?) throws -> String

Private to public, via a Hinkal relayer. Returns the transaction hash.

transfer

func transfer(_ chainID: Int64, tokenAddrsJSON: String?, amountsWeiJSON: String?,
              recipient: String?, feeToken: String?, feeStructureJSON: String?) throws -> String

Private to private (to another Hinkal user's private balance). recipient is a Hinkal private address.

withdrawStuckUtxos

func withdrawStuckUtxos(_ chainID: Int64, tokenAddr: String?, recipientAddress: String?) throws -> String

Recovers UTXOs left stuck by an interrupted deposit-and-withdraw.

Swaps

swap / swapSolana

func swap(_ chainID: Int64, tokenAddrsJSON: String?, amountsWeiJSON: String?,
          actionID: String?, swapData: String?, feeToken: String?,
          feeStructureJSON: String?) throws -> String
func swapSolana(_ chainID: Int64, tokenAddrsJSON: String?, amountsWeiJSON: String?,
                swapData: String?, feeToken: String?, feeStructureJSON: String?) throws -> String

Swap one token for another inside the shielded balance. Quote first with getEvmSwapPrices(...) / getSolanaSwapPrices(...).

getEvmSwapPrices / getSolanaSwapPrices

func getEvmSwapPrices(_ chainID: Int64, inAmount: String?, inTokenAddr: String?, outTokenAddr: String?) throws -> String
func getSolanaSwapPrices(_ chainID: Int64, inAmount: String?, inTokenAddr: String?, outTokenAddr: String?) throws -> String

Returns a swap quote (JSON) including the swapData you pass into swap.

Cross-chain

bridgePrivate(toPrivate:)

func bridgePrivate(toPrivate sourceChainID: Int64, sourceTokenAddr: String?,
                   destChainID: Int64, destTokenAddr: String?, amount: String?,
                   recipientJSON: String?, slippage: Double, feeToken: String?) throws -> String

Moves shielded value from one chain to another (private to private).

depositAndWithdraw / depositAndBridge / nearDepositAndBridge

func depositAndWithdraw(_ chainID: Int64, tokenAddr: String?, recipientAmountsJSON: String?,
                        recipientAddressesJSON: String?, scheduleTimeSec: Int64,
                        feeStructureJSON: String?, preEstimateGas: Bool) throws -> String
func depositAndBridge(_ chainID: Int64, tokenAddr: String?, recipientsJSON: String?,
                      scheduleTimeSec: Int64, feeStructureJSON: String?, preEstimateGas: Bool) throws -> String
func nearDepositAndBridge(_ chainID: Int64, tokenAddr: String?, recipientAmountsJSON: String?,
                          recipientAddressesJSON: String?, paramsJSON: String?,
                          scheduleTimeSec: Int64, feeStructureJSON: String?) throws -> String

Public-to-public and cross-chain routes. scheduleTimeSec schedules the second leg; poll checkSendTransactionStatus(...).

Claimable UTXOs & status

claimUtxo / fetchClaimableUtxos

func claimUtxo(_ chainID: Int64, tokenAddr: String?, handle: String?,
               feeStructureJSON: String?, claimableSignature: String?) throws -> String
func fetchClaimableUtxos(_ chainID: Int64, ethAddress: String?, signature: String?,
                         isSolanaLedger: Bool, txMessageForSolanaLedger: String?) throws -> String

List and claim claimable UTXOs (gift-style transfers).

checkSendTransactionStatus

func checkSendTransactionStatus(_ scheduleID: String?) throws -> String

Polls the status of a scheduled send (deposit-and-withdraw / bridge).

emporiumOp

func emporiumOp(_ contract: String?, callDataString: String?, invokeWallet: Bool, valueWei: String?) throws -> String

Executes an arbitrary contract call through the shielded account (advanced).

Balances & identity

getTotalBalance

func getTotalBalance(_ chainID: Int64, userKeysSignature: String?, ethAddress: String?,
                     resetCache: Bool, useBlockedUtxos: Bool) throws -> String

Shielded balance per token (JSON). Pass resetCache: true to re-scan after a fund-moving operation.

getStuckShieldedBalances

func getStuckShieldedBalances(_ chainID: Int64, userKeysSignature: String?, ethAddress: String?) throws -> String

Funds stuck in unspendable UTXOs. Recover with withdrawStuckUtxos.

getRecipientInfo / getShieldedPublicKey / getSolanaPublicKey

func getRecipientInfo() throws -> String
func getShieldedPublicKey() throws -> String
func getSolanaPublicKey() throws -> String

Identity accessors. getRecipientInfo returns the Hinkal private address to share for incoming private transfers.

getSupportedChains

func getSupportedChains() throws -> String

Supported chains for the connected identity (JSON).

initUserKeys(withSignature:) / initUserKeysFromSeedPhrases

func initUserKeys(withSignature signature: String?)
func initUserKeysFromSeedPhrases(_ seedPhrasesJSON: String?) throws

Derive the shielded identity from a signature or from seed phrases.

MobileHostWalletProtocol

The protocol your app implements so the SDK can sign without holding the key. Most methods use an error: NSErrorPointer out-parameter; only switchChain is throws.

protocol MobileHostWalletProtocol {
    func address(_ error: NSErrorPointer) -> String
    func chainID() -> Int64
    func personalSign(_ message: String?, error: NSErrorPointer) -> String
    func sendTransaction(_ toHex: String?, dataHex: String?, valueDec: String?,
                         gasLimit: Int64, error: NSErrorPointer) -> String
    func switchChain(_ chainID: Int64) throws
}

For Solana and Tron, implement MobileHostSolanaSignerProtocol or MobileHostTronSignerProtocol (their publicKey/address use the error: out-parameter; the signing methods are throws and return non-optional Data).

Module Functions

Amounts

func MobileAmountToWei(_ chainID: Int64, _ tokenAddr: String?, _ amount: String?) throws -> String
func MobileAmountFromWei(_ chainID: Int64, _ tokenAddr: String?, _ amountWei: String?) throws -> String
func MobileAmountWithPrecision(_ chainID: Int64, _ tokenAddr: String?, _ amountWei: String?, _ precision: Int64) throws -> String

Human to wei and back; MobileAmountWithPrecision formats to a fixed number of decimals.

Tokens

func MobileGetTokensJSON(_ chainID: Int64) throws -> String
func MobileResolveTokensJSON(_ chainID: Int64, _ tokenAddrsJSON: String?) throws -> String
func MobileResolveTokensLenientJSON(_ chainID: Int64, _ tokenAddrsJSON: String?) throws -> String
func MobileGetSwapQuotesJSON(_ chainID64: Int64, _ inAmount: String?, _ inTokenAddr: String?, _ outTokenAddr: String?) throws -> String

Token catalog, resolution, and aggregated swap quotes. DEX-specific quote helpers also exist: MobileGetOneInchQuoteJSON, MobileGetOdosQuoteJSON, MobileGetOKXQuoteJSON, MobileGetUniswapQuoteJSON, MobileGetExternalSwapAddress.

Chains

func MobileSupportedChainsJSON() throws -> String
func MobileAllSupportedChainsJSON() throws -> String
func MobileWalletSupportedChainsJSON() throws -> String
func MobileBridgeSupportedChainsJSON() throws -> String
func MobileChainIDsJSON() throws -> String
func MobileNetworkJSON(_ chainID: Int64) throws -> String
func MobileNetworkRegistryJSON() throws -> String
func MobileHinkalWrapperAddress(_ chainID: Int64) throws -> String
func MobileSolanaChainID() -> Int64
func MobileTronChainID() -> Int64
func MobileSolanaNativeTokenAddress() -> String

Chain predicates (return Bool, no throw):

func MobileIsEvmChain(_ chainID: Int64) -> Bool
func MobileIsSolanaChain(_ chainID: Int64) -> Bool
func MobileIsTronChain(_ chainID: Int64) -> Bool
func MobileIsHinkalSupportedChain(_ chainID: Int64) -> Bool
func MobileIsBridgeSupportedChain(_ chainID: Int64) -> Bool

Bridge quotes

func MobileGetLifiBridgeQuoteJSON(...) throws -> String
func MobileGetNearIntentsQuoteJSON(...) throws -> String
func MobileGetNearIntentsTokensJSON(...) throws -> String
func MobileBridgeDestinationChainsJSON(_ sourceChainID: Int64) throws -> String

Quotes and destination lists for cross-chain bridging.

Addresses & keys

func MobileIsValidPrivateAddress(_ address: String?) -> Bool
func MobileNewUserKeys(_ signature: String?) -> MobileUserKeys?
func MobileUserKeysFromNullifyingKey(_ nullifyingKey: String?) -> MobileUserKeys?
func MobileGetRecipientInfoFromSignature(_ signature: String?) throws -> String
func MobileGetStealthAddressStructureFromSignature(_ signature: String?) throws -> String
func MobileNewStealthAddressStructureJSON(_ privateAddress: String?) throws -> String

Validate private addresses and derive keys / stealth-address structures from a signature.