API Reference

Complete API reference for the Hinkal Android SDK.

The SDK exposes free functions as static methods on Mobile, and a stateful surface through two classes: Client (connection and session) and Hinkal (operations), in the io.hinkal.mobile package. Data crosses the boundary as JSON strings and primitives; native methods declare throws Exception.

Client

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

newClient

fun newClient(): Client

Creates a client with default configuration. Use newClientWithConfig(configJSON) to pass a JSON config.

connect

fun connect(host: HostWallet): String

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

connectSolana / connectTron

fun connectSolana(host: HostSolanaSigner, chainID: Long): String
fun connectTron(host: HostTronSigner, chainID: Long): String

Connect a Solana or Tron wallet.

connectWithPrivateKey

fun connectWithPrivateKey(privateKeyHex: String, chainID64: Long): String

Headless EVM connect for tests and backends. Also connectWithSolanaPrivateKey(...), connectWithTronPrivateKey(...).

hinkal

fun hinkal(): Hinkal

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

disconnect

fun disconnect()

Clears the session.

getFeeStructureJSON

fun getFeeStructureJSON(chainID64: Long, feeTokenAddr: String, tokenAddrsJSON: String,
                        actionID: String, callsJSON: String, variableRateWei: String,
                        solanaParamsJSON: String): String

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

calculateTotalFee / calculateWithdrawalAmount

fun calculateTotalFee(amountWei: String, feeStructureJSON: String): String
fun calculateWithdrawalAmount(amountWithFeeWei: String, feeStructureJSON: String): String

Fee math helpers.

getGasTokenSymbols

fun getGasTokenSymbols(chainID64: Long): String

Returns the gas token symbols for a chain.

Hinkal

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

Deposits

deposit

fun deposit(chainID: Long, tokenAddrsJSON: String, amountsWeiJSON: String,
            preEstimateGas: Boolean, returnTxData: Boolean): String

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

depositForOther

fun depositForOther(chainID: Long, tokenAddrsJSON: String, amountsWeiJSON: String,
                    recipientInfo: String, preEstimateGas: Boolean, returnTxData: Boolean): String

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

depositSolana / depositSolanaForOther

fun depositSolana(chainID: Long, tokenAddr: String, amountWei: String, returnTxData: Boolean): String
fun depositSolanaForOther(chainID: Long, tokenAddr: String, amountWei: String,
                          recipientInfo: String, returnTxData: Boolean): String

Solana deposit variants (single token).

prooflessDeposit

fun prooflessDeposit(chainID: Long, tokenAddrsJSON: String, amountsWeiJSON: String,
                     stealthAddressStructuresJSON: String, createBlockedUtxos: Boolean,
                     feeStructureJSON: String, orderID: String, returnTxData: Boolean): String

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

Withdrawals & Transfers

withdraw

fun withdraw(chainID: Long, tokenAddrsJSON: String, amountsWeiJSON: String,
             recipient: String, relayerOff: Boolean, feeToken: String,
             feeStructureJSON: String): String

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

transfer

fun transfer(chainID: Long, tokenAddrsJSON: String, amountsWeiJSON: String,
             recipient: String, feeToken: String, feeStructureJSON: String): String

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

withdrawStuckUtxos

fun withdrawStuckUtxos(chainID: Long, tokenAddr: String, recipientAddress: String): String

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

Swaps

swap / swapSolana

fun swap(chainID: Long, tokenAddrsJSON: String, amountsWeiJSON: String,
         actionID: String, swapData: String, feeToken: String, feeStructureJSON: String): String
fun swapSolana(chainID: Long, tokenAddrsJSON: String, amountsWeiJSON: String,
               swapData: String, feeToken: String, feeStructureJSON: String): String

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

getEvmSwapPrices / getSolanaSwapPrices

fun getEvmSwapPrices(chainID: Long, inAmount: String, inTokenAddr: String, outTokenAddr: String): String
fun getSolanaSwapPrices(chainID: Long, inAmount: String, inTokenAddr: String, outTokenAddr: String): String

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

Cross-chain

bridgePrivateToPrivate

fun bridgePrivateToPrivate(sourceChainID: Long, sourceTokenAddr: String, destChainID: Long,
                           destTokenAddr: String, amount: String, recipientJSON: String,
                           slippage: Double, feeToken: String): String

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

depositAndWithdraw / depositAndBridge / nearDepositAndBridge

fun depositAndWithdraw(chainID: Long, tokenAddr: String, recipientAmountsJSON: String,
                       recipientAddressesJSON: String, scheduleTimeSec: Long,
                       feeStructureJSON: String, preEstimateGas: Boolean): String
fun depositAndBridge(chainID: Long, tokenAddr: String, recipientsJSON: String,
                     scheduleTimeSec: Long, feeStructureJSON: String, preEstimateGas: Boolean): String
fun nearDepositAndBridge(chainID: Long, tokenAddr: String, recipientAmountsJSON: String,
                         recipientAddressesJSON: String, paramsJSON: String,
                         scheduleTimeSec: Long, feeStructureJSON: String): String

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

