FAQ

What is the Hinkal API?

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

Who should use the Hinkal API?

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

When should I use the API instead of the SDK?

Use the API when building server-side integrations.

When should I use the API instead of WaaS?

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

Is the API custodial?

No.

Who controls the user's wallet?

The user.

Does Hinkal access user private keys?

No.

What does Hinkal manage?

Only Hinkal shielded keys used for privacy operations.

Where does the API run?

Inside a secure enclave running on GCP Confidential VMs.

Which chains are supported?

Ethereum, Solana, Tron, and supported EVM chains.

Does the API support Ethereum?

Yes.

Does the API support Solana?

Yes.

Does the API support Tron?

Yes.

Does the API support EVM chains?

Yes.

What operations are supported?

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

How does API authentication work?

Through wallet signatures and authenticated sessions.

What is a session?

A temporary authorization associated with a wallet.

How do I create a session?

Call POST /create-session.

Is a session required?

Yes.

How long does a session last?

24 hours by default.

Can sessions expire?

Yes.

What happens when a session expires?

A new session must be created.

What is clientPublicKey?

A secp256k1 public key used for authentication.

What is x-hinkal-request-signature?

A request authentication signature.

What algorithm is used?

secp256k1.

Does the API support EIP-712?

Yes.

Does the API support Solana signatures?

Yes.

Does the API support Tron signatures?

Yes.

What is Normal Mode?

A mode where sessions authorize requests.

What is EIP-712 Mode?

A mode where transactions require explicit approvals.

Which mode is recommended?

It depends on your security requirements and user experience goals.

Does every request require signing?

Authenticated requests do.

Can I reuse a session?

Yes.

Can multiple requests use the same session?

Yes.

Can I invalidate a session?

By creating a new session or waiting for expiration.

What is GET /ping?

A health-check endpoint.

What is GET /supported-chains?

Returns supported networks.

What is GET /supported-tokens?

Returns supported assets.

What is GET /balance?

Returns balance information.

What is GET /recipient-info?

Returns recipient-related information.

What is GET /get-fee-structure?

Returns fee information.

What is GET /get-swap-data?

Returns swap information.

What is POST /refresh-cache?

Refreshes cached data.

Which endpoint should I call first?

POST /create-session.

How do I retrieve balances?

Using GET /balance.

How do I retrieve supported assets?

Using GET /supported-tokens.

How do I retrieve supported networks?

Using GET /supported-chains.

Does balance retrieval require transactions?

No.

Can I query balances at any time?

Yes.

Does the API support fee estimation?

Yes.

What is POST /deposit?

A Public→Private transaction.

What is POST /withdraw?

A Private→Public transaction.

What is POST /transfer?

A Private→Private transaction.

What is POST /swap?

A private swap transaction.

What is POST /proofless-deposit?

A deposit flow that does not require proof generation.

What is POST /deposit-for-other?

Deposits funds for another account.

What is POST /deposit-solana-for-other?

The Solana version of deposit-for-other.

What is POST /withdraw-stuck-utxos?

Withdraws inaccessible UTXOs.

Can I execute deposits?

Yes.

Can I execute withdrawals?

Yes.

Can I execute transfers?

Yes.

Can I execute swaps?

Yes.

Can I estimate fees before execution?

Yes.

Does the API return unsigned transactions?

Yes.

Can I sign transactions myself?

Yes.

Can I broadcast transactions myself?

Yes.

Does Hinkal provide relaying?

Yes.

What is a relayer?

A service that executes and broadcasts transactions.

Why use a relayer?

To simplify transaction execution and improve user experience.

Are relayer fees charged?

Yes.

What is Private Send?

A confidential payout mechanism.

What is POST /private-send?

Creates a private payout order.

What is orderId?

A unique controlling identifier.

How do I control an order?

Using GET /private-send/{orderId}.

Can I send to multiple recipients?

Yes.

Can I build payroll systems?

Yes.

Can I build treasury systems?

Yes.

What statuses are available?

PENDING, EXCHANGING, SUCCESSFUL, FAILED, and EXPIRED.

What does PENDING mean?

The order exists but the deposit has not been detected.

What does EXCHANGING mean?

The deposit was detected and payouts are being processed.

What does SUCCESSFUL mean?

The transaction completed successfully.

What does FAILED mean?

Execution failed.

What does EXPIRED mean?

The deposit was not received before expiration.

Can I monitor payout progress?

Yes.

What is attestation?

A cryptographic proof of enclave integrity.

Which endpoint provides attestation?

GET /attestation.

Why is attestation important?

It proves the enclave is running the expected code.

What is imageDigest?

The hash of the running enclave image.

What is verificationPublicKey?

A public key generated inside the enclave.

What is x-hinkal-response-signature?

A signature proving a response came from the enclave.

Can I verify API responses?

Yes.

Can I verify enclave integrity?

Yes.

Do I need attestation for every request?

No.

When should I refresh attestation?

When response verification fails.

Why am I getting a 401 error?

Authentication failed.

Why am I getting a 403 error?

Authorization failed.

Why is my balance empty?

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

Why is my transaction stuck?

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

Why is my Private Send still pending?

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

Why did my order expire?

The required deposit was not received before the expiration deadline.

What information should I provide when reporting an API issue?

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