Jupiter Developers

The Router path uses the /build endpoint to return raw swap instructions instead of an assembled transaction. Routing is handled by Metis, Jupiter’s onchain routing engine, which finds the best path across Solana DEXes. You build the transaction yourself, giving you full control to add custom instructions, CPI, or modify any part of the transaction. Once built and signed, submit via your own RPC or use /submit to land through Jupiter’s transaction infrastructure with SOL tips.

Quick start

Prerequisites

Imports, types, and helpers

import {
  AccountRole,
  Address,
  address,
  AddressesByLookupTableAddress,
  appendTransactionMessageInstructions,
  Base64EncodedBytes,
  Blockhash,
  compileTransaction,
  compressTransactionMessageUsingAddressLookupTables,
  createKeyPairSignerFromBytes,
  createSolanaRpc,
  createTransactionMessage,
  getBase58Decoder,
  getBase58Encoder,
  getBase64Codec,
  getBase64EncodedWireTransaction,
  AccountMeta,
  Instruction,
  pipe,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  signTransaction,
} from "@solana/kit";
import { getTransferSolInstruction } from "@solana-program/system"; // For adding custom instructions

// ── Config ──────────────────────────────────────────────────────────────────
const COMPUTE_BUDGET_PROGRAM: Address = address(
  "ComputeBudget111111111111111111111111111111",
);
const COMPUTE_UNIT_LIMIT_MAX = 1_400_000;

// ── Instruction types ───────────────────────────────────────────────────────

type Account = {
  pubkey: Address;
  isSigner: boolean;
  isWritable: boolean;
};

type ApiInstruction = {
  programId: Address;
  accounts: Account[];
  data: Base64EncodedBytes;
};

function createInstruction(ix: ApiInstruction): Instruction {
  return {
    programAddress: ix.programId,
    accounts: ix.accounts.map((acc) => ({
      address: acc.pubkey,
      role: acc.isSigner && acc.isWritable
        ? AccountRole.WRITABLE_SIGNER
        : acc.isSigner
          ? AccountRole.READONLY_SIGNER
          : acc.isWritable
            ? AccountRole.WRITABLE
            : AccountRole.READONLY,
    })),
    data: Uint8Array.from(getBase64Codec().encode(ix.data)),
  };
}

// ── Build response type ─────────────────────────────────────────────────────

type BuildResponse = {
  inputMint: string;
  outputMint: string;
  inAmount: string;
  outAmount: string;
  otherAmountThreshold: string;
  swapMode: string;
  slippageBps: number;
  routePlan: {
    percent: number;
    bps: number;
    swapInfo: {
      ammKey: string;
      label: string;
      inputMint: string;
      outputMint: string;
      inAmount: string;
      outAmount: string;
    };
  }[];
  computeBudgetInstructions: ApiInstruction[];
  setupInstructions: ApiInstruction[];
  swapInstruction: ApiInstruction;
  cleanupInstruction: ApiInstruction | null;
  otherInstructions: ApiInstruction[];
  tipInstruction: ApiInstruction | null;
  addressesByLookupTableAddress: Record<string, string[]> | null;
  blockhashWithMetadata: {
    blockhash: number[];
    lastValidBlockHeight: number;
  };
};

// ── Helpers ──────────────────────────────────────────────────────────────────

function makeSetComputeUnitLimitIx(units: number): ApiInstruction {
  const data = Buffer.alloc(5);
  data.writeUInt8(0x02, 0);
  data.writeUInt32LE(units, 1);
  return {
    programId: COMPUTE_BUDGET_PROGRAM,
    accounts: [],
    data: data.toString("base64") as ApiInstruction["data"],
  };
}

function transformBlockhash(meta: BuildResponse["blockhashWithMetadata"]): {
  blockhash: Blockhash;
  lastValidBlockHeight: bigint;
} {
  return {
    blockhash: getBase58Decoder().decode(
      Uint8Array.from(meta.blockhash),
    ) as Blockhash,
    lastValidBlockHeight: BigInt(meta.lastValidBlockHeight),
  };
}

function transformALTs(
  raw: Record<string, string[]> | null,
): AddressesByLookupTableAddress {
  if (!raw) return {};
  return Object.fromEntries(
    Object.entries(raw).map(([key, addrs]) => [
      address(key),
      addrs.map((a) => address(a)),
    ]),
  );
}

