> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravn.exchange/llms.txt
> Use this file to discover all available pages before exploring further.

# Private swaps

> Swaps whose deposit and payout aren't directly linked on-chain.

Set `confidential: true` on [`/quote`](https://docs.ravn.exchange/api-reference/quote). The race narrows to venues with a
private settlement path, and the best output wins. If none can quote, you get `404 NO_LIQUIDITY`,
never a public fill.

| Venue | Cost vs a public swap | Speed | Notes |
| - | - | - | - |
| NEAR Intents (Confidential Intents) | About 0.3 bps more EVM to EVM, 5 to 8 bps when Bitcoin or Solana is a leg | Like a public swap | The cheapest. Any to any |
| Houdini Swap | About 3% below spot | Minutes to an hour | Settles through two partner exchanges, which hold the funds meanwhile. About \$25 minimum |
| Hinkal | About 0.3 to 0.45% less than NEAR | Seconds after the deposit, plus the bridge | Opt-in, EVM chains only. [See below](#hinkal) |

Each hides the direct link between deposit and payout; how strongly depends on the venue. Your
integrator fee applies, [paid beside the swap](https://docs.ravn.exchange/collecting-your-fee.md). Read `estimatedTimeSeconds`
before executing.

## Compliance

* **Houdini Swap** receives your request's IP and user agent, plus `clientTimezone` (your user's
  IANA timezone, default `UTC`). Its terms bar US persons and sanctioned jurisdictions.
* **Hinkal**'s terms bar Cuba, Iran, North Korea, Syria, and Crimea, Sevastopol, Donetsk and
  Luhansk.

RAVN leaves a venue out when your request comes from a barred country. You are responsible for your
end users' eligibility: pass `excludeVenues: ["houdini"]` or `["hinkal"]` where you can't meet it.

## Hinkal

Your user pays into Hinkal's shared pool, and Hinkal pays the recipient from a fresh wallet through
LI.FI, so the payout can arrive in another token or on another chain. LI.FI's 0.25% and Hinkal's
0.10% plus a small flat fee come out of the quoted output. The deposit itself is heavy (450k to 670k
gas), paid by the user's wallet and shown in the quote's `gas`.

**Limits**

* Races only when the quote has `authorizeSteps: true` (or `onlyVenues` naming `hinkal`), so a flow
  that can't collect the signatures below never gets a Hinkal quote.
* From Ethereum, Base, Arbitrum, Polygon, BNB Chain or Robinhood Chain. Pays out on any of those,
  plus Solana, Arc, Tempo, Avalanche, Monad and HyperEVM.
* Any token Hinkal's pool takes, except stETH and PAXG. Up to \$10,000 a swap.
* Needs `destinationAddress` on the quote, or the quote is only a preview. Takes no `refundAddress`
  other than `userAddress`.
* Up to 12 swaps an hour per IP, or 120 per API key. Past that, `/execute` answers
  `502 BUILD_FAILED`. Send your key.
* Not available through the [MCP server](https://docs.ravn.exchange/ai-agents/mcp-server.md) or [x402](https://docs.ravn.exchange/ai-agents/x402-payments.md).

**Privacy is thinner than NEAR's.** Hinkal has few users, and the payout follows the deposit by
seconds for about the same amount, so timing can still link the two wallets. Hinkal screens
depositors, and a flagged depositor's funds can only go back, publicly, to the wallet that paid.
RAVN keeps the order encrypted for 7 days to track and recover it. Tell your users it hides the
direct link, never that it's untraceable.

### AUTHORIZE steps

Before Hinkal's swap is built, the paying wallet (`userAddress`) signs twice. `/execute` asks for
each signature with an `AUTHORIZE` answer:

```json theme={null}
{
  "executionType": "AUTHORIZE",
  "quoteToken": "…",
  "authorization": "hk_…",
  "sign": { "method": "personal_sign", "message": "Authorize Hinkal session\nSession ID: …\nPublic Key: …" },
  "expiresAt": "2026-10-22T12:09:00.000Z",
  "step": 1,
  "steps": 2
}
```

Have the wallet sign `sign`, then call `/execute` again with the same `quoteToken`, this
`authorization` and the `signature`, before `expiresAt`, with a **new** `Idempotency-Key`. Repeat
until a `TRANSACTION` comes back. Signing moves no funds. Check each step before your user signs:

1. **`personal_sign`**: opens a read-only session. The message must be exactly the three lines
   above. Refuse one that adds `This signature can also be used to submit transactions.`: that mode's
   key could move the wallet's funds.
2. **`eth_signTypedData_v4`**: Hinkal's `PrivateSendBridge` order, signed on the input chain. Its
   domain is only `{ name: "Hinkal Enclave", chainId }`, it's for the input token (the zero address
   for the chain's coin) and at most the input amount, and `recipients` holds exactly one entry: your
   `destinationAddress`.
3. **The `TRANSACTION`**: the approval on a token sell, then `prooflessDeposit` on
   `0x7cb60446d7635C68EDf1c568cac74A1f98c1Cfa4` (the same address on every chain), your fee when
   one applies, and a `statusRef`. Send its `calls` one by one.

> [!WARNING]
>
> **Send the deposit within 10 minutes of receiving the second `AUTHORIZE`.** Hinkal prices its route
> then, and a later deposit is likely to fail at the bridge. The `TRANSACTION` carries no deadline, so
> note the time yourself. Have the wallet sign step 2 within about 6 minutes: with under 4 of them
> left, the order is refused (`400 INVALID_REQUEST`) and you start again from `/execute`.

On JavaScript or TypeScript, [`executeAndTrack`](https://docs.ravn.exchange/sdks/core#executeandtrack) checks and signs both
steps, then sends the deposit. In Python, [`check_authorize`](https://docs.ravn.exchange/sdks/python#execute) checks each
step. A [sandbox](https://docs.ravn.exchange/sandbox-mode.md) quote skips the steps.

### When a Hinkal swap fails

A failed payout is **not refunded on its own**. `/status` reports `failed` (never `refunded`), with
`venueStatus` ending `(needs recovery)`, and the funds wait at Hinkal on the source chain. The
paying wallet gets them back with [`POST /recover`](https://docs.ravn.exchange/api-reference/recover), within 7 days. After 7
days RAVN no longer holds the swap and its status reads `unknown`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.