Claimables & status

claimUtxo / fetchClaimableUtxos

fun claimUtxo(chainID: Long, tokenAddr: String, handle: String,
              feeStructureJSON: String, claimableSignature: String): String
fun fetchClaimableUtxos(chainID: Long, ethAddress: String, signature: String,
                        isSolanaLedger: Boolean, txMessageForSolanaLedger: String): String

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

checkSendTransactionStatus

fun checkSendTransactionStatus(scheduleID: String): String

Polls the status of a scheduled send.

emporiumOp

fun emporiumOp(contract: String, callDataString: String, invokeWallet: Boolean, valueWei: String): String

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

waitForTransaction

fun waitForTransaction(chainID: Long, txHash: String, confirmations: Long, timeoutSec: Long): Boolean

Waits for a transaction to reach the given confirmations, up to timeoutSec.

Balances & identity

getTotalBalance

fun getTotalBalance(chainID: Long, userKeysSignature: String, ethAddress: String,
                    resetCache: Boolean, useBlockedUtxos: Boolean): String

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

getStuckShieldedBalances

fun getStuckShieldedBalances(chainID: Long, userKeysSignature: String, ethAddress: String): String

Funds stuck in unspendable UTXOs. Recover with withdrawStuckUtxos.

getRecipientInfo / getShieldedPublicKey / getSolanaPublicKey

fun getRecipientInfo(): String
fun getShieldedPublicKey(): String
fun getSolanaPublicKey(): String

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

getSupportedChains

fun getSupportedChains(): String

Supported chains for the connected identity (JSON).

initUserKeysWithSignature / initUserKeysFromSeedPhrases

fun initUserKeysWithSignature(signature: String)
fun initUserKeysFromSeedPhrases(seedPhrasesJSON: String)

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

HostWallet

The interface your app implements so the SDK can sign without holding the key.

interface HostWallet {
    fun address(): String
    fun chainID(): Long
    fun personalSign(message: String): String
    fun sendTransaction(toHex: String, dataHex: String, valueDec: String, gasLimit: Long): String
    fun switchChain(chainID: Long)
}

For Solana and Tron, implement HostSolanaSigner (publicKey, signMessage(ByteArray), signTransaction(ByteArray)) or HostTronSigner (address, signMessage(String), signTxHash(ByteArray)).

Module Functions

Static methods on Mobile.

Amounts

fun amountToWei(chainID: Long, tokenAddr: String, amount: String): String
fun amountFromWei(chainID: Long, tokenAddr: String, amountWei: String): String
fun amountWithPrecision(chainID: Long, tokenAddr: String, amountWei: String, precision: Long): String

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

Tokens

fun getTokensJSON(chainID: Long): String
fun resolveTokensJSON(chainID: Long, tokenAddrsJSON: String): String
fun resolveTokensLenientJSON(chainID: Long, tokenAddrsJSON: String): String
fun getSwapQuotesJSON(chainID64: Long, inAmount: String, inTokenAddr: String, outTokenAddr: String): String

Token catalog, resolution, and aggregated swap quotes. DEX-specific helpers: getOneInchQuoteJSON, getOdosQuoteJSON, getOKXQuoteJSON, getUniswapQuoteJSON, getExternalSwapAddress.

Chains

fun supportedChainsJSON(): String
fun allSupportedChainsJSON(): String
fun walletSupportedChainsJSON(): String
fun bridgeSupportedChainsJSON(): String
fun chainIDsJSON(): String
fun networkJSON(chainID: Long): String
fun networkRegistryJSON(): String
fun hinkalWrapperAddress(chainID: Long): String
fun solanaChainID(): Long
fun tronChainID(): Long
fun solanaNativeTokenAddress(): String

Chain predicates (return Boolean):

fun isEvmChain(chainID: Long): Boolean
fun isSolanaChain(chainID: Long): Boolean
fun isTronChain(chainID: Long): Boolean
fun isHinkalSupportedChain(chainID: Long): Boolean
fun isBridgeSupportedChain(chainID: Long): Boolean

Bridge quotes

fun getLifiBridgeQuoteJSON(sourceChainID: Long, destinationChainID: Long, sourceTokenAddr: String,
                           destinationTokenAddr: String, amount: String, slippage: Double,
                           fromAddress: String, toAddress: String): String
fun getNearIntentsQuoteJSON(requestJSON: String): String
fun getNearIntentsTokensJSON(): String
fun bridgeDestinationChainsJSON(sourceChainID: Long): String

Quotes and destination lists for cross-chain bridging.

Addresses & keys

fun isValidPrivateAddress(address: String): Boolean
fun newUserKeys(signature: String): UserKeys
fun userKeysFromNullifyingKey(nullifyingKey: String): UserKeys
fun getRecipientInfoFromSignature(signature: String): String
fun getStealthAddressStructureFromSignature(signature: String): String
fun newStealthAddressStructureJSON(privateAddress: String): String

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