function buildTransaction(
  ixs: Instruction[],
  blockhash: { blockhash: Blockhash; lastValidBlockHeight: bigint },
  alts: AddressesByLookupTableAddress,
  feePayer: Address,
) {
  return pipe(
    createTransactionMessage({ version: 0 }),
    (msg) => appendTransactionMessageInstructions(ixs, msg),
    (msg) => compressTransactionMessageUsingAddressLookupTables(msg, alts),
    (msg) => setTransactionMessageFeePayer(feePayer, msg),
    (msg) => setTransactionMessageLifetimeUsingBlockhash(blockhash, msg),
    (msg) => compileTransaction(msg),
  );
}

import {
  ComputeBudgetProgram,
  Connection,
  Keypair,
  PublicKey,
  SystemProgram,
  TransactionInstruction,
  TransactionMessage,
  VersionedTransaction,
  AddressLookupTableAccount,
} from "@solana/web3.js";
import bs58 from "bs58";

const COMPUTE_UNIT_LIMIT_MAX = 1_400_000;

// ── API response types ──────────────────────────────────────────────────────

type ApiAccount = {
  pubkey: string;
  isSigner: boolean;
  isWritable: boolean;
};

type ApiInstruction = {
  programId: string;
  accounts: ApiAccount[];
  data: string; // base64
};

type BuildResponse = {
  inputMint: string;
  outputMint: string;
  inAmount: string;
  outAmount: string;
  otherAmountThreshold: string;
  swapMode: string;
  slippageBps: number;
  routePlan: {
    percent: number;
    bps: number;
    swapInfo: {
      ammKey: string;
      label: string;
      inputMint: string;
      outputMint: string;
      inAmount: string;
      outAmount: string;
    };
  }[];
  computeBudgetInstructions: ApiInstruction[];
  setupInstructions: ApiInstruction[];
  swapInstruction: ApiInstruction;
  cleanupInstruction: ApiInstruction | null;
  otherInstructions: ApiInstruction[];
  tipInstruction: ApiInstruction | null;
  addressesByLookupTableAddress: Record<string, string[]> | null;
  blockhashWithMetadata: {
    blockhash: number[];
    lastValidBlockHeight: number;
  };
};

// ── Helpers ──────────────────────────────────────────────────────────────────

function toInstruction(ix: ApiInstruction): TransactionInstruction {
  return new TransactionInstruction({
    programId: new PublicKey(ix.programId),
    keys: ix.accounts.map((acc) => ({
      pubkey: new PublicKey(acc.pubkey),
      isSigner: acc.isSigner,
      isWritable: acc.isWritable,
    })),
    data: Buffer.from(ix.data, "base64"),
  });
}

function transformALTs(
  raw: Record<string, string[]> | null,
): AddressLookupTableAccount[] {
  if (!raw) return [];
  return Object.entries(raw).map(
    ([key, addresses]) =>
      new AddressLookupTableAccount({
        key: new PublicKey(key),
        state: {
          deactivationSlot: BigInt("18446744073709551615"),
          lastExtendedSlot: 0,
          lastExtendedSlotStartIndex: 0,
          addresses: addresses.map((a) => new PublicKey(a)),
        },
      }),
  );
}

Code example

const API_KEY = process.env.JUPITER_API_KEY;
const RPC_URL = process.env.RPC_URL;
if (!API_KEY) throw new Error("Missing JUPITER_API_KEY");
if (!RPC_URL) throw new Error("Missing RPC_URL");

const signer = await createKeyPairSignerFromBytes(
  getBase58Encoder().encode(process.env.BS58_PRIVATE_KEY!),
);
const rpc = createSolanaRpc(RPC_URL);

// Step 1: Get swap instructions from /build
const buildRes = await fetch(
  "https://api.jup.ag/swap/v2/build?" +
    new URLSearchParams({
      inputMint: "So11111111111111111111111111111111111111112",
      outputMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      amount: "100000000",
      taker: signer.address,
      slippageBps: "100",
      tipAmount: "1000000", // 0.001 SOL tip for /submit (omit if using your own RPC)
    }),
  { headers: { "x-api-key": API_KEY } },
);
if (!buildRes.ok) {
  console.error(`/build failed: ${buildRes.status}`, await buildRes.text());
  process.exit(1);
}
const build: BuildResponse = await buildRes.json();

// Step 2: Collect instructions (no compute unit limit yet, we simulate first)
// Example: add a SOL transfer after the swap
const RECIPIENT = address("YOUR_RECIPIENT_ADDRESS");
const transferIx = getTransferSolInstruction({
  source: signer,
  destination: RECIPIENT,
  amount: 1_000_000n, // 0.001 SOL
});

