> 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-sdk/faq.md).

# FAQ

<details>

<summary>What is the Hinkal SDK?</summary>

The Hinkal SDK enables developers to integrate confidential blockchain transactions into applications without implementing zero-knowledge cryptography themselves.

</details>

<details>

<summary>When should I use the SDK instead of the API?</summary>

Use the SDK when building frontend applications, wallets, embedded finance products, or user-facing experiences that require direct wallet interaction.

</details>

<details>

<summary>When should I use the SDK instead of WaaS?</summary>

Use the SDK when users control their own wallets. Use WaaS when you need managed wallets and organizational controls.

</details>

<details>

<summary>What can I build with the SDK?</summary>

Private payments, payroll systems, treasury tools, settlement platforms, wallets, embedded finance applications, and OTC solutions.

</details>

<details>

<summary>Which chains are supported?</summary>

Ethereum, Polygon, Arbitrum, Base, Optimism, Avalanche, Solana, Tron, and supported EVM-compatible networks.

</details>

<details>

<summary>What is the minimum SDK integration flow?</summary>

Connect wallet, initialize SDK, create or restore identity, retrieve balances, execute transactions, and track status.

</details>

<details>

<summary>How long does integration take?</summary>

Most teams complete an initial integration within a few days.

</details>

<details>

<summary>Do users need a new wallet?</summary>

No.

</details>

<details>

<summary>Do users need a new blockchain?</summary>

No.

</details>

<details>

<summary>Is the SDK custodial?</summary>

No.

</details>

<details>

<summary>Do I need smart contract changes?</summary>

No.

</details>

<details>

<summary>Do I need backend infrastructure?</summary>

No.

</details>

<details>

<summary>Do I need zero-knowledge expertise?</summary>

No.

</details>

<details>

<summary>What is the first SDK method I should call?</summary>

Initialize the SDK and establish the user's identity.

</details>

<details>

<summary>How do I install the SDK?</summary>

Install it from npm and follow the integration guide.

</details>

<details>

<summary>Which Node.js versions are supported?</summary>

Use the versions specified in the SDK documentation.

</details>

<details>

<summary>Does the SDK support React?</summary>

Yes.

</details>

<details>

<summary>Does the SDK support Next.js?</summary>

Yes.

</details>

<details>

<summary>Does the SDK support Node.js?</summary>

Yes.

</details>

<details>

<summary>Does the SDK support browser environments?</summary>

Yes.

</details>

<details>

<summary>Does the SDK support TypeScript?</summary>

Yes.

</details>

<details>

<summary>Can I integrate it into an existing application?</summary>

Yes.

</details>

<details>

<summary>Do I need environment variables?</summary>

Only if your application architecture requires them.

</details>

<details>

<summary>Do I need RPC providers?</summary>

Yes, for blockchain connectivity.

</details>

<details>

<summary>How do I connect a wallet?</summary>

Use the wallet provider of your choice and pass the signer to the SDK.

</details>

<details>

<summary>Which wallet providers are supported?</summary>

Most major wallet providers are supported.

</details>

<details>

<summary>Does Hinkal support MetaMask?</summary>

Yes.

</details>

<details>

<summary>Does Hinkal support Rabby?</summary>

Yes.

</details>

<details>

<summary>Does Hinkal support Phantom?</summary>

Yes.

</details>

<details>

<summary>Does Hinkal support Privy?</summary>

Yes.

</details>

<details>

<summary>Does Hinkal support Turnkey?</summary>

Yes.

</details>

<details>

<summary>Does Hinkal support Dynamic?</summary>

Yes.

</details>

<details>

<summary>Does Hinkal support DFNS?</summary>

Yes.

</details>

<details>

<summary>Does Hinkal support MPC wallets?</summary>

Yes.

</details>

<details>

<summary>Does Hinkal support smart wallets?</summary>

Yes.

</details>

<details>

<summary>Does Hinkal support hardware wallets?</summary>

Yes.

</details>

<details>

<summary>Can I use ethers.js signers?</summary>

Yes.

</details>

<details>

<summary>Can I use viem signers?</summary>

Yes.

</details>

<details>

<summary>What signer interface is required?</summary>

The signer must support message signing and transaction authorization.

</details>

<details>

<summary>How is a Hinkal identity created?</summary>

The SDK derives a private identity from wallet authentication.

</details>

<details>

<summary>What is storeAndGetInitialSignature()?</summary>

A helper used to maintain a stable identity across sessions.

</details>

<details>

<summary>Why do I need storeAndGetInitialSignature()?</summary>

Some wallet providers generate different signatures for identical messages.

</details>

<details>

<summary>What happens if I don't use it?</summary>

Users may appear as different private accounts after reconnecting.

</details>

<details>

<summary>Which wallets require it?</summary>

Typically embedded wallets and some MPC providers.

</details>

<details>

<summary>Why can't I see my previous balances?</summary>

Most commonly because a different identity was generated.

</details>

<details>

<summary>Why did my identity change after reconnecting?</summary>

The wallet produced a different signature than the one originally used.

</details>

<details>

<summary>How do I restore an existing identity?</summary>

Reuse the originally stored signature.

</details>

<details>

<summary>Does the SDK support deterministic signatures?</summary>

Yes.

</details>

<details>

<summary>Does the SDK support non-deterministic signatures?</summary>

Yes.

