> For the complete documentation index, see [llms.txt](https://hinkal-team.gitbook.io/hinkal/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hinkal-team.gitbook.io/hinkal/hinkal-mobile-sdk/ios/api-reference.md).

# 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.

{% hint style="info" %}
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).
{% endhint %}

### MobileClient

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

**MobileNewClient**

```swift
func MobileNewClient() -> MobileClient?
```

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

**connect**

```swift
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**

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

Connects a Solana wallet.

**connectTron**

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

Connects a Tron wallet.

**connect(withPrivateKey:chainID64:)**

```swift
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**

```swift
func hinkal() -> MobileHinkal?
```

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

**disconnect**

```swift
func disconnect() throws
```

Clears the session.

**getFeeStructureJSON**

```swift
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**

```swift
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**

```swift
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**

```swift
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:)**

```swift
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**

```swift
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**

```swift
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**

```swift
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**

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

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

**withdrawStuckUtxos**

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

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

#### Swaps

**swap / swapSolana**

```swift
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**

```swift
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:)**

```swift
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**

```swift
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**

```swift
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**

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

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

**emporiumOp**

```swift
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**

```swift
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**

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

Funds stuck in unspendable UTXOs. Recover with `withdrawStuckUtxos`.

**getRecipientInfo / getShieldedPublicKey / getSolanaPublicKey**

```swift
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**

```swift
func getSupportedChains() throws -> String
```

Supported chains for the connected identity (JSON).

**initUserKeys(withSignature:) / initUserKeysFromSeedPhrases**

```swift
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`.

```swift
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

```swift
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

```swift
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

```swift
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):

```swift
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

```swift
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

```swift
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.