Guides

Swap on Jupiter

jupiter.swap swaps one asset in your private balance for another at the route Jupiter finds. Any pair Jupiter routes works, as long as Solana Privacy Rings holds both assets. This guide covers the quote, slippage, the fees, and what to do when a swap does not go through.

You need a private balance holding the asset you are swapping from. Enter and leave covers getting one.

Swap

  1. Open the hook

    On Balance, under Run a hook, press Swap. Or open jupiter.swap in the registry and press Run.

  2. Fill the form

    Choose the asset in, type the amount, choose the asset out, and set Slippage. The amount cannot be more than your private balance holds of that asset.

  3. Read the quote

    The quote refreshes as you type. It shows what you receive, the Expected out, the Minimum out, the run fee, the relayer's fee and the Route. If Jupiter has no path for the pair and amount, the panel reads No route.

  4. Run

    Press Run. The stages are Making the proofs, Relayed and Confirmed. At Done the result is in your balance.

SOL and wrapped SOL

Name SOL by the wrapped SOL mint, So11111111111111111111111111111111111111112, on either side of the swap. Your private balance holds native SOL. The hook wraps it on the way into Jupiter and unwraps what comes out, inside the run.

Slippage and the minimum out

slippageBps is in basis points: 50 is 0.5%, and that is the default. The quote turns it into minimumOut, an exact amount in the asset out.

The minimum out is part of your proof. After the call to Jupiter, the Pook program measures what arrived and fails the run if it is less. A swap that would give you less than the minimum does not happen.

The fees

Two amounts come off what the swap returns, both in the asset out: the run fee and the relayer's fee. The quote lists them, and netOut is the result after both. Fees and POOK explains how each is worked out and where it goes.

The run fails if the result is not larger than the fees taken from it. Very small swaps meet this first.

When a swap does not go through

A run is one transaction. If it fails at any point, no note is spent and your balance is as it was.

What you seeWhyWhat to do
No route, or the error code NO_ROUTEJupiter has no path for this pair and amount.Try another amount or another asset out.
UPSTREAM_UNAVAILABLEJupiter could not be reached for a quote.Try again in a moment.
INSUFFICIENT_BALANCEThe amount is more than one or two of your notes of the asset in hold together.Swap less, or see the note below.
SlippageExceededThe price moved past your minimum out between the quote and the run.Run again for a fresh quote, or raise the slippage.
OutputBelowFeesThe result is not larger than the fees.Swap a larger amount.
The proof expired before it landedThe run reached the chain after expiresAt.Run again. Nothing was spent.

A run spends up to two notes. If your balance of an asset is spread over more notes than that, swap what two of them hold, and the change and the result come back as fresh notes.

In the SDK, pook.run throws an ApiClientError when the quote or the relayer refuses, and returns relay.status of failed or expired with relay.error when the transaction itself did. Call a hook from your app shows both.

What the chain shows

The run's transaction shows the hook, the route's pools, the amount in, what Jupiter returned, the fees and the relayer. It does not show your wallet or what you hold. What the chain shows lists every field.