> 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/description/overview.md).

# Overview

The API is Hinkal's privacy protocol exposed as a REST API. It is a normal HTTPS API with one defining property: **the server runs inside a secure enclave**. Every request is handled by code executing inside a GCP Confidential VM (AMD SEV), whose memory is encrypted at the hardware level and inaccessible to the host - including Google and Hinkal's own infrastructure.

Think of it as "an API, but the compute is the enclave."

## Supported chains

The API supports three chain families:

| Chain          |                         Chain ID | Notes                                                                                                     |
| -------------- | -------------------------------: | --------------------------------------------------------------------------------------------------------- |
| EVM chains     | Standard IDs (e.g. 1 = Ethereum) | Full feature set                                                                                          |
| Solana mainnet |                              501 | Per-operation signing differences; see [Authentication](/hinkal/hinkal-api/description/authentication.md) |
| TRON           |                        728126428 | TIP-712 typed-data signing (EIP-712 compatible)                                                           |

## What it does

Hinkal lets users hold a **private balance** - funds whose ownership and movement are not visible on the public ledger. Working with that private balance requires:

* decrypting the user's UTXOs (unspent shielded outputs),
* generating zero-knowledge proofs that authorize spends without revealing them,
* building the resulting on-chain transactions.

The API performs all of this **inside the enclave** and hands back either an unsigned transaction for the caller to broadcast, or a relayed transaction hash.

## What never leaves the enclave

Each shielded balance is controlled by a **shielded key**. This key decrypts the user's UTXOs and authorizes their zero-knowledge proofs. It is:

* generated inside the enclave,
* stored encrypted outside the enclave - encrypted with a key held in **Google Cloud KMS**, which the enclave alone is authorized to use,
* decrypted and used **only inside the enclave**. When a request needs to read the user's private balance or build a proof, the enclave decrypts the shielded key in memory, uses it for that single operation, and discards it - all within the enclave boundary. The decrypted key is never persisted and never returned in a response.

No component outside the enclave - not the API host, not the database, not Hinkal engineers - ever sees a raw shielded key.

## You keep your own wallet

The API is **not** a custodial wallet. The caller keeps their own wallet (EVM, Solana, or TRON) and uses it to authenticate requests. The enclave manages only the shielded key that operates the privacy layer - never the caller's key.

## Request model

* **Base URL**: `https://api.hinkal.io`
* **Response envelope**: `{ "success": true, ... }` on success, `{ "success": false, "error": "..." }` on failure.
* **Authentication**: every request requires an active session and a secp256k1 payload signature (`x-hinkal-request-signature`). Sessions have two modes: **normal mode** (payload signature covers all requests) and **EIP-712 mode** (transaction endpoints additionally require a per-operation typed-data or ed25519 signature that commits to the exact parameters). See [Authentication](/hinkal/hinkal-api/description/authentication.md).

## Endpoint groups

| Group                          | Endpoints                                                                                                                                                                               |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Health                         | `GET /ping`                                                                                                                                                                             |
| Attestation                    | `GET /attestation`                                                                                                                                                                      |
| Sessions                       | `POST /create-session`                                                                                                                                                                  |
| Info                           | `GET /supported-tokens`, `GET /supported-chains`, `GET /contract-addresses`                                                                                                             |
| Reads                          | `GET /balance`, `GET /stuck-utxo-balance`, `GET /recipient-info`, `GET /get-fee`, `GET /get-swap-data`                                                                                  |
| Cache                          | `POST /refresh-cache`                                                                                                                                                                   |
| Transactions (EVM/TRON/Solana) | `POST /deposit`, `POST /proofless-deposit`, `POST /deposit-for-other`, `POST /deposit-solana-for-other`, `POST /withdraw`, `POST /transfer`, `POST /swap`, `POST /withdraw-stuck-utxos` |
| Private Send                   | `POST /private-send`, `GET /private-send/{orderId}`                                                                                                                                     |
| Receive addresses              | `POST /receive-address`, `GET /receive-vault-account`, `POST /receive-vault-recover`                                                                                                    |

See the [Examples](/hinkal/hinkal-api/description/examples.md) for end-to-end code, [Private Send](/hinkal/hinkal-api/description/private-send.md) for the asynchronous private-send flow, and [Attestation](/hinkal/hinkal-api/description/attestation.md) for verifying that the server is running the published code inside a genuine TEE.