Privy

Privy lets your users sign in the way they already do -email, social login, passkey, or an existing wallet - and gives each one a secure, self-custodial embedded wallet with no seed phrase to manage. Because Hinkal only needs a standard signer to operate, a Privy wallet plugs in directly: the same wallet a user signs in with can hold a private, shielded balance and run confidential deposits, withdrawals, transfers, swaps, and private sends.

Privy's role is unchanged. It authenticates the user, manages the embedded wallet, and produces signatures. Hinkal uses those signatures to authorize private operations and never takes custody of the wallet.

Compatibility

Environment	Supported	Notes
Browser	✅	React, Next.js
Library	✅	@privy-io/react-auth v3

How the integration works

Three parties are involved:

• The user's Privy wallet - produces every signature. Nothing executes without one.

• The Hinkal API - an HTTP service running inside a secure enclave. It decrypts the user's shielded balance, generates the zero-knowledge proofs, and builds the on-chain transactions. The wallet's private key never reaches it.

• The relayer - broadcasts private transactions, so the user's public wallet is never the on-chain sender of a confidential operation.

Installation

npm install @privy-io/react-auth ethers

yarn add @privy-io/react-auth ethers

1. Get a signer from Privy

Every Hinkal request is authorized by the user's wallet, so the first step is to obtain an ethers.Signer from their Privy embedded wallet.

import { useWallets } from "@privy-io/react-auth";
import { ethers } from "ethers";

const { wallets } = useWallets();
const embedded = wallets.find((w) => w.walletClientType === "privy");

const account = embedded.address;                       // user's EVM address
const chainId = Number(embedded.chainId.split(":")[1]); // "eip155:1" -> 1

const provider = await embedded.getEthereumProvider();  // EIP-1193 provider
const signer = await new ethers.BrowserProvider(provider).getSigner();

embedded.getEthereumProvider() returns the wallet's EIP-1193 provider; wrapping it in an ethers BrowserProvider yields a Signer. From here, every Hinkal call is identical to any other wallet.

2. How requests are authorized

Hinkal authorizes requests with two kinds of signature, both produced by the Privy wallet. The enclave reconstructs the same data and verifies the signature server-side before doing anything.

Read signature (sessions and getters)

Read-only endpoints - fetching the shielded balance, getting fee structures, quoting a swap - use a personal-message signature. The signed message is exactly:

Authorize Hinkal session
Session ID: <nonce>

const nonce = crypto.randomUUID();
const signature = await signer.signMessage(
  `Authorize Hinkal session\nSession ID: ${nonce}`,
);

Transaction signature (EIP-712 typed data)

Each transaction is authorized with an EIP-712 typed-data signature that commits to the exact operation. The enclave rebuilds the identical structure and verifies it, so the user approves precisely what will execute.

The domain is:

const domain = { name: "Hinkal Enclave", chainId };

Each operation has its own primary type. The full set:

const types = {
  TokenAmount: [
    { name: "token",  type: "address" },
    { name: "amount", type: "int256"  },
  ],
  Deposit: [
    { name: "nonce",        type: "string"        },
    { name: "chainId",      type: "uint256"       },
    { name: "tokenAmounts", type: "TokenAmount[]" },
  ],
  Withdraw: [
    { name: "nonce",        type: "string"        },
    { name: "chainId",      type: "uint256"       },
    { name: "tokenAmounts", type: "TokenAmount[]" },
    { name: "recipient",    type: "string"        },
  ],
  Transfer: [
    { name: "nonce",        type: "string"        },
    { name: "chainId",      type: "uint256"       },
    { name: "tokenAmounts", type: "TokenAmount[]" },
    { name: "recipient",    type: "string"        },
  ],
  Swap: [
    { name: "nonce",        type: "string"        },
    { name: "chainId",      type: "uint256"       },
    { name: "tokenAmounts", type: "TokenAmount[]" },
  ],
};

When signing, include only the primary type you are using plus the types it references. A deposit, for example:

const nonce = crypto.randomUUID();
const signature = await signer.signTypedData(
  { name: "Hinkal Enclave", chainId },
  {
    Deposit:     types.Deposit,
    TokenAmount: types.TokenAmount,
  },
  { nonce, chainId, tokenAmounts: [{ token, amount }] },
);

Two rules the enclave enforces - the signature must match exactly:

• Sort tokenAmounts by token address (checksummed, ascending) before signing. The enclave re-sorts before verifying; an unsorted array produces a non-matching signature.

• The nonce is single-use and expires after 60 seconds. Generate a fresh UUID for every signed request; a reused or expired nonce is rejected server-side.

Write session (sign once for 24 hours)

If you open a write session, the user signs the session message once with an extra third line:

Authorize Hinkal session
Session ID: <nonce>
This signature can also be used to submit transactions.

That single signature authorizes every transaction for 24 hours - the per-transaction typed-data signature is skipped. Without a write session, each transaction is signed individually as shown above.

3. Read the shielded balance

The shielded balance is the user's private, encrypted holdings. Reading it uses a read signature passed as query parameters:

const params = new URLSearchParams({
  address:   account,
  chainId:   String(chainId),
  signature,
  nonce,
});
const res = await fetch(`https://api.hinkal.io/balance?${params}`);
const { balances } = await res.json(); // { success: true, balances: [...] }

The enclave decrypts the user's shielded outputs internally and returns the balances.

4. Shield - deposit (public → private)

A deposit moves funds from the user's public Privy wallet into their shielded balance.

1. The wallet signs the Deposit typed data (or a write session is reused).

2. POST /deposit with the signature and details.

3. The enclave returns an unsigned transaction (txData).

4. The user's wallet signs and broadcasts it - a deposit is the public on-ramp into privacy, sent from the user's own address.

const res = await fetch("https://api.hinkal.io/deposit", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    signature,
    nonce,
    address:        account,
    chainId,
    tokenAddresses, // string[] — same order as amounts
    amounts,        // string[] — token base units
  }),
});
const { txData } = await res.json(); // { success: true, txData: { to, data, value? } }

// User broadcasts with their Privy wallet
const tx = await signer.sendTransaction(txData);
await tx.wait();

After confirmation, the funds are in the user's shielded balance.

5. Unshield - withdraw (private → public)

A withdrawal sends funds from the shielded balance to any public address. The user does not broadcast it: the enclave builds and proves the transaction and the relayer broadcasts it, so the user's wallet is never the on-chain sender.

1. The wallet signs the Withdraw typed data (or a write session is reused).

2. POST /withdraw.

3. The response is the resulting txHash.

const res = await fetch("https://api.hinkal.io/withdraw", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    signature,
    nonce,
    address:          account,
    chainId,
    tokenAddresses,
    amounts,          // positive values; the enclave negates them internally
    recipientAddress, // public address receiving the funds
    feeToken,         // token used to pay the relayer fee
    feeStructure,     // from GET /get-fee-structure
  }),
});
const { txHash } = await res.json(); // { success: true, txHash }

6. Transfer (private → private)

A transfer moves funds from the user's shielded balance to another user's shielded balance. Both sides stay private - there is no public on-chain link between sender and recipient, and the amount is not visible. The user does not broadcast it: the enclave proves the transaction and the relayer broadcasts it.

The recipient is identified by their recipient info - a private identifier the recipient obtains from GET /recipient-info(authorized by their own session signature) and shares with the sender. It is not a public address.

// The recipient fetches their own recipient info and shares it with the sender:
const params = new URLSearchParams({
  address: recipientAccount, chainId: String(chainId), signature, nonce,
});
const { recipientInfo } = await (
  await fetch(`https://api.hinkal.io/recipient-info?${params}`)
).json();

The sender then signs the Transfer typed data and submits:

