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

# FAQ

<details>

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

The Hinkal API exposes Hinkal's privacy protocol through REST endpoints.

</details>

<details>

<summary>Who should use the Hinkal API?</summary>

Backend developers, payment providers, exchanges, treasury platforms, and enterprise teams.

</details>

<details>

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

Use the API when building server-side integrations.

</details>

<details>

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

Use the API when users keep control of their own wallets.

</details>

<details>

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

No.

</details>

<details>

<summary>Who controls the user's wallet?</summary>

The user.

</details>

<details>

<summary>Does Hinkal access user private keys?</summary>

No.

</details>

<details>

<summary>What does Hinkal manage?</summary>

Only Hinkal shielded keys used for privacy operations.

</details>

<details>

<summary>Where does the API run?</summary>

Inside a secure enclave running on GCP Confidential VMs.

</details>

<details>

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

Ethereum, Solana, Tron, and supported EVM chains.

</details>

<details>

<summary>Does the API support Ethereum?</summary>

Yes.

</details>

<details>

<summary>Does the API support Solana?</summary>

Yes.

</details>

<details>

<summary>Does the API support Tron?</summary>

Yes.

</details>

<details>

<summary>Does the API support EVM chains?</summary>

Yes.

</details>

<details>

<summary>What operations are supported?</summary>

Deposits, withdrawals, transfers, swaps, private sends, and balance retrieval.

</details>

<details>

<summary>How does API authentication work?</summary>

Through wallet signatures and authenticated sessions.

</details>

<details>

<summary>What is a session?</summary>

A temporary authorization associated with a wallet.

</details>

<details>

<summary>How do I create a session?</summary>

Call POST /create-session.

</details>

<details>

<summary>Is a session required?</summary>

Yes.

</details>

<details>

<summary>How long does a session last?</summary>

24 hours by default.

</details>

<details>

<summary>Can sessions expire?</summary>

Yes.

</details>

<details>

<summary>What happens when a session expires?</summary>

A new session must be created.

</details>

<details>

<summary>What is clientPublicKey?</summary>

A secp256k1 public key used for authentication.

</details>

<details>

<summary>What is x-hinkal-request-signature?</summary>

A request authentication signature.

</details>

<details>

<summary>What algorithm is used?</summary>

secp256k1.

</details>

<details>

<summary>Does the API support EIP-712?</summary>

Yes.

</details>

<details>

<summary>Does the API support Solana signatures?</summary>

Yes.

</details>

<details>

<summary>Does the API support Tron signatures?</summary>

Yes.

</details>

<details>

<summary>What is Normal Mode?</summary>

A mode where sessions authorize requests.

</details>

<details>

<summary>What is EIP-712 Mode?</summary>

A mode where transactions require explicit approvals.

</details>

<details>

<summary>Which mode is recommended?</summary>

It depends on your security requirements and user experience goals.

</details>

<details>

<summary>Does every request require signing?</summary>

Authenticated requests do.

</details>

<details>

<summary>Can I reuse a session?</summary>

Yes.

</details>

<details>

<summary>Can multiple requests use the same session?</summary>

Yes.

</details>

<details>

<summary>Can I invalidate a session?</summary>

By creating a new session or waiting for expiration.

</details>

<details>

<summary>What is GET /ping?</summary>

A health-check endpoint.

</details>

<details>

<summary>What is GET /supported-chains?</summary>

Returns supported networks.

</details>

<details>

<summary>What is GET /supported-tokens?</summary>

Returns supported assets.

</details>

<details>

<summary>What is GET /balance?</summary>

Returns balance information.

</details>

<details>

<summary>What is GET /recipient-info?</summary>

Returns recipient-related information.

</details>

<details>

<summary>What is GET /get-fee-structure?</summary>

Returns fee information.

</details>

<details>

<summary>What is GET /get-swap-data?</summary>

Returns swap information.

</details>

<details>

<summary>What is POST /refresh-cache?</summary>

Refreshes cached data.

</details>

<details>

<summary>Which endpoint should I call first?</summary>

POST /create-session.

</details>

<details>

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

Using GET /balance.

</details>

<details>

<summary>How do I retrieve supported assets?</summary>

Using GET /supported-tokens.

</details>

<details>

<summary>How do I retrieve supported networks?</summary>

Using GET /supported-chains.

</details>

<details>

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

No.

</details>

<details>

<summary>Can I query balances at any time?</summary>

Yes.

</details>

<details>