const instructions = [
  ...build.setupInstructions.map(createInstruction),
  createInstruction(build.swapInstruction),
  transferIx, // Your custom instruction, added after the swap
  ...(build.cleanupInstruction
    ? [createInstruction(build.cleanupInstruction)]
    : []),
  ...build.otherInstructions.map(createInstruction),
  ...(build.tipInstruction
    ? [createInstruction(build.tipInstruction)]
    : []),
];

// Step 3: Prepare blockhash and address lookup tables
const blockhash = transformBlockhash(build.blockhashWithMetadata);
const alts = transformALTs(build.addressesByLookupTableAddress);

// Step 4: Simulate with max CU limit to estimate actual usage
const simulationTx = buildTransaction(
  [
    createInstruction(makeSetComputeUnitLimitIx(COMPUTE_UNIT_LIMIT_MAX)),
    ...instructions,
  ],
  blockhash,
  alts,
  signer.address,
);

const simulationResult = await rpc
  .simulateTransaction(getBase64EncodedWireTransaction(simulationTx), {
    encoding: "base64",
    commitment: "confirmed",
    replaceRecentBlockhash: true,
  })
  .send();

if (simulationResult.value.err) {
  console.error("Simulation failed:", simulationResult.value.err);
}

// Set 1.2x buffer on simulated CU, capped at max
const estimatedCUL = simulationResult.value.unitsConsumed
  ? Math.min(
      Math.ceil(Number(simulationResult.value.unitsConsumed) * 1.2),
      COMPUTE_UNIT_LIMIT_MAX,
    )
  : COMPUTE_UNIT_LIMIT_MAX;

// Step 5: Build final transaction with estimated CU limit + CU price from response
const compiledTx = buildTransaction(
  [
    createInstruction(makeSetComputeUnitLimitIx(estimatedCUL)),
    ...build.computeBudgetInstructions.map(createInstruction),
    ...instructions,
  ],
  blockhash,
  alts,
  signer.address,
);

// Step 6: Sign and submit via /submit (or use your own RPC / transaction pipeline)
const signedTransaction = await signTransaction([signer.keyPair], compiledTx);

const submitRes = await fetch("https://api.jup.ag/tx/v1/submit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": API_KEY,
  },
  body: JSON.stringify({
    signedTransaction: getBase64EncodedWireTransaction(signedTransaction),
  }),
});

const { signature } = await submitRes.json();
console.log("Submitted:", `https://solscan.io/tx/${signature}`);

// Step 7: Confirm the transaction landed
const confirmation = await rpc
  .confirmTransaction(signature, {
    strategy: { type: "blockhash", ...blockhash },
    commitment: "confirmed",
  })
  .send();

if (confirmation.value.err) {
  console.error("Transaction failed:", confirmation.value.err);
  process.exit(1);
}

console.log("Confirmed:", signature);

const API_KEY = process.env.JUPITER_API_KEY;
const RPC_URL = process.env.RPC_URL;
if (!API_KEY) throw new Error("Missing JUPITER_API_KEY");
if (!RPC_URL) throw new Error("Missing RPC_URL");

const connection = new Connection(RPC_URL);
const signer = Keypair.fromSecretKey(
  bs58.decode(process.env.BS58_PRIVATE_KEY!),
);

// Step 1: Get swap instructions from /build
const buildRes = await fetch(
  "https://api.jup.ag/swap/v2/build?" +
    new URLSearchParams({
      inputMint: "So11111111111111111111111111111111111111112",
      outputMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      amount: "100000000",
      taker: signer.publicKey.toString(),
      slippageBps: "100",
      tipAmount: "1000000", // 0.001 SOL tip for /submit (omit if using your own RPC)
    }),
  { headers: { "x-api-key": API_KEY } },
);
if (!buildRes.ok) {
  console.error(`/build failed: ${buildRes.status}`, await buildRes.text());
  process.exit(1);
}
const build: BuildResponse = await buildRes.json();

// Step 2: Collect instructions (no compute unit limit yet, we simulate first)
// Example: add a SOL transfer after the swap
const RECIPIENT = new PublicKey("YOUR_RECIPIENT_ADDRESS");
const transferIx = SystemProgram.transfer({
  fromPubkey: signer.publicKey,
  toPubkey: RECIPIENT,
  lamports: 1_000_000, // 0.001 SOL
});

