Skip to main content

​
Overview

Some tokens have no direct private route. For these tokens we can still offer a private swap: the swap runs privately to a hub token (for example USDC), then an on-chain hop takes the hub token to the token your user wants.
Coverage: With this feature, almost any token on Solana and on high-volume EVM chains, such as Ethereum, Base, Robinhood, Arbitrum, BNB Chain, Polygon, Optimism, Avalanche and more, can be the output of a private swap.

​
How the route works

The on-chain hop is an extra leg added after a normal private swap. The private part is unchanged:
  1. Private leg: the deposit goes through the same multi-hop private routing as any private swap, and comes out as the hub token. This is what breaks the link between your user’s deposit and the output.
  2. On-chain hop: the hub token is swapped on-chain into the destination token and sent to addressTo.
The swap stays private. The on-chain hop starts only after the private leg has finished, so the user’s deposit is never linked to it. This route needs one extra field when you create the exchange: intermediateRefundAddress.
Add support for intermediateRefundAddress before you turn the feature on. If you turn it on first, your users will get quotes that you cannot turn into orders.

​
How it fits in

This is an option on the Private Swap flow, not a separate flow. Fetching tokens, sending the deposit and polling status are unchanged. Only these things differ:

​
When you get this route

All of these must be true:
  • The feature is turned on for your account.
  • The quote is private (types=private).
  • The quote is floating rate, not fixed.
  • The amount is the send amount (amountType=send), not the receive amount.
  • No direct private route exists to the destination token.
When a token has a direct route, you get the normal private quote, as before.

​
Turn it on

To turn on Private routes with on-chain hop for your account, contact your Houdini representative and we will turn it on for you. To check the setting, call Get partner profile (GET /me) and read privateOnchainLegEnabled.

​
Limits

This route has its own amount limits, and they are lower than for a normal private swap. When the destination token can only be reached through this route, an amount outside the limits returns an error instead of an empty quotes array:
  • 422 QUOTE_OVER_LIMIT when the amount is too high
  • 422 AMOUNT_TOO_LOW when the amount is too low
The error message gives the allowed range. The same limits are checked again when you create the exchange.

​
Spot the route in a quote

A quote for this route has these extra fields: Check requiresIntermediateRefundAddress on every private quote. When it is true, ask your user for a wallet on intermediateRefundChain before they confirm the swap.

​
Create the exchange

Send the quote’s quoteId as usual, plus intermediateRefundAddress:
Rules for intermediateRefundAddress:
  • It must be a valid address on intermediateRefundChain.
  • It must be able to receive intermediateRefundToken.
  • Use a wallet your user controls, not an exchange deposit address.

​
Two refund addresses

​
Error Codes

These errors are not retried on another route. Fix the request or get a new quote.

​
Next Steps

Private Swap

The base private swap flow

Order Lifecycle

Understand all order statuses

Error Codes

Full list of API errors

Fixed Rate & Reverse Quote

Lock the rate or set the receive amount