<summary>Does the API support fee estimation?</summary>

Yes.

</details>

<details>

<summary>What is POST /deposit?</summary>

A Public→Private transaction.

</details>

<details>

<summary>What is POST /withdraw?</summary>

A Private→Public transaction.

</details>

<details>

<summary>What is POST /transfer?</summary>

A Private→Private transaction.

</details>

<details>

<summary>What is POST /swap?</summary>

A private swap transaction.

</details>

<details>

<summary>What is POST /proofless-deposit?</summary>

A deposit flow that does not require proof generation.

</details>

<details>

<summary>What is POST /deposit-for-other?</summary>

Deposits funds for another account.

</details>

<details>

<summary>What is POST /deposit-solana-for-other?</summary>

The Solana version of deposit-for-other.

</details>

<details>

<summary>What is POST /withdraw-stuck-utxos?</summary>

Withdraws inaccessible UTXOs.

</details>

<details>

<summary>Can I execute deposits?</summary>

Yes.

</details>

<details>

<summary>Can I execute withdrawals?</summary>

Yes.

</details>

<details>

<summary>Can I execute transfers?</summary>

Yes.

</details>

<details>

<summary>Can I execute swaps?</summary>

Yes.

</details>

<details>

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

Yes.

</details>

<details>

<summary>Does the API return unsigned transactions?</summary>

Yes.

</details>

<details>

<summary>Can I sign transactions myself?</summary>

Yes.

</details>

<details>

<summary>Can I broadcast transactions myself?</summary>

Yes.

</details>

<details>

<summary>Does Hinkal provide relaying?</summary>

Yes.

</details>

<details>

<summary>What is a relayer?</summary>

A service that executes and broadcasts transactions.

</details>

<details>

<summary>Why use a relayer?</summary>

To simplify transaction execution and improve user experience.

</details>

<details>

<summary>Are relayer fees charged?</summary>

Yes.

</details>

<details>

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

A confidential payout mechanism.

</details>

<details>

<summary>What is POST /private-send?</summary>

Creates a private payout order.

</details>

<details>

<summary>What is orderId?</summary>

A unique controlling identifier.

</details>

<details>

<summary>How do I control an order?</summary>

Using GET /private-send/{orderId}.

</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>What statuses are available?</summary>

PENDING, EXCHANGING, SUCCESSFUL, FAILED, and EXPIRED.

</details>

<details>

<summary>What does PENDING mean?</summary>

The order exists but the deposit has not been detected.

</details>

<details>

<summary>What does EXCHANGING mean?</summary>

The deposit was detected and payouts are being processed.

</details>

<details>

<summary>What does SUCCESSFUL mean?</summary>

The transaction completed successfully.

</details>

<details>

<summary>What does FAILED mean?</summary>

Execution failed.

</details>

<details>

<summary>What does EXPIRED mean?</summary>

The deposit was not received before expiration.

</details>

<details>

<summary>Can I monitor payout progress?</summary>

Yes.

</details>

<details>

<summary>What is attestation?</summary>

A cryptographic proof of enclave integrity.

</details>

<details>

<summary>Which endpoint provides attestation?</summary>

GET /attestation.

</details>

<details>

<summary>Why is attestation important?</summary>

It proves the enclave is running the expected code.

</details>

<details>

<summary>What is imageDigest?</summary>

The hash of the running enclave image.

</details>

<details>

<summary>What is verificationPublicKey?</summary>

A public key generated inside the enclave.

</details>

<details>

<summary>What is x-hinkal-response-signature?</summary>

A signature proving a response came from the enclave.

</details>

<details>

<summary>Can I verify API responses?</summary>

Yes.

</details>

<details>

<summary>Can I verify enclave integrity?</summary>

Yes.

</details>

<details>

<summary>Do I need attestation for every request?</summary>

No.

</details>

<details>

<summary>When should I refresh attestation?</summary>

When response verification fails.

</details>

<details>

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

Authentication failed.

</details>

<details>

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

Authorization failed.

</details>

<details>

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

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

</details>

<details>

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

Possible reasons include network congestion, insufficient funds, or processing delays.

</details>

<details>

<summary>Why is my Private Send still pending?</summary>

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

</details>

<details>

<summary>Why did my order expire?</summary>

The required deposit was not received before the expiration deadline.

</details>

<details>

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

Provide chain ID, wallet address, endpoint used, request payload, response payload, error message, transaction hash, order ID (if applicable), and timestamp.

</details>