const instructions = [
  ...build.setupInstructions.map(toInstruction),
  toInstruction(build.swapInstruction),
  transferIx, // Your custom instruction, added after the swap
  ...(build.cleanupInstruction
    ? [toInstruction(build.cleanupInstruction)]
    : []),
  ...build.otherInstructions.map(toInstruction),
  ...(build.tipInstruction
    ? [toInstruction(build.tipInstruction)]
    : []),
];

// Step 3: Resolve address lookup tables (from /build response, no RPC needed)
const addressLookupTableAccounts = transformALTs(
  build.addressesByLookupTableAddress,
);

const { blockhash, lastValidBlockHeight } = build.blockhashWithMetadata;
const recentBlockhash = bs58.encode(Buffer.from(blockhash));

// Step 4: Simulate with max CU limit to estimate actual usage
const simulationMessage = new TransactionMessage({
  payerKey: signer.publicKey,
  recentBlockhash,
  instructions: [
    ComputeBudgetProgram.setComputeUnitLimit({ units: COMPUTE_UNIT_LIMIT_MAX }),
    ...instructions,
  ],
}).compileToV0Message(addressLookupTableAccounts);

const simulationTx = new VersionedTransaction(simulationMessage);
const simulationResult = await connection.simulateTransaction(simulationTx, {
  replaceRecentBlockhash: true,
});

if (simulationResult.value.err) {
  console.error("Simulation failed:", simulationResult.value.err);
}

// Set 1.2x buffer on simulated CU, capped at max
const estimatedCUL = simulationResult.value.unitsConsumed
  ? Math.min(
      Math.ceil(simulationResult.value.unitsConsumed * 1.2),
      COMPUTE_UNIT_LIMIT_MAX,
    )
  : COMPUTE_UNIT_LIMIT_MAX;

// Step 5: Build final transaction with estimated CU limit + CU price from response
const finalMessage = new TransactionMessage({
  payerKey: signer.publicKey,
  recentBlockhash,
  instructions: [
    ComputeBudgetProgram.setComputeUnitLimit({ units: estimatedCUL }),
    ...build.computeBudgetInstructions.map(toInstruction), // CU price from response
    ...instructions,
  ],
}).compileToV0Message(addressLookupTableAccounts);

// Step 6: Sign and submit via /submit (or use your own RPC / transaction pipeline)
const transaction = new VersionedTransaction(finalMessage);
transaction.sign([signer]);

const submitRes = await fetch("https://api.jup.ag/tx/v1/submit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": API_KEY,
  },
  body: JSON.stringify({
    signedTransaction: Buffer.from(transaction.serialize()).toString("base64"),
  }),
});

const { signature } = await submitRes.json();
console.log("Submitted:", `https://solscan.io/tx/${signature}`);

// Step 7: Confirm the transaction landed
const confirmation = await connection.confirmTransaction(
  { signature, blockhash: recentBlockhash, lastValidBlockHeight },
  "confirmed",
);

if (confirmation.value.err) {
  console.error("Transaction failed:", confirmation.value.err);
  process.exit(1);
}

console.log("Confirmed:", signature);

How it works

1. Call `/build`

GET /build returns a quote and all the instructions you need to build a swap transaction. Required parameters:

Parameter	Description
`inputMint`	Mint address of the token you are selling
`outputMint`	Mint address of the token you are buying
`amount`	Amount in the smallest unit of the input token
`taker`	Your wallet address

Key response fields:

Field	Description
`computeBudgetInstructions`	Compute unit price instruction (does not include compute unit limit)
`setupInstructions`	Pre-swap setup (e.g. ATA creation)
`swapInstruction`	The main swap instruction
`cleanupInstruction`	Post-swap cleanup (may be null)
`otherInstructions`	Additional instructions
`tipInstruction`	SOL tip transfer instruction (present when `tipAmount` is provided)
`addressesByLookupTableAddress`	Address lookup tables for v0 transactions
`blockhashWithMetadata`	Recent blockhash and expiry height

Each instruction follows this structure:

{
  programId: string,     // Program address
  accounts: [
    {
      pubkey: string,    // Account address
      isWritable: boolean,
      isSigner: boolean
    }
  ],
  data: string           // Base64-encoded instruction data
}

2. Add your own instructions

Insert custom instructions alongside the swap instructions. Common examples:

SOL transfer (tip or payment)
Memo instruction
Create or close token accounts
Custom program CPI

See Common Instructions for a reference of common instructions.

3. Simulate compute unit limit

