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.

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](https://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 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]( swap) GET /swap/v2/order sign POST /swap/v2/execute Lend/borrow/yield [Lend]( lend) POST /lend/v1/earn/deposit or /withdraw Leverage/perps [Perps]( perps) On chain via Anchor IDL (no REST API yet) Limit orders [Trigger]( trigger limit orders) JWT auth POST /trigger/v2/orders/price DCA/recurring buys [Recurring]( recurring dca) POST /recurring/v1/createOrder sign POST /recurring/v1/execute Token search [Tokens]( tokens) GET /tokens/v2/search?query={mint} Token verification/metadata update Use jupiter vrfd skill Defer — not handled by this skill Price lookup [Price]( price) GET /price/v3?ids={mints} Portfolio/positions [Portfolio]( portfolio) GET /portfolio/v1/positions/{address} Prediction market integration [Prediction Markets]( prediction markets) GET /prediction/v1/events POST /prediction/v1/orders Invite send/clawback [Send]( send) POST /send/v1/craft send sign send to RPC Token creation/fees [Studio]( studio) POST /studio/v1/dbc pool/create tx upload submit Vesting/distribution [Lock]( lock) On chain program LocpQgucEQHbqNABEYvBvwoxCPsSbG91A1QaQhQQqjn DEX/RFQ integration [Routing]( 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]( 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](https://developers.jup.ag/docs/swap/advanced/gasless.md) 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](https://developers.jup.ag/docs/swap/index.md) [Order & Execute](https://developers.jup.ag/docs/swap/order and execute.md) [Build](https://developers.jup.ag/docs/swap/build/index.md) [Gasless](https://developers.jup.ag/docs/swap/advanced/gasless.md) [Migration](https://developers.jup.ag/docs/swap/migration/ultra to order.md) [OpenAPI](https://developers.jup.ag/docs/openapi spec/swap/v2/swap.yaml) 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](https://developers.jup.ag/docs/lend/index.md) [Earn](https://developers.jup.ag/docs/lend/earn.md) [SDK](https://developers.jup.ag/docs/lend/api vs sdk.md) [OpenAPI](https://developers.jup.ag/docs/openapi spec/lend/lend.yaml) 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.com/julianfssen/jupiter perps anchor idl parsing](https://github.com/julianfssen/jupiter perps anchor idl parsing) Gotchas : Max 9 simultaneous positions: 3 long (SOL, wETH, wBTC) + 6 short (3 tokens x 2 collateral USDC/USDT). Validate margin/leverage against account model. Refs: [Overview](https://developers.jup.ag/docs/perps/index.md) [Position account](https://developers.jup.ag/docs/perps/position account.md) [Position request](https://developers.jup.ag/docs/perps/position request account.md) Trigger (Limit Orders) Base URL : https://api.jup.ag/trigger/v2 Triggers : limit order , trigger , price condition Min order : 10 USD equivalent Auth : Dual auth — x api key (all requests) + Authorization: Bearer <jwt (order mutations). JWT obtained via challenge response: POST /auth/challenge → sign challenge with wallet → POST /auth/verify → receive token. JWT expiry does NOT affect open orders — they continue executing. Endpoints : /auth/challenge (POST, body: walletPubkey + type ), /auth/verify (POST, body: type + walletPubkey + base58 signature ), /vault (GET), /vault/register (GET), /deposit/craft (POST), /orders/price (POST create, PATCH update), /orders/price/cancel/{orderId} (POST, initiates withdrawal), /orders/price/confirm cancel/{orderId} (POST, submits signed withdrawal + cancelRequestId ), /orders/history (GET, wallet implicit via JWT) Order types : single (one directional trigger), oco (take profit + stop loss pair), otoco (entry trigger + OCO). triggerCondition : "above" or "below" . Architecture : Off chain custodial vault (Privy) per wallet. Orders invisible on chain until execution — MEV resistant. Triggers on USD price (not pool rate ratios). Partial fills supported. Gotchas : Order creation is 3 steps — GET /vault/register (register if new; returns 409 "Vault already registered" if it exists, which is fine), POST /deposit/craft (returns transaction + requestId ; the body MUST include orderType: "price" and orderSubType ( single / oco / otoco )), sign deposit tx, then POST /orders/price with depositRequestId + depositSignedTx . Cancellation is two step — POST /cancel/{orderId} returns transaction + requestId ; sign, then POST /con

integrating-jupiter