Jupiter swap
Jupiter swap: Execution and Balance Reconciliation
Jupiter swap completion requires a successful transaction and an output balance change that matches the exchange. Reconcile the actual input, received tokens, and separate charges against that transaction's record. A quote describes proposed terms; a signature identifies the transaction, while a wallet's displayed portfolio value answers a different question.
Pool quotes and market-maker quotes before execution
Jupiter obtains exchange quotes through onchain liquidity routing and requests for quotes from market makers. Pool routes calculate an output using available liquidity; market makers return terms for the requested exchange. Both provide a starting point for reconciliation, but the original quote isn't a receipt. Preserve the selected input and output mint addresses, input amount, quoted receipt, and applicable minimum output alongside the order.
A usable price also needs an executable transaction. Jupiter's order response can contain a quote even when transaction construction fails, with an error explaining the obstruction. Resolve insufficient funds or unmet account requirements before signing. If those conditions require a new order, its terms become the relevant comparison. Combining the first quote with a later transaction can create an apparent discrepancy that never existed within either order.
Does a transaction signature prove that the swap completed?
A transaction signature identifies the signed transaction; it doesn't establish successful execution or delivery of the output.
The execution record must establish both success and confirmation status. A successful Solana transaction has a null execution-error field in its transaction metadata. The confirmation level describes how firmly the network has accepted that record. A processed result and a finalized result don't express the same degree of settlement. Keep the confirmation level with the amounts when another action depends on completion.
Jupiter's managed execution response distinguishes success from failure and can return a signature for either outcome. An application therefore needs to inspect the result, rather than treating the presence of a signature as its success condition.
A missing response leaves the outcome unresolved. It doesn't authorize another exchange. Successful execution with mismatched balances calls for reconciliation; an unresolved signature calls for status checking. Those situations require different responses even if the wallet presents both as an unfinished swap.
The signed order and its execution response
Jupiter's managed execution connects the signed transaction to its originating order through a request identifier. Retaining that association prevents a refreshed quote from replacing the terms of an already submitted exchange. The execution response includes actual input and output amounts when available, alongside status and error information. Its total output field describes the receipt after fees collected in the output token, so subtracting the same included fee again would understate the receipt. For custom transactions, retain the submitted signature and inspect the resulting transaction directly. A timeout in either path leaves the outcome unresolved until transaction-status and expiration checks establish what happened.
Destination accounts and transaction balance changes
Reconciliation starts with the intended receiving account and token mint, rather than a wallet's combined holdings. Solana transaction metadata can include token balances before and after execution. Match the relevant account entries, then subtract the earlier quantity from the later quantity. Use the token's recorded decimals consistently. Comparing a raw integer amount with a formatted wallet quantity can produce an apparent shortfall even when both represent the same receipt.
Account creation and closure require extra care. An absent earlier entry can reflect an account created during execution, but absence alone doesn't establish a zero balance. Inspect the account instructions before making that interpretation. Similarly, intermediate accounts can receive and forward tokens within one transaction. Their movements aren't additional receipts for the wallet. If the receiving account or ownership doesn't match the intended destination, leave the discrepancy unresolved instead of assigning an unrelated balance increase to the swap.
Network charges and account funding
Swap output and the wallet's native-token balance measure different parts of the exchange. A Solana transaction fee includes a base fee and any prioritization fee. The transaction identifies its fee payer, which can differ from the person exchanging tokens. Jupiter's order data also distinguishes payers for signature fees, prioritization costs, and account rent. Attribute a debit to the account that actually paid it; don't assume every displayed expense reduced the same wallet.
Creating a token account can require a rent-exempt balance, while closing an eligible account returns its remaining lamports to a destination. These movements affect reconciliation without representing an exchange price. Keep account funding, returned balances, network fees, and any separate tips distinct. A quoted cost is an estimate or proposed term; the executed instructions and balance changes establish the actual movements. Where a charge already reduces the reported net token receipt, record its treatment without deducting it twice.
A completed exchange with a delayed wallet display
Consider a hypothetical exchange with every amount and account condition assumed for illustration. The selected input is 73.28 input tokens, the quote offers 41.24 output tokens, and the minimum receipt is 41.06. The existing destination account holds 5.27 output tokens. Assume no token transfer fee, no unrelated output movement, and network charges paid separately from the output tokens.
Before signing, the reader accepts the minimum receipt and checks that the available balances cover the exchange and applicable charges. After submission, the transaction reaches finalized status without an execution error. Its records show 73.28 input tokens consumed and a destination balance of 46.45 output tokens.
The receipt is 46.45 minus 5.27, or 41.18 output tokens. That clears the minimum by 0.12 tokens and falls 0.06 tokens below the quote. The reader records 41.18 as the received amount and accounts for the separately paid charges. The exchange is complete even if the wallet temporarily continues displaying the earlier balance.
In the edge case, the same submitted exchange has no resolved transaction status. An unchanged wallet display then proves neither failure nor success. The reader stops before signing a replacement and checks the original signature. A successful record leads back to balance reconciliation; confirmed failure or verified expiration without execution permits consideration of a fresh order. Different input amounts, route terms, or charges would change the accounting, so the example establishes no fixed cost or promised receipt.
When is a replacement swap justified?
A replacement swap is justified only after the original attempt can no longer execute and hasn't completed successfully.
For a transaction using a recent blockhash, expiration follows that blockhash's validity, rather than the duration of a loading indicator. Check the relevant validity boundary together with transaction history. A transaction lookup can return no result because it hasn't reached the requested confirmation level or the queried node can't find it. That response alone doesn't prove expiration. If an onchain record establishes failure, examine its error before requesting new terms. Repeating an unresolved exchange with a newly signed transaction risks executing both attempts.
Rebroadcasting the same signed transaction differs from authorizing a replacement transaction. Keep that distinction in application records and support requests. A new quote, signature, or order identifier shouldn't silently overwrite the attempt whose outcome remains unknown.
Received quantities and portfolio valuations
Token quantities establish what the exchange delivered; portfolio valuations apply a price to those holdings. A changing valuation doesn't, by itself, identify a missing transfer or an execution fee. Reconcile each asset in its own units first, including the native token when the wallet pays network charges. Only then apply any valuation used for reporting, with its own price and time basis.
A transaction record preserves the exchange's balance changes even after later activity changes the wallet again. Comparing those recorded quantities resolves the original exchange more precisely than comparing portfolio screenshots taken at different times. The screenshot can describe what the application displayed; the transaction establishes which accounts changed and by how much.
Frequently asked questions about Jupiter swap
Which timestamp should I retain when recording a completed Jupiter swap?
Retain the transaction signature and slot, plus the block time when available. The block time is an estimated production timestamp and can be absent. Keep any quote timestamp separately, because it describes the proposed terms rather than the moment the network recorded the exchange.
Why can't a recent-status lookup find an older swap?
A recent-status lookup searches a limited cache unless transaction-history searching is enabled. For an older signature, the RPC request may need the searchTransactionHistory option and a provider that retains the relevant history. A missing cache entry doesn't reverse a completed exchange or establish that it failed.
Does automatic gas coverage mean the exchange has no gas-related cost?
Automatic gas coverage can shift the cost into the swap's token output. When Jupiter's automatic sponsorship applies, it can recover gas costs through an increased swap fee and a lower receipt. Other payer arrangements have different terms, so identify the actual arrangement before attributing the cost.
How should wrapped SOL affect the reconciliation?
Wrapped SOL requires accounting for both its token account and the native SOL destination. Closing a wrapped SOL account releases its underlying SOL, so the token account's closure can accompany a native balance increase. Separate that release from returned account funding and network charges to avoid counting the same value twice.
Is adding every swap event a reliable way to calculate the received amount?
Adding every swap event can count intermediate movements as though they were final receipts. Route events can describe exchanges between different tokens, whose quantities aren't directly additive. Use the final destination's balance change and the execution result, then inspect individual events to explain the route.
What does a transaction response with missing metadata establish?
A transaction response with missing metadata doesn't provide enough detail to reconcile fees and token balance changes. Preserve the signature and retrieve the execution details through a provider that can return them. Missing metadata is a limit of that response, rather than evidence of a zero receipt.