Skip to content

locallaunchsc-cloud/solana-dev-skills / jupiter-swap

solana-jupiter-swap

Verified

Use this skill when the user wants to integrate Jupiter — Solana's leading DEX aggregator — to get quotes and execute swaps with slippage control, priority fees, and versioned transactions.

Jupiter Swap

Overview

Jupiter is the default DEX aggregator on Solana: it routes a single swap across dozens of DEXes (Orca, Raydium, Meteora, Phoenix, etc.) and RFQ market makers to give the user the best price. As of May 2026 the stable HTTP surface is the Swap V1 API at https://api.jup.ag/swap/v1 (requires a free API key from portal.jup.ag) or the keyless mirror at https://lite-api.jup.ag/swap/v1 for low-volume use. A newer Swap V2 unified router (/swap/v2/order, /build, /execute) launched in March 2026 and is the recommended target for new production systems, but V1 is still the most stable, broadly-supported path and what almost every example online uses. This skill covers V1, with a note on the V2 migration.

When to use this skill

  • The user asks "how do I swap tokens on Solana"
  • The user mentions Jupiter, JUP, "DEX aggregator", "best price routing"
  • They want to buy/sell an SPL token from a script, bot, or backend
  • They need to embed swaps inside a larger Solana program flow (e.g. claim → swap → stake)
  • They're hitting slippage / blockhash / priority-fee problems on a swap they already wrote

Skip this skill if the user wants an on-chain CPI call into Jupiter (use Jupiter's IDL + Anchor instead) or only wants a price feed (use /price or Pyth).

Prerequisites

  • Node 20+ (LTS) — node -v should report ≥ 20.x
  • npm i @solana/web3.js@^1.98.4 @jup-ag/api@^6.0.48 (or pin exact versions)
  • A Solana RPC endpoint. The public https://api.mainnet-beta.solana.com is rate-limited and will get you 429s — use a staked-connection RPC (Helius, Triton, QuickNode, Shyft) for anything past hello-world.
  • A funded mainnet keypair (~0.05 SOL minimum for rent + fees on top of the swap amount)
  • For api.jup.ag: a free API key from https://portal.jup.ag. For lite-api.jup.ag: nothing.

Workflow

1. Get a quote — GET /swap/v1/quote

Quote endpoint takes inputMint, outputMint, amount (atomic units of the input mint), and slippageBps (1% = 100 bps).

const QUOTE_HOST = "https://lite-api.jup.ag"; // or "https://api.jup.ag" with x-api-key
const SOL  = "So11111111111111111111111111111111111111112";
const USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";

const qs = new URLSearchParams({
  inputMint: SOL,
  outputMint: USDC,
  amount: String(0.1 * 1e9), // 0.1 SOL in lamports
  slippageBps: "50",         // 0.5%
});
const quote = await fetch(`${QUOTE_HOST}/swap/v1/quote?${qs}`).then(r => r.json());

2. Quote response anatomy

Fields you actually use:

  • inAmount / outAmount — atomic units, both as decimal strings
  • otherAmountThreshold — the floor you'll receive after slippageBps is applied (this is the on-chain guard)
  • priceImpactPct — string like "0.0012" (0.12%). Bail above ~1–2% on a normal pair.
  • routePlan — array of hops. routePlan[i].swapInfo.label tells you which DEX ("Orca (Whirlpools)", "Raydium CLMM", …).
  • contextSlot — slot the quote was priced against. If you delay >~10s before posting, refetch.

3. Get the swap transaction — POST /swap/v1/swap

Send the entire quote object back as quoteResponse. Don't try to reconstruct it.

const swapBody = {
  quoteResponse: quote,
  userPublicKey: wallet.publicKey.toBase58(),
  wrapAndUnwrapSol: true,            // creates/closes the wSOL ATA for you
  dynamicComputeUnitLimit: true,     // simulates to size CU exactly
  dynamicSlippage: true,             // lets Jupiter pick slippage at build time (V1 feature)
  prioritizationFeeLamports: {
    priorityLevelWithMaxLamports: {
      maxLamports: 10_000_000,       // 0.01 SOL cap — adjust per asset
      priorityLevel: "veryHigh",
    },
  },
};
const { swapTransaction } = await fetch(`${QUOTE_HOST}/swap/v1/swap`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(swapBody),
}).then(r => r.json());

