FAQ

What is the Hinkal SDK?

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

When should I use the SDK instead of the API?

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

When should I use the SDK instead of WaaS?

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

What can I build with the SDK?

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

Which chains are supported?

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

What is the minimum SDK integration flow?

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

How long does integration take?

Most teams complete an initial integration within a few days.

Do users need a new wallet?

No.

Do users need a new blockchain?

No.

Is the SDK custodial?

No.

Do I need smart contract changes?

No.

Do I need backend infrastructure?

No.

Do I need zero-knowledge expertise?

No.

What is the first SDK method I should call?

Initialize the SDK and establish the user's identity.

How do I install the SDK?

Install it from npm and follow the integration guide.

Which Node.js versions are supported?

Use the versions specified in the SDK documentation.

Does the SDK support React?

Yes.

Does the SDK support Next.js?

Yes.

Does the SDK support Node.js?

Yes.

Does the SDK support browser environments?

Yes.

Does the SDK support TypeScript?

Yes.

Can I integrate it into an existing application?

Yes.

Do I need environment variables?

Only if your application architecture requires them.

Do I need RPC providers?

Yes, for blockchain connectivity.

How do I connect a wallet?

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

Which wallet providers are supported?

Most major wallet providers are supported.

Does Hinkal support MetaMask?

Yes.

Does Hinkal support Rabby?

Yes.

Does Hinkal support Phantom?

Yes.

Does Hinkal support Privy?

Yes.

Does Hinkal support Turnkey?

Yes.

Does Hinkal support Dynamic?

Yes.

Does Hinkal support DFNS?

Yes.

Does Hinkal support MPC wallets?

Yes.

Does Hinkal support smart wallets?

Yes.

Does Hinkal support hardware wallets?

Yes.

Can I use ethers.js signers?

Yes.

Can I use viem signers?

Yes.

What signer interface is required?

The signer must support message signing and transaction authorization.

How is a Hinkal identity created?

The SDK derives a private identity from wallet authentication.

What is storeAndGetInitialSignature()?

A helper used to maintain a stable identity across sessions.

Why do I need storeAndGetInitialSignature()?

Some wallet providers generate different signatures for identical messages.

What happens if I don't use it?

Users may appear as different private accounts after reconnecting.

Which wallets require it?

Typically embedded wallets and some MPC providers.

Why can't I see my previous balances?

Most commonly because a different identity was generated.

Why did my identity change after reconnecting?

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

How do I restore an existing identity?

Reuse the originally stored signature.

Does the SDK support deterministic signatures?

Yes.

Does the SDK support non-deterministic signatures?

Yes.

Do I need RFC6979 signatures?

No.

Can identities be backed up?

Identity persistence should be implemented by the integrating application.

Can identities be migrated?

Yes, if the original identity information is preserved.

Can identities be shared between devices?

Yes, if identity persistence is properly implemented.

How should I persist user sessions?

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

How do I retrieve balances?

Use the SDK balance retrieval methods.

Can I retrieve private balances?

Yes.

Can I retrieve public balances?

Yes.

How often should balances be refreshed?

After transactions and significant user actions.

Why is my balance empty?

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

Can I retrieve supported assets?

Yes.

Can I retrieve supported chains?

Yes.

Does balance retrieval require signing?

Depending on the operation, yes.

Can balances be cached?

Yes.

How does balance synchronization work?

The SDK synchronizes balance information with supported networks and services.

Which transaction flows are supported?

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

What is Public→Private?

A deposit into a confidential balance.

What is Private→Private?

A confidential transfer.

What is Private→Public?

A withdrawal to a public address.

What is Public→Public?

A private routing flow between public wallets.

How do I perform a deposit?

Use the SDK deposit methods.

How do I perform a withdrawal?

Use the SDK withdrawal methods.

How do I perform a transfer?

Use the SDK transfer methods.

How do I perform a swap?

Use the SDK swap methods.

How do I perform a private send?

Use the SDK private send functionality.

Can I send to multiple recipients?

Yes.

Can I build payroll systems?

Yes.

Can I build treasury systems?

Yes.

Can I build payout systems?

Yes.

Can I build settlement systems?

Yes.

What is depositAndWithdraw()?

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

What is depositAndWithdrawExtended()?

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

When should I use depositAndWithdrawExtended()?

Whenever transaction controlling is required.

What is scheduledId?

A unique identifier used to control asynchronous execution.

What is the difference between txHash and scheduledId?

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

How do I control a private send?

Store the scheduledId and query status methods.

How do I control recipient payouts?

Use scheduledId with transaction status methods.

What is checkSendTransactionStatus()?

A method used to retrieve transaction execution status.

How are relayer fees calculated?

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.

What is variableRate?

A configurable percentage-based fee parameter.

How do I configure a 0.1% fee?

Set variableRate to 10 basis points.

Can I estimate fees before sending?

Yes.

Why is my transaction stuck?

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

Why is my private send still pending?

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

Why am I getting an invalid signature error?

Verify signer configuration, wallet setup, and identity initialization.

Why am I getting a CSP error?

The required WebAssembly permissions are not enabled.

What information should I provide when reporting an SDK issue?

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