The /build response includes computeBudgetInstructions with the compute unit price but not the compute unit limit. You need to simulate the transaction to determine the correct limit. Why: integrators using /build typically add their own instructions, so the CU usage will differ from the base swap. The simulation gives you the actual CU consumed, and you set the limit to 1.2x that value (capped at 1,400,000). Both code examples above demonstrate this: simulate with max CU limit, then rebuild with 1.2x the simulated value plus the CU price from the response. See Solana fee structure for more on compute units and Estimate Compute Units for a standalone guide.

4. Build a v0 transaction

The response includes address lookup tables in addressesByLookupTableAddress. Use these to compile a v0 (versioned) transaction, which supports more accounts than legacy transactions.

5. Sign and send

Sign the transaction with your wallet and send via your own RPC, or use /submit to land them through Jupiter’s transaction infrastructure with SOL tips.

/build transactions cannot use /execute.

/build does not have the required requestId
/build is intended for customisations, and /execute validates the transaction to prevent any changes

Router vs Meta-Aggregator

	Meta-Aggregator (`/order`)	Router (`/build`)
Routing	All engines (Metis, JupiterZ, Dflow, OKX)	Metis only
Swap fees	Jupiter platform fee	None
Transaction landing	Managed via `/execute`	Self-managed or use Jupiter’s proprietary transaction landing pipeline via `/submit`
Transaction control	None	Full
Compute budget	Included in transaction	Included as instructions (you can override)

Optional parameters

Parameter	Default	Description
`slippageBps`	50	Slippage tolerance in basis points, or `"rtse"` for RTSE
`tipAmount`	-	SOL tip amount in lamports. Adds a tip instruction for use with `/submit`
`computeUnitPricePercentile`	-	Priority fee percentile for the CU price instruction. Named levels: `"medium"` (25th), `"high"` (50th), `"veryHigh"` (75th), or an integer 0-10000 in bps. See Compute Units
`mode`	(default)	“fast” for reduced latency routing (BETA)
`maxAccounts`	64	Maximum accounts for the swap route (1-64)
`platformFeeBps`	0	Integrator platform fee in bps (requires `feeAccount`)
`feeAccount`	-	Token account to collect platform fees
`payer`	public key	Account that pays transaction fees and rent
`wrapAndUnwrapSol`	true	Whether to wrap/unwrap SOL automatically
`dexes`	(all)	Restrict routing to specific DEXes
`excludeDexes`	(none)	Exclude specific DEXes from routing
`destinationTokenAccount`	-	SPL token account for output
`nativeDestinationAccount`	-	Native SOL account for output
`blockhashSlotsToExpiry`	150	Slots until blockhash expires (1-300)
`forJitoBundle`	false	Exclude DEXes incompatible with Jito bundles

For the full parameter reference, see the API reference.

Fees

Jupiter does not charge swap fees on /build. The only fee mechanism is integrator platform fees via platformFeeBps and feeAccount:

const params = new URLSearchParams({
  inputMint: "So11111111111111111111111111111111111111112",
  outputMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  amount: "1000000000",
  taker: walletAddress,
  platformFeeBps: "50",          // 0.5%
  feeAccount: "YOUR_FEE_TOKEN_ACCOUNT",
});

const response = await fetch(
  `https://api.jup.ag/swap/v2/build?${params}`,
  { headers: { "x-api-key": API_KEY } }
);

Your fee is added as part of the swap instruction. The feeAccount can be any SPL token account you control (it does not need to be a referral program account). You are responsible for creating and managing this account.

Transaction Submission to submit via Jupiter’s transaction landing infrastructure with SOL tips for priority processing
Common Instructions for common instructions to compose with your swap
Advanced Techniques for CU simulation, mode: "fast", and maxAccounts
API Reference: GET /build for the full OpenAPI specification

Swap

Meta-Aggregator

Router

Advanced

Routing Integration

Guides

Migration

Build

Quick start

Prerequisites

Code example

How it works

1. Call `/build`

2. Add your own instructions

3. Simulate compute unit limit

4. Build a v0 transaction

5. Sign and send

Router vs Meta-Aggregator

Optional parameters

Fees

​Quick start

​Prerequisites

​Code example

​How it works

​1. Call /build

​2. Add your own instructions

​3. Simulate compute unit limit

​4. Build a v0 transaction

​5. Sign and send

​Router vs Meta-Aggregator

​Optional parameters

​Fees

​Related

Quick start

Prerequisites

Code example

How it works

1. Call `/build`

2. Add your own instructions

3. Simulate compute unit limit

4. Build a v0 transaction

5. Sign and send

Router vs Meta-Aggregator

Optional parameters

Fees

Related