---

name: integrating-jupiter description: Comprehensive guidance for integrating Jupiter APIs (Swap, Lend, Perps, Trigger, Recurring, Tokens, Price, Portfolio, Prediction Markets, Send, Studio, Lock, Routing). Use for endpoint selection, integration flows, error handling, and production hardening. license: MIT metadata: author: jup-ag version: "1.2.0" tags:

• jupiter
• jup-ag
• solana
• defi
• swap-v2
• token-swap
• dex-aggregator
• gasless
• limit-order
• dca
• jupiter-lend
• jupiter-perps
• jupiter-trigger
• jupiter-recurring
• jupiter-portfolio
• jupiter-prediction
• jupiter-send
• jupiter-studio
• jupiter-lock
• jupiter-routing
• jupiterz-rfq
• metis
• jupiter-price-api
• jupiter-tokens-api
• jupiter-portal
• jlp

---

Jupiter API Integration

Single skill for all Jupiter APIs, optimized for fast routing and deterministic execution.

Base URL: https://api.jup.ag Auth: x-api-key from developers.jup.ag (required for Jupiter REST endpoints)

Use/Do Not Use

Use when:

• The task requires choosing or calling Jupiter endpoints.
• The task involves swap, lending, perps, orders, pricing, portfolio, send, studio, lock, or routing.
• The user needs debugging help for Jupiter API calls.

Do not use when:

• The task is generic Solana setup with no Jupiter API usage.
• The task is UI-only with no API behavior decisions.
• The agent context is not DeFi/crypto (generic triggers like buy, sell, trade assume a DeFi domain).

Triggers: swap, quote, gasless, best route, buy, sell, trade, convert, token exchange, jupiter api, jup.ag, ultra, metis, ultra swap, ultra api, ultra-api.jup.ag, lend, borrow, earn, yield, apy, deposit, liquidation, perps, leverage, long, short, position, futures, margin trading, limit order, trigger, price condition, dca, recurring, scheduled swaps, token metadata, token search, verification, shield, price, valuation, price feed, portfolio, positions, holdings, prediction markets, market odds, event market, invite transfer, send, clawback, create token, studio, claim fee, vesting, distribution lock, unlock schedule, dex integration, rfq integration, routing engine, status page, health check, service health, accumulate, auto-buy

Developer Quickstart

import { Connection, Keypair, VersionedTransaction } from '@solana/web3.js';

const API_KEY = process.env.JUPITER_API_KEY!;  // from developers.jup.ag
if (!API_KEY) throw new Error('Missing JUPITER_API_KEY');
const BASE = 'https://api.jup.ag';
const headers = { 'x-api-key': API_KEY };

async function jupiterFetch<T>(path: string, init?: RequestInit): Promise<T> {
  const res = await fetch(`${BASE}${path}`, {
    ...init,
    headers: { ...headers, ...init?.headers },
  });
  if (res.status === 429) throw { code: 'RATE_LIMITED', retryAfter: Number(res.headers.get('Retry-After')) || 10 };
  if (!res.ok) {
    const raw = await res.text();
    let body: any = { message: raw || `HTTP_${res.status}` };
    try {
      body = raw ? JSON.parse(raw) : body;
    } catch {
      // keep text fallback body
    }
    throw { status: res.status, ...body };
  }
  return res.json();
}

// Sign and send any Jupiter transaction
async function signAndSend(
  txBase64: string,
  wallet: Keypair,
  connection: Connection,
  additionalSigners: Keypair[] = []
): Promise<string> {
  const tx = VersionedTransaction.deserialize(Buffer.from(txBase64, 'base64'));
  tx.sign([wallet, ...additionalSigners]);
  const sig = await connection.sendRawTransaction(tx.serialize(), {
    maxRetries: 0,
    skipPreflight: true,
  });
  return sig;
}

Token Amounts & Decimals

Every Jupiter amount field is in the token's smallest unit (raw integer) — never a human/UI value.

• Common decimals: SOL & wSOL = 9, USDC & USDT = 6. Canonical mints: SOL So11111111111111111111111111111111111111112, USDC EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v.
• Convert human → raw: raw = Math.round(human * 10 ** decimals). Examples: 1 SOL → 1_000_000_000, 100 USDC → 100_000_000. slippageBps is basis points: 0.5% = 50, 1% = 100.
• Read decimals per-mint on-chain with getMint(connection, mintPubkey) from @solana/spl-token — never hardcode (decimals vary by token), and do not call the Price API just to discover decimals.

Intent Router (first step)

| User intent | API family | First action | |---|---|---| | Swap/quote | Swap | GET /swap/v2/order -> sign -> POST /swap/v2/execute | | Lend/borrow/yield | Lend | POST /lend/v1/earn/deposit or /withdraw | | Leverage/perps | Perps | On-chain via Anchor IDL (no REST API yet) | | Limit orders | Trigger | JWT auth -> POST /trigger/v2/orders/price | | DCA/recurring buys | Recurring | POST /recurring/v1/createOrder -> sign -> POST /recurring/v1/execute | | Token search | Tokens | GET /tokens/v2/search?query={mint} | | Token verification/metadata update | Use jupiter-vrfd skill | Defer — not handled by this skill | | Price lookup | Price | GET /price/v3?ids={mints} | | Portfolio/positions | Portfolio | GET /portfolio/v1/positions/{address} | | Prediction market integration | Prediction Markets | GET /prediction/v1/events -> POST /prediction/v1/orders | | Invite send/clawback | Send | POST /send/v1/craft-send -> sign -> send to RPC | | Token creation/fees | Studio | POST /studio/v1/dbc-pool/create-tx -> upload -> submit | | Vesting/distribution | Lock | On-chain program LocpQgucEQHbqNABEYvBvwoxCPsSbG91A1QaQhQQqjn | | DEX/RFQ integration | Routing | Choose DEX (AMM trait) vs RFQ (webhook) path |

API Playbooks

Use each block as a minimal execution contract. Fetch the linked refs for full request/response shapes, TypeScript interfaces, and parameter details.

Swap

• Base URL: https://api.jup.ag/swap/v2

• Triggers: swap, quote, gasless, best route

• Fee: Variable by pair — 0 bps (Jupiter tokens/pegged), 2 bps (SOL-Stable), 5 bps (LST-Stable), 10 bps (most pairs), 50 bps (tokens < 24h). Referral fees: 50-255 bps (Jupiter retains 20%).

• Rate Limit: 50 req/10s base, scales with 24h execute volume (see Rate Limits)

• Endpoints: /order (GET), /execute (POST), /build (GET, Metis-only raw instructions)

• Quote vs. execute: For a read-only quote/price preview, call GET /order and omit taker — the response transaction is null and you read outAmount, routePlan[].swapInfo.label, and price-impact fields. Pass taker (then sign + POST /execute) only when you actually intend to swap. There is no separate quote endpoint — /swap/v1/quote is deprecated; use /swap/v2/order for quotes too.

• Routing: 4 routers compete — Metis (metis), JupiterZ (jupiterz), Dflow (dflow), OKX (okx). The router response field returns one of these values. swapType is aggregator (Metis, Dflow, or OKX) or rfq (JupiterZ). Response mode field: "ultra" (all routers, default params) or "manual" (restricted by optional params). /build uses Metis only.

• Gasless: Three paths — automatic (Jupiter-covered), JupiterZ (MM-covered), integrator-payer (payer param, Metis-only routing). Eligibility varies by balance, trade size, and parameters used. See Gasless docs for current thresholds and disqualifying params.

• Gotchas:

  • Signed payloads have ~2 min TTL. Transactions are immutable after receipt.
  • Split order/execute in code and logging. Re-quote before execution when conditions may have changed.
  • Routing impact of optional params: referralAccount + referralFee disable JupiterZ only (Metis/Dflow/OKX remain); payer (integrator gasless) restricts routing to Metis only (disables JupiterZ, Dflow, and OKX); receiver does NOT restrict routing, but must differ from taker (receiver=taker returns 400 "Receiver cannot be same as taker").
  • /build transactions cannot use /execute — self-manage via RPC.

• Migrating from an older integration? Use the jupiter-swap-migration skill.

• Refs: Overview | Order & Execute | Build | Gasless | Migration | OpenAPI

  Fees are documented inline on the Order & Execute and Build pages; router competition and the parameter routing-impact matrix are on the Overview and Order & Execute pages.

Common error codes returned by /swap/v2/execute with recommended actions:

| Code | Category | Meaning | Retryable | Action | |------|----------|---------|-----------|--------| | 0 | Success | Transaction confirmed | — | — | | -1 | Execute | Missing/expired cached order | Yes | Re-quote and retry | | -2 | Execute | Invalid signed transaction | No | Fix transaction signing | | -3 | Execute | Invalid message bytes | No | Fix serialization | | -1000 | Aggregator | Failed landing attempt | Yes | Re-quote with adjusted params | | -1001 | Aggregator | Unknown error | Yes | Retry with backoff | | -1002 | Aggregator | Invalid transaction | No | Fix transaction construction | | -1003 | Aggregator | Transaction not fully signed | No | Ensure all required signers | | -1004 | Aggregator | Invalid block height | Yes | Re-quote (stale blockhash) | | -2000 | RFQ | Failed landing | Yes | Re-quote and retry | | -2001 | RFQ | Unknown error | Yes | Retry with backoff | | -2002 | RFQ | Invalid payload | No | Fix request payload | | -2003 | RFQ | Quote expired | Yes | Re-quote and retry | | -2004 | RFQ | Swap rejected | Yes | Re-quote, possibly different route | | 429 | Rate limit | Rate limited | Yes | Exponential backoff, wait 10s window |

On success, /execute returns { status: "Success", code: 0, signature, inputAmountResult, outputAmountResult, slot, totalInputAmount, totalOutputAmount }. On failure it returns status: "Failed" with a non-zero code and an error string. inputAmountResult/outputAmountResult are the actual on-chain amounts; reconcile against your quote.

---

Lend

• Base URL: https://api.jup.ag/lend/v1
• Triggers: lend, borrow, earn, liquidation
• Programs: Earn jup3YeL8QhtSx1e253b2FDvsMNC87fDrgQZivbrndc9, Borrow jupr81YtYssSyPt8jbnGuiWon5f6x9TcDEFxYe3Bdzi
• SDK: @jup-ag/lend (TypeScript)
• Endpoints: /earn/deposit (POST), /earn/withdraw (POST), /earn/mint (POST), /earn/redeem (POST), /earn/deposit-instructions (POST), /earn/withdraw-instructions (POST), /earn/tokens (GET), /earn/positions (GET), /earn/earnings (GET)
• Gotchas: Recompute account state before each state-changing action. Encode risk checks (health factors, liquidation boundaries) as preconditions. All deposit/withdraw/mint/redeem return base64 unsigned VersionedTransaction.
• For SDK-level integration with @jup-ag/lend and @jup-ag/lend-read, use the jupiter-lend skill.
• Refs: Overview | Earn | SDK | OpenAPI

---

Perps

• Status: API is work-in-progress. No REST endpoints yet. Interact on-chain via Anchor IDL.
• Triggers: perps, leverage, long, short, position
• Community SDK: [github.