</details>

<details>

<summary>Do I need RFC6979 signatures?</summary>

No.

</details>

<details>

<summary>Can identities be backed up?</summary>

Identity persistence should be implemented by the integrating application.

</details>

<details>

<summary>Can identities be migrated?</summary>

Yes, if the original identity information is preserved.

</details>

<details>

<summary>Can identities be shared between devices?</summary>

Yes, if identity persistence is properly implemented.

</details>

<details>

<summary>How should I persist user sessions?</summary>

Store identity-related information securely according to your application's requirements.

</details>

<details>

<summary>How do I retrieve balances?</summary>

Use the SDK balance retrieval methods.

</details>

<details>

<summary>Can I retrieve private balances?</summary>

Yes.

</details>

<details>

<summary>Can I retrieve public balances?</summary>

Yes.

</details>

<details>

<summary>How often should balances be refreshed?</summary>

After transactions and significant user actions.

</details>

<details>

<summary>Why is my balance empty?</summary>

Possible reasons include identity mismatch, unsupported assets, or synchronization delays.

</details>

<details>

<summary>Can I retrieve supported assets?</summary>

Yes.

</details>

<details>

<summary>Can I retrieve supported chains?</summary>

Yes.

</details>

<details>

<summary>Does balance retrieval require signing?</summary>

Depending on the operation, yes.

</details>

<details>

<summary>Can balances be cached?</summary>

Yes.

</details>

<details>

<summary>How does balance synchronization work?</summary>

The SDK synchronizes balance information with supported networks and services.

</details>

<details>

<summary>Which transaction flows are supported?</summary>

Public→Public, Public→Private, Private→Private, and Private→Public.

</details>

<details>

<summary>What is Public→Private?</summary>

A deposit into a confidential balance.

</details>

<details>

<summary>What is Private→Private?</summary>

A confidential transfer.

</details>

<details>

<summary>What is Private→Public?</summary>

A withdrawal to a public address.

</details>

<details>

<summary>What is Public→Public?</summary>

A private routing flow between public wallets.

</details>

<details>

<summary>How do I perform a deposit?</summary>

Use the SDK deposit methods.

</details>

<details>

<summary>How do I perform a withdrawal?</summary>

Use the SDK withdrawal methods.

</details>

<details>

<summary>How do I perform a transfer?</summary>

Use the SDK transfer methods.

</details>

<details>

<summary>How do I perform a swap?</summary>

Use the SDK swap methods.

</details>

<details>

<summary>How do I perform a private send?</summary>

Use the SDK private send functionality.

</details>

<details>

<summary>Can I send to multiple recipients?</summary>

Yes.

</details>

<details>

<summary>Can I build payroll systems?</summary>

Yes.

</details>

<details>

<summary>Can I build treasury systems?</summary>

Yes.

</details>

<details>

<summary>Can I build payout systems?</summary>

Yes.

</details>

<details>

<summary>Can I build settlement systems?</summary>

Yes.

</details>

<details>

<summary>What is depositAndWithdraw()?</summary>

A private send flow that deposits funds and delivers them to recipients.

</details>

<details>

<summary>What is depositAndWithdrawExtended()?</summary>

An enhanced version of depositAndWithdraw() that provides additional tracking information.

</details>

<details>

<summary>When should I use depositAndWithdrawExtended()?</summary>

Whenever transaction controlling is required.

</details>

<details>

<summary>What is scheduledId?</summary>

A unique identifier used to control asynchronous execution.

</details>

<details>

<summary>What is the difference between txHash and scheduledId?</summary>

txHash tracks blockchain execution while scheduledId tracks the full payout lifecycle.

</details>

<details>

<summary>How do I control a private send?</summary>

Store the scheduledId and query status methods.

</details>

<details>

<summary>How do I control recipient payouts?</summary>

Use scheduledId with transaction status methods.

</details>

<details>

<summary>What is checkSendTransactionStatus()?</summary>

A method used to retrieve transaction execution status.

</details>

<details>

<summary>How are relayer fees calculated?</summary>

Relayer fee = a flat fee plus a variable fee: flatFee + (amount × variableRate ÷ 10000), where variableRate is in basis points. The flat fee covers the on-chain gas cost of the transaction, estimated by the relayer (per chain), converted to USD, then priced in the chosen fee token.

</details>

<details>

<summary>What is variableRate?</summary>

A configurable percentage-based fee parameter.

</details>

<details>

<summary>How do I configure a 0.1% fee?</summary>

Set variableRate to 10 basis points.

</details>

<details>

<summary>Can I estimate fees before sending?</summary>

Yes.

</details>

<details>

<summary>Why is my transaction stuck?</summary>

Possible causes include network congestion, insufficient funds, pending approvals, or processing delays.

</details>

<details>

<summary>Why is my private send still pending?</summary>

The deposit may not have been detected yet or recipient payouts may still be processing.

</details>

<details>

<summary>Why am I getting an invalid signature error?</summary>

Verify signer configuration, wallet setup, and identity initialization.

</details>

<details>

<summary>Why am I getting a CSP error?</summary>

The required WebAssembly permissions are not enabled.

</details>

<details>

<summary>What information should I provide when reporting an SDK issue?</summary>

Provide the SDK version, chain ID, wallet provider, transaction hash, scheduledId (if available), error message, environment details, and reproduction steps.

</details>