const res = await fetch("https://api.hinkal.io/transfer", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    signature,
    nonce,
    address:          account,
    chainId,
    tokenAddresses,
    amounts,          // positive values; the enclave negates them internally
    recipientAddress, // the recipient's recipientInfo string
    feeToken,         // token used to pay the relayer fee
    feeStructure,     // from GET /get-fee-structure
  }),
});
const { txHash } = await res.json(); // { success: true, txHash }

The enclave proves and the relayer broadcasts.

7. Swap (within the shielded balance)

A swap exchanges one token for another inside the shielded balance. It is a two-call flow: first fetch a quote, then execute.

// 1. Quote — read signature
const quoteParams = new URLSearchParams({
  signature, nonce, address: account, chainId: String(chainId),
  inputTokenAddress, outputTokenAddress, amount,
});
const quote = await (
  await fetch(`https://api.hinkal.io/get-swap-data?${quoteParams}`)
).json();
// quote: { externalActionId, swapData, outSwapAmount }

// 2. Execute — Swap typed-data signature (or write session)
const res = await fetch("https://api.hinkal.io/swap", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    signature,
    nonce,
    address:          account,
    chainId,
    tokenAddresses,   // [inputToken, outputToken]
    amounts,          // [inputAmount (negative), expectedOutputAmount (positive, after Hinkal fee)]
    externalActionId: quote.externalActionId,
    swapData:         quote.swapData,
    feeToken,
    feeStructure,
  }),
});
const { txHash } = await res.json();

As with withdrawals and transfers, the enclave proves and the relayer broadcasts.

8. Private send (one deposit → many private payouts)

A private send deposits public funds once and has the enclave pay out privately to one or more recipients - the on-chain link between sender and recipients is never visible.

1. POST /private-send with the token, recipients, and amounts → returns an order (orderId, approvalAddress, serializedTx, amountIn, amountOut, fee).

2. Approve the ERC20 spend if approvalAddress is set.

3. Sign and broadcast the deposit with the user's Privy wallet.

4. Poll GET /private-send/{orderId} until every scheduled payout completes.

// 1. Prepare the order (write session or per-transaction signature)
const res = await fetch("https://api.hinkal.io/private-send", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    signature,
    nonce,
    address:      account,
    chainId,
    tokenAddress,        // single token
    recipients,          // [{ address, amount }, ...] amounts in base units
    feeToken,            // optional — defaults to tokenAddress
    // txCompletionTime, // optional Unix-seconds deadline
  }),
});
const order = await res.json();
// { orderId, approvalAddress, serializedTx, amountIn, amountOut, fee }

// 2. Approve if required (EVM)
if (order.approvalAddress) {
  const token = new ethers.Contract(tokenAddress, ERC20_ABI, signer);
  await (await token.approve(order.approvalAddress, BigInt(order.amountIn))).wait();
}

// 3. Broadcast the deposit with the Privy wallet
const tx = ethers.Transaction.from(
  "0x" + Buffer.from(order.serializedTx, "base64").toString("hex"),
);
tx.nonce = await signer.provider.getTransactionCount(account, "pending");
const depositHash = await signer.provider.send(
  "eth_sendRawTransaction",
  [await signer.signTransaction(tx)],
);

// 4. Poll until all payouts settle
const result = await pollOrder(order.orderId); // GET /private-send/{orderId}

amountIn is what leaves the wallet; amountOut is what recipients collectively receive; the difference is the protocol fee. Amounts are in the token's smallest unit. The user broadcasts the single deposit; the enclave then proves and the relayer broadcasts each private payout.

Summary

Operation	Endpoint	Signature	Who broadcasts
Read balance	GET /balance	Read (message)	—
Deposit (shield)	POST /deposit	Deposit typed data	The user's wallet
Withdraw (unshield)	POST /withdraw	Withdraw typed data	Relayer
Transfer (private → private)	POST /transfer	Transfer typed data	Relayer
Swap	GET /get-swap-data + POST /swap	Swap typed data	Relayer
Private send	POST /private-send + poll	session or per-tx	User (deposit) + relayer (payouts)