4. Sign and send a versioned transaction

Jupiter always returns a v0 VersionedTransaction (it relies on address lookup tables — there is no legacy path that fits the route). Don't try to convert it to a legacy Transaction.

import { VersionedTransaction } from "@solana/web3.js";

const tx = VersionedTransaction.deserialize(Buffer.from(swapTransaction, "base64"));
tx.sign([wallet]);

const sig = await connection.sendRawTransaction(tx.serialize(), {
  skipPreflight: true,    // we already simulated via dynamicComputeUnitLimit
  maxRetries: 0,          // we'll handle retries ourselves
});

5. Confirm and decode logs

Use the same blockhash that's already inside the tx — getLatestBlockhash here is just for the confirmation strategy.

const latest = await connection.getLatestBlockhash("confirmed");
const status = await connection.confirmTransaction(
  { signature: sig, ...latest },
  "confirmed",
);
if (status.value.err) throw new Error(`Swap failed: ${JSON.stringify(status.value.err)}`);
console.log(`https://solscan.io/tx/${sig}`);

6. Priority fees — auto vs manual

Two patterns:

  • Auto (recommended): prioritizationFeeLamports: { priorityLevelWithMaxLamports: { maxLamports, priorityLevel: "veryHigh" } }. Jupiter samples the fee market via Triton and picks. Cap at something sane so a fee spike doesn't drain you.
  • Manual: prioritizationFeeLamports: 5_000_000 (flat lamports) or set computeUnitPriceMicroLamports yourself. Only do this if you're running your own fee oracle.

7. Dynamic slippage

dynamicSlippage: true lets Jupiter set otherAmountThreshold at build time based on observed volatility for that pair. The slippageBps in your quote becomes a cap. This is almost always what you want for production. Disable it if you're arb-ing and want exact behavior.

8. Token list / verified mints

Always verify the mint addresses you're swapping. Use the Jupiter strict token list at https://tokens.jup.ag/tokens?tags=verified (or lite-api.jup.ag/tokens/v1/...). Passing a random mint that looks like USDC but isn't will route — and you'll receive a worthless token.

Common pitfalls

  1. 6001: Slippage exceeded — price moved between quote and execution. Either raise slippageBps (50 → 100 → 300 for thin tokens), turn on dynamicSlippage: true, or refetch the quote right before sending.

  2. BlockhashNotFound / Transaction was not confirmed in 30.00 seconds — the blockhash baked into Jupiter's tx is ~60–90s lived. If you sat on swapTransaction too long, throw it away and call /swap again. Don't try to swap out the blockhash on the v0 tx — re-fetch.

  3. InsufficientFundsForRent even though you have SOL — Jupiter's swap amount is taken from your balance and you still pay the priority fee and possibly a 0.00203928 SOL rent deposit for a new ATA. Keep ~0.05 SOL clear above the swap amount on mainnet.

  4. Wrapped SOL ATA missing — if wrapAndUnwrapSol: false, you must create the wSOL ATA yourself before swapping out of SOL. Just leave it true unless you're aggregating multiple swaps and managing wSOL across them.

  5. "Why won't asLegacyTransaction work?" — it can't. Real Jupiter routes touch enough accounts that they only fit inside a v0 tx with Address Lookup Tables. Use VersionedTransaction.deserialize, not Transaction.from.

  6. Public RPC 429s mid-flight — api.mainnet-beta.solana.com will silently drop your sendRawTransaction under load and you'll think the swap "didn't go through" when it did. Use a staked-connection RPC (Helius, Triton, QuickNode). Verify by querying the signature.

  7. Decimals mismatch — amount is atomic units of inputMint, not human units. 1 USDC is 1_000_000 (6 decimals), 1 SOL is 1_000_000_000 (9 decimals). Multiply by 10 ** mint.decimals, never assume.

References

Example scripts

See scripts/quote-only.ts for a read-only quote and scripts/swap.ts for a full executed swap.

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall