Order & Execute

Documentation Index

Fetch the complete documentation index at: https://dev.jup.ag/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

Quick start

​

Prerequisites

// .env: BS58_PRIVATE_KEY=your_base58_secret_key

// @solana/kit
import { createKeyPairSignerFromBytes, getBase58Encoder } from "@solana/kit";
const signer = await createKeyPairSignerFromBytes(
  getBase58Encoder().encode(process.env.BS58_PRIVATE_KEY!),
);

// @solana/web3.js
import { Keypair } from "@solana/web3.js";
import bs58 from "bs58";
const signer = Keypair.fromSecretKey(bs58.decode(process.env.BS58_PRIVATE_KEY!));

import {
  createKeyPairSignerFromBytes,
  getBase58Encoder,
  getTransactionDecoder,
  getTransactionEncoder,
  partiallySignTransaction,
} from "@solana/kit";

type OrderResponse = {
  transaction: string;       // base64-encoded transaction
  requestId: string;
  outAmount: string;
  router: string;            // "iris" | "jupiterz" | "dflow" | "okx"
  mode: string;              // "ultra" | "manual"
  feeBps: number;
  feeMint: string;
};

type ExecuteResponse = {
  status: "Success" | "Failed";
  signature: string;
  code: number;
  inputAmountResult: string;
  outputAmountResult: string;
  error?: string;
};

const API_KEY = process.env.JUPITER_API_KEY;
if (!API_KEY) throw new Error("Missing JUPITER_API_KEY");
const BASE_URL = "https://api.jup.ag/swap/v2";

// Load wallet from base58 secret key in .env
const signer = await createKeyPairSignerFromBytes(
  getBase58Encoder().encode(process.env.BS58_PRIVATE_KEY!),
);

​

Code example

// Step 1: Get an order
const orderResponse = await fetch(
  `${BASE_URL}/order?` +
    new URLSearchParams({
      inputMint: "So11111111111111111111111111111111111111112", // SOL
      outputMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC
      amount: "100000000",
      taker: signer.address,
    }),
  { headers: { "x-api-key": API_KEY } },
);
if (!orderResponse.ok) {
  console.error(`/order failed: ${orderResponse.status}`, await orderResponse.text());
  process.exit(1);
}
const order: OrderResponse = await orderResponse.json();

if (!order.transaction) {
  console.error("No transaction in response:", JSON.stringify(order, null, 2));
  process.exit(1);
}

// Step 2: Sign the transaction
// Use partiallySignTransaction because JupiterZ quotes require an additional
// market maker signature, which is added during /execute
const transactionBytes = Buffer.from(order.transaction, "base64");
const transaction = getTransactionDecoder().decode(transactionBytes);
const signedTransaction = await partiallySignTransaction(
  [signer.keyPair],
  transaction,
);

// Step 3: Execute
const signedTxBytes = getTransactionEncoder().encode(signedTransaction);
const signedTxBase64 = Buffer.from(signedTxBytes).toString("base64");

const executeResponse = await fetch(`${BASE_URL}/execute`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": API_KEY,
  },
  body: JSON.stringify({
    signedTransaction: signedTxBase64,
    requestId: order.requestId,
  }),
});
if (!executeResponse.ok) {
  console.error(`/execute failed: ${executeResponse.status}`, await executeResponse.text());
  process.exit(1);
}
const result: ExecuteResponse = await executeResponse.json();

console.log(`https://solscan.io/tx/${result.signature}`);
if (result.status === "Success") {
  console.log("Swap successful:", JSON.stringify(result, null, 2));
} else {
  console.error("Swap failed:", JSON.stringify(result, null, 2));
}

​

How it works

​

1. Get an order

​

2. Sign the transaction

• The transaction returned by /order is unsigned. Sign it with your wallet’s private key. The example above uses @solana/kit. The transaction is a versioned transaction (v0).
• Note: we use the partiallySignTransaction for partial signing because when JupiterZ routing is provided, there is an additional signer which is the MM that will be required after sending the transaction to /execute request.

​

3. Execute the transaction

• Optimised slippage via RTSE (Real-Time Slippage Estimator), applied at order time to balance trade success and price protection
• Optimised priority fee strategy for current network conditions
• Jupiter Beam (our own proprietary transaction execution pipeline) for accelerated transaction sending and landing across multiple RPC providers
• Confirmation polling
• Parses both successful and failed transactions

​

Error codes

​

Routing impact matrix

​

Order mode

​

Fees

​

Jupiter platform fee

{
  "platformFee": {
    "amount": "8529",
    "feeBps": 5,
    "feeMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
  }
}

​

Total fee vs platform fee

​

Fee breakdown

​

Fee mint priority

1. SOL
2. Stablecoins (USDC, USDT, etc.)
3. Liquid staked tokens (jupSOL, etc.)
4. Bluechips (large market cap tokens)
5. Others

​

Referral fees

​

How it works

• Jupiter takes 20% of your integrator fee (no separate platform fee when referral is active)
• Jupiter decides which token mint to collect fees in based on the fee mint priority list
• You must create a referralTokenAccount for each mint you expect to receive fees in
• If the referralTokenAccount for the feeMint is not initialised, the order still returns but executes without your fees (the user still gets their swap)
• Fee range: 50 to 255 bps
• Supports SPL and Token2022 tokens

​

Setup

1. Install the Referral SDK

npm install @jup-ag/referral-sdk

2. Create a referralAccount (once)

import { ReferralProvider } from "@jup-ag/referral-sdk";
import { Connection, Keypair, PublicKey, sendAndConfirmTransaction } from "@solana/web3.js";
import bs58 from "bs58";

const connection = new Connection("https://api.mainnet-beta.solana.com");
const wallet = Keypair.fromSecretKey(bs58.decode(process.env.BS58_PRIVATE_KEY!));
const provider = new ReferralProvider(connection);

// Jupiter Ultra Referral Project
const projectPubKey = new PublicKey("DkiqsTrw1u1bYFumumC7sCG2S8K25qc2vemJFHyW2wJc");

const transaction = await provider.initializeReferralAccountWithName({
  payerPubKey: wallet.publicKey,
  partnerPubKey: wallet.publicKey,
  projectPubKey: projectPubKey,
  name: "your-app-name",
});

const signature = await sendAndConfirmTransaction(connection, transaction.tx, [wallet]);
console.log("referralAccount:", transaction.referralAccountPubKey.toBase58());

3. Create referralTokenAccount for each fee mint

const mint = new PublicKey("So11111111111111111111111111111111111111112"); // SOL

const transaction = await provider.initializeReferralTokenAccountV2({
  payerPubKey: wallet.publicKey,
  referralAccountPubKey: new PublicKey("YOUR_REFERRAL_ACCOUNT"),
  mint,
});

const signature = await sendAndConfirmTransaction(connection, transaction.tx, [wallet]);
console.log("referralTokenAccount:", transaction.tokenAccount.toBase58());

​

Usage

const params = new URLSearchParams({
  inputMint: "So11111111111111111111111111111111111111112",
  outputMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  amount: "1000000000",
  taker: walletAddress,
  referralAccount: "YOUR_REFERRAL_ACCOUNT",
  referralFee: "50", // 50 bps = 0.5%
});

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

​

Fee response fields

​

Related

• Jupiter Referral Program for the full referral program documentation
• Advanced Techniques for gasless swaps, priority fees, and CU optimisation
• API Reference: GET /order for the full OpenAPI specification
• API Reference: POST /execute for the full OpenAPI specification