; } ``` --- ## Configuration Options | Option | Type | Description | |---|---|---| | `displayMode` | `'integrated' \| 'widget' \| 'modal'` | How the swap UI is displayed | | `integratedTargetId` | `string` | DOM element ID for integrated mode (default: `'jupiter-plugin'`) | | `endpoint` | `string` | Solana RPC URL (**use Helius RPC**) | | `defaultExplorer` | `string` | Explorer for tx links: `'Solana Explorer'`, `'Solscan'`, `'Solana Beach'`, `'SolanaFM'` | | `formProps` | `object` | Pre-fill input/output mints, amounts, referral config | | `enableWalletPassthrough` | `boolean` | Enable wallet passthrough from your app | | `passthroughWalletContextState` | `WalletContextState` | Your app's wallet state (when passthrough is enabled) | ### Pre-filling Swap Parameters ```typescript window.Jupiter.init({ displayMode: 'modal', endpoint: HELIUS_RPC_URL, formProps: { initialInputMint: 'So11111111111111111111111111111111111111112', // SOL initialOutputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC initialAmount: '1000000000', // 1 SOL }, }); ``` ### Wallet Passthrough If your app already has a connected wallet, pass it through: ```typescript import { useWallet } from '@solana/wallet-adapter-react'; const wallet = useWallet(); window.Jupiter.init({ displayMode: 'integrated', endpoint: HELIUS_RPC_URL, enableWalletPassthrough: true, passthroughWalletContextState: wallet, }); ``` --- ## Helius Synergies ### RPC Endpoint **Always use a Helius RPC URL** as the `endpoint` parameter. This ensures: - Reliable, high-performance RPC access - Proper rate limits based on the user's Helius plan - Better transaction landing rates ```typescript const HELIUS_RPC = `https://mainnet.helius-rpc.com/?api-key=${HELIUS_API_KEY}`; window.Jupiter.init({ endpoint: HELIUS_RPC, // ... }); ``` ### Portfolio Context Combine the swap widget with Helius DAS to show the user's portfolio alongside the swap: ```typescript // 1. Fetch holdings via Helius getAssetsByOwner (showFungible: true) // 2. Display portfolio in your app // 3. Let users click a token to pre-fill the swap widget window.Jupiter.init({ formProps: { initialInputMint: selectedToken.mint, initialAmount: selectedToken.rawAmount, }, }); ``` ### Transaction Monitoring After swaps complete through the plugin, use Helius to provide rich transaction details: ```typescript // Listen for swap completion events from the plugin // Use parseTransactions MCP tool to show human-readable swap details // Use Wallet API to update portfolio view ``` --- ## Referral Fees Earn fees on swaps through the plugin using Jupiter's Referral Program: ```typescript window.Jupiter.init({ formProps: { referralAccount: 'YOUR_REFERRAL_ACCOUNT_ADDRESS', referralFee: 50, // 0.5% (range: 50-255 bps) }, }); ``` --- ## Theming Customize the plugin appearance using CSS variables: ```css :root { --jupiter-plugin-primary: #6366f1; --jupiter-plugin-bg: #1a1a2e; /* See Jupiter Plugin docs for all available CSS variables */ } ``` --- ## Common Pitfalls 1. **Always provide an RPC endpoint** — Without one, the plugin uses public RPCs which are unreliable. Use Helius RPC. 2. **Use wallet passthrough** if your app already handles wallet connection — avoids double-connect UX. Use `enableWalletPassthrough: true` + `passthroughWalletContextState`. 3. **Valid explorers**: `'Solana Explorer'`, `'Solscan'`, `'Solana Beach'`, `'SolanaFM'`. Do NOT use `'Orb'` — it's not supported by the Plugin. 4. **The plugin is client-side only** — It runs in the browser, not in Node.js. 5. **Use `init()` not JSX** — There is no `` React component. Use the `init()` function from `@jup-ag/plugin`. --- ## Resources - Jupiter Plugin Docs: [dev.jup.ag/docs/plugin](https://dev.jup.ag/docs/plugin) - Jupiter Plugin npm: [@jup-ag/plugin](https://www.npmjs.com/package/@jup-ag/plugin) --- ## jupiter-portal.md # Jupiter Portal — API Keys & Rate Limits ## What This Covers Jupiter API key setup, authentication requirements, and rate limiting behavior for all Jupiter REST endpoints. --- ## Getting an API Key All Jupiter REST endpoints require authentication via the `x-api-key` header. 1. Go to [developers.jup.ag/portal](https://developers.jup.ag/portal) 2. Sign in with your email 3. Generate an API key 4. Store it securely — never commit to git ### Using the API Key ```typescript const headers = { 'x-api-key': process.env.JUPITER_API_KEY!, 'Content-Type': 'application/json', }; const response = await fetch('https://api.jup.ag/swap/v2/order?inputMint=...&outputMint=...&amount=...&taker=...', { headers, }); ``` ### Environment Variable Setup ```bash export JUPITER_API_KEY=your-api-key-here ``` --- ## Base URL All Jupiter API endpoints use: ``` https://api.jup.ag ``` --- ## Rate Limits ### Swap API — Dynamic Rate Limits Swap API rate limits scale dynamically based on your 24-hour execute volume: | 24h Execute Volume | Rate Limit | |---|---| | $0 | 50 req/10s | | $10,000 | 51 req/10s | | $100,000 | 61 req/10s | | $1,000,000 | 165 req/10s | Rate limits increase as you drive more volume through the API. ### Other APIs Most other Jupiter APIs use standard rate limits. Check the specific API documentation for exact limits. ### Handling Rate Limits (HTTP 429) When you receive a 429 response, implement exponential backoff with jitter: ```typescript async function fetchWithRetry( url: string, options: RequestInit, maxRetries = 3 ): Promise { for (let attempt = 0; attempt <= maxRetries; attempt++) { const response = await fetch(url, options); if (response.status === 429 && attempt < maxRetries) { const baseDelay = Math.pow(2, attempt) * 1000; const jitter = Math.random() * 1000; await new Promise(r => setTimeout(r, baseDelay + jitter)); continue; } return response; } throw new Error('Max retries exceeded'); } ``` --- ## Authentication Invariant **Hard rule**: Never call a Jupiter REST endpoint without the `x-api-key` header. If the user hasn't configured a key, stop and ask them to set one up at [developers.jup.ag/portal](https://developers.jup.ag/portal) before proceeding. --- ## API Families Jupiter provides these API families, all under `https://api.jup.ag`: | API | Path Prefix | Purpose | |---|---|---| | Swap API V2 | `/swap/v2` | Token swaps with optimized routing | | Trigger V2 | `/trigger/v2` | Limit orders (JWT auth, vault deposits, OCO/OTOCO) | | Recurring | `/recurring/v1` | DCA orders | | Tokens | `/tokens/v2` | Token search and metadata | | Price | `/price/v3` | Token prices | | Portfolio | `/portfolio/v1` | Position tracking (beta) | | Prediction Markets | `/prediction/v1` | Event markets (beta, geo-restricted) | | Send | `/send/v1` | Token transfers (beta) | | Studio | `/studio/v1` | Token creation (beta) | | Lend (REST) | `/lend/v1` | Lending operations | ### Beta APIs Portfolio, Prediction Markets, Send, and Studio are currently in beta. Their interfaces may change. ### On-Chain Only - **Perps**: No REST API yet — on-chain Anchor IDL only - **Lock**: On-chain vesting program (audited by OtterSec and Sec3) --- ## Resources - Jupiter Portal: [developers.jup.ag/portal](https://developers.jup.ag/portal) - Jupiter Docs: [dev.jup.ag](https://dev.jup.ag/) - LLM-Optimized Docs: [dev.jup.ag/docs/llms.txt](https://dev.jup.ag/docs/llms.txt) --- ## jupiter-recurring.md # Jupiter Recurring API — Dollar-Cost Averaging (DCA) ## What This Covers Recurring token purchases via Jupiter's Recurring API — setting up DCA orders, viewing active orders, and canceling orders. --- ## Base URL & Auth ``` Base: https://api.jup.ag/recurring/v1 Auth: x-api-key header (required) ``` --- ## How DCA Works Jupiter Recurring creates on-chain DCA orders that automatically execute at regular intervals. Jupiter's keeper network handles the periodic execution. ### Fees - **0.1% execution fee** per individual order execution - Fees are deducted from the output amount at each execution ### Minimums - **Minimum total order value**: $100 USD equivalent - **Minimum per-order value**: $50 USD equivalent - **Minimum number of orders**: 2 - Orders that violate any of these minimums will be rejected ### Limitations - **Token-2022 not supported** — Only standard SPL tokens are compatible with the Recurring API. Token-2022 mints will be rejected. - **Price-based orders are deprecated** — The `params.price` field and `/priceDeposit` / `/priceWithdraw` endpoints are deprecated and no longer actively supported. Use time-based orders only. --- ## Endpoints ### POST /createOrder — Create DCA Order ```typescript const response = await fetch('https://api.jup.ag/recurring/v1/createOrder', { method: 'POST', headers: { 'x-api-key': process.env.JUPITER_API_KEY!, 'Content-Type': 'application/json', }, body: JSON.stringify({ user: walletPublicKey, inputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC outputMint: 'So11111111111111111111111111111111111111112', // SOL params: { time: { inAmount: '50000000', // 50 USDC per execution (atomic units) numberOfOrders: 10, // 10 executions total interval: 604800, // Interval in seconds: 86400=daily, 604800=weekly // Optional: // startAt: 1700000000, // Unix timestamp for first execution // minPrice: '100', // Min acceptable price // maxPrice: '200', // Max acceptable price }, }, }), }); const result = await response.json(); // Returns: { requestId, transaction } ``` **Parameters**: - `user` — Wallet public key - `inputMint` — Token you're spending (e.g., USDC) - `outputMint` — Token you're buying (e.g., SOL) - `params.time.inAmount` — Amount per execution in atomic units - `params.time.numberOfOrders` — Number of individual executions - `params.time.interval` — Interval between executions in **seconds** (86400 = daily, 604800 = weekly, 2592000 = ~monthly) - `params.time.startAt` — (Optional) Unix timestamp for first execution - `params.time.minPrice` — (Optional) Minimum price threshold — skip execution if price is below - `params.time.maxPrice` — (Optional) Maximum price threshold — skip execution if price is above ### Calculating Total Spend ```typescript const perExecution = 50_000_000; // 50 USDC const numberOfOrders = 10; const totalSpend = perExecution * numberOfOrders; // 500 USDC total // Total must be >= $100 USD equivalent ``` ### GET /getRecurringOrders — List Active DCA Orders ```typescript const response = await fetch( `https://api.jup.ag/recurring/v1/getRecurringOrders?user=${walletPublicKey}&orderStatus=active&recurringType=time`, { headers: { 'x-api-key': process.env.JUPITER_API_KEY! } } ); const orders = await response.json(); // Returns array of active DCA orders with progress, next execution time, etc. ``` **Parameters**: - `user` — Wallet public key - `orderStatus` — Required: `active` or `history` - `recurringType` — Required: `time` ### POST /cancelOrder — Cancel DCA Order ```typescript const response = await fetch('https://api.jup.ag/recurring/v1/cancelOrder', { method: 'POST', headers: { 'x-api-key': process.env.JUPITER_API_KEY!, 'Content-Type': 'application/json', }, body: JSON.stringify({ user: walletPublicKey, order: orderAddressToCancel, recurringType: 'time', }), }); const cancelResult = await response.json(); // Returns: { requestId, transaction } ``` Canceling a DCA order returns any unspent input tokens to the user's wallet. ### POST /execute — Submit Signed Transaction After signing a transaction from `/createOrder` or `/cancelOrder`, submit it back to Jupiter: ```typescript const executeResponse = await fetch('https://api.jup.ag/recurring/v1/execute', { method: 'POST', headers: { 'x-api-key': process.env.JUPITER_API_KEY!, 'Content-Type': 'application/json', }, body: JSON.stringify({ signedTransaction: base64SignedTx, requestId: result.requestId, }), }); ``` --- ## Transaction Flow All Recurring API responses that modify state return `transaction` and `requestId`. Sign the transaction and submit via `/execute` or Helius Sender. See `references/jupiter-trigger.md` for the full signing/submission pattern. --- ## Common Pitfalls 1. **Minimum $100 total** — Total spend (`inAmount * numberOfOrders`) must be >= $100 USD equivalent 2. **Minimum $50 per order** — Each individual `inAmount` must be >= $50 USD equivalent 3. **Minimum 2 orders** — `numberOfOrders` must be >= 2 4. **Token-2022 not supported** — Only standard SPL tokens work; Token-2022 mints are rejected 5. **Amounts are in atomic units** — 500 USDC = 500_000_000 6. **Interval is in seconds** — Not a string like `'weekly'`. Use 86400 for daily, 604800 for weekly. 7. **Unspent funds returned on cancel** — Remaining input tokens go back to the wallet 8. **Each execution is a separate swap** — Price varies per execution (that's the point of DCA) 9. **Frequency determines the schedule** — The keeper network handles timing; you don't need to trigger executions manually 10. **Use `user` not `maker`** — The field is `user` for all Recurring endpoints 11. **Price-based orders are deprecated** — Use time-based orders (`params.time`) only --- ## Resources - Recurring API Docs: [dev.jup.ag/docs/recurring](https://dev.jup.ag/docs/recurring) --- ## jupiter-swap.md # Jupiter Swap API V2 ## What This Covers Token swaps via Jupiter's Swap API V2 — getting quotes, executing swaps, building custom transactions, handling idempotency, and production hardening. V2 provides optimized routing across all Solana DEXes through multi-router competition. --- ## Base URL & Auth ``` Base: https://api.jup.ag/swap/v2 Auth: x-api-key header (required) ``` Rate limits are dynamic — see `references/jupiter-portal.md` for details. --- ## Two Paths Jupiter V2 offers two integration paths: | Feature | `/order` + `/execute` | `/build` | |---------|----------------------|----------| | Routing | All routers (Metis, JupiterZ RFQ, DFlow, OKX) | Metis only | | Swap fees | Jupiter platform fee included | None | | Execution | Managed via `/execute` (Jupiter Beam) | Self-managed (your own RPC) | | Transaction control | None (pre-built) | Full (raw instructions) | | Compute budget | Included in transaction | Instructions provided (overridable) | | Jito tip inclusion | Handled internally by Jupiter Beam (no tip ix in the returned transaction; landing is Jupiter's responsibility) | Not included — you add a `SystemProgram.transfer` to a Jito tip account when submitting via Helius Sender | **Use `/order` + `/execute`** for most integrations (recommended). **Use `/build`** only when you need custom instructions, CPI, or full transaction control. > **Using Helius Sender?** Sender's dual-routing (Jito) requires a tip transfer **inside** the transaction. `/order`'s pre-built transaction does not include one, so signing and forwarding it to Sender will fail to land via Jito. Use `/build` and assemble the transaction yourself — see `references/integration-patterns.md` Pattern 1 for the full recipe and `references/helius-sender.md` for tip accounts and minimum amounts. --- ## Path 1: Order & Execute (Recommended) ### GET /order — Get Quote + Transaction Returns a swap quote with a pre-built transaction. Omit `taker` to get a quote-only response — `transaction` will be null but `requestId` and the rest of the quote data are still returned. ```typescript const params = new URLSearchParams({ inputMint: 'So11111111111111111111111111111111111111112', // SOL outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC amount: '1000000000', // 1 SOL in lamports taker: walletPublicKey, // Optional — omit for quote-only }); const response = await fetch(`https://api.jup.ag/swap/v2/order?${params}`, { headers: { 'x-api-key': process.env.JUPITER_API_KEY! }, }); const order = await response.json(); // Returns: { transaction, requestId, inputMint, outputMint, inAmount, outAmount, router, mode, feeBps, feeMint } // If taker is omitted (quote-only): `transaction` is null, but `requestId` and the rest of the quote data are still returned ``` **Required parameters**: - `inputMint` — Source token mint address - `outputMint` — Destination token mint address - `amount` — Amount in atomic units (lamports for SOL, raw units for SPL tokens) - `taker` — Wallet public key that will sign (required for transaction, omit for quote-only) **Optional parameters**: - `slippageBps` — Slippage tolerance in basis points (default: auto via RTSE) - `receiver` — Destination wallet for output tokens (defaults to `taker`) - `referralAccount` — Referral account for integrator fees - `referralFee` — Referral fee in basis points (50-255 bps) - `excludeRouters` — Comma-separated routers to exclude: `iris`, `jupiterz`, `dflow`, `okx` - `excludeDexes` — Comma-separated DEXes to exclude from routing **Response fields**: - `transaction` — Base64-encoded transaction (null when `taker` is omitted) - `requestId` — Returned on every response (including quote-only); required for `/execute` and idempotent retries - `outAmount` — Expected output before slippage - `router` — Winning router (`iris`, `jupiterz`, `dflow`, `okx`) - `mode` — `ultra` (default params, all routers) or `manual` (optional params detected, routing restricted) - `feeBps` — Fee basis points applied - `feeMint` — Token used for fee ### POST /execute — Execute Swap Submit the signed transaction for managed execution. ```typescript // 1. Deserialize and sign const txBuffer = Buffer.from(order.transaction, 'base64'); const transaction = VersionedTransaction.deserialize(txBuffer); transaction.sign([keypair]); // 2. Execute via Jupiter const signedTx = Buffer.from(transaction.serialize()).toString('base64'); const execRes = await fetch('https://api.jup.ag/swap/v2/execute', { method: 'POST', headers: { 'x-api-key': process.env.JUPITER_API_KEY!, 'Content-Type': 'application/json', }, body: JSON.stringify({ signedTransaction: signedTx, requestId: order.requestId, }), }); const result = await execRes.json(); // Success: { status: "Success", signature, inputAmountResult, outputAmountResult, swapEvents } // Failure: { status: "Failed", code, error } ``` **CRITICAL**: Always include `requestId` from the `/order` response. This enables idempotent retries — if the request fails mid-flight, re-call `POST /execute` with the same `requestId` and `signedTransaction` to check status. **Jupiter execution features**: - RTSE (Real-Time Slippage Estimator) — adjusts slippage at execution time - Optimized priority fee strategy for current network conditions - Jupiter Beam — proprietary transaction execution pipeline across multiple RPC providers - Confirmation polling and transaction parsing ### Using Jupiter Quote + Helius Sender (Alternative) For more control over transaction submission, you can use Jupiter for the quote/transaction and Helius Sender for submission. See `references/integration-patterns.md` Pattern 1. --- ## Path 2: Build Custom Transactions (Advanced) ### GET /build — Get Instructions Returns raw swap instructions for custom transaction assembly. ```typescript const params = new URLSearchParams({ inputMint: 'So11111111111111111111111111111111111111112', outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', amount: '1000000000', taker: walletPublicKey, }); const response = await fetch(`https://api.jup.ag/swap/v2/build?${params}`, { headers: { 'x-api-key': process.env.JUPITER_API_KEY! }, }); const buildResult = await response.json(); ``` **Response fields**: - `computeBudgetInstructions` — Compute unit price instruction (no limit — you must simulate) - `setupInstructions` — Pre-swap setup (ATA creation, etc.) - `swapInstruction` — Main swap instruction - `cleanupInstruction` — Post-swap cleanup (nullable) - `otherInstructions` — Additional instructions - `addressesByLookupTableAddress` — V0 transaction lookup tables - `blockhashWithMetadata` — Blockhash and expiry height **Build flow**: 1. Call `/build` with required params 2. Add your custom instructions alongside swap instructions 3. Simulate with max CU limit (1,400,000) to estimate actual usage 4. Build V0 transaction with estimated CU limit (1.2x simulated, capped at 1,400,000) 5. If submitting via Helius Sender, append a `SystemProgram.transfer` to a random Jito tip account (see `references/integration-patterns.md` Pattern 1) 6. Sign and send via your own RPC (or Helius Sender) **Optional parameters**: - `slippageBps` — Slippage tolerance (default: 50 bps) - `mode` — `"fast"` for reduced latency routing - `maxAccounts` — Max accounts for swap route (1-64, default 64) - `platformFeeBps` — Integrator platform fee in bps - `feeAccount` — Token account for platform fees (required if `platformFeeBps` > 0) - `wrapAndUnwrapSol` — Auto wrap/unwrap SOL (default: true) - `dexes` / `excludeDexes` — Include/exclude specific DEXes - `blockhashSlotsToExpiry` — Slots until blockhash expires (1-300, default 150) **Note**: `/build` only supports ExactIn mode. You are responsible for sending the transaction via your own RPC and handling confirmation. Jupiter does not charge swap fees on `/build`. --- ## Routing Four routers compete for best pricing on `/order`: - **Metis** — Jupiter's on-chain aggregator (core routing engine) - **JupiterZ** — RFQ market makers (off-chain liquidity, often beats on-chain by 5-20 bps on major pairs) - **DFlow** — Third-party order flow - **OKX** — Third-party liquidity provider **Parameter impact on routing**: - `receiver`, `referralAccount`, `referralFee` — disables JupiterZ only (Metis, DFlow, OKX still compete) - `payer` — disables JupiterZ, DFlow, AND OKX (reduces to **Metis only**) Check the `mode` field in the response (`ultra` = all routers, `manual` = restricted). --- ## Fees ### `/order` Platform Fees | Token Pair | Fee | |------------|-----| | Jupiter tokens (SOL/Stable → JUP/JLP/jupSOL) | 0 bps | | Pegged assets (LST-LST, Stable-Stable) | 0 bps | | SOL-Stable | 2 bps | | LST-Stable | 5 bps | | Most other pairs | 10 bps | | New tokens (within 24 hours) | 50 bps | ### Integrator Fees (Referral Program) Use `referralAccount` and `referralFee` parameters on `/order`: - `referralFee` range: 50-255 basis points - Jupiter retains 20% of referral fees; you receive 80% - **Adding `referralAccount` disables RFQ (JupiterZ) routing** ### `/build` Fees No Jupiter platform fee. Implement custom fees via `platformFeeBps` and `feeAccount`. --- ## Gasless Swaps ### Automatic Gasless (`/order`) Jupiter automatically covers all gas when the taker has insufficient SOL: - Requires < 0.01 SOL in taker wallet - Minimum trade: ~$10 USD equivalent - Default `/order` parameters only (no integrator/manual mode params) - Increases swap fee to compensate (reduces output tokens) ### JupiterZ Gasless When RFQ market makers win the quote, they cover network and priority fees — but not ATA rent. Taker must have SOL for account creation. ### Integrator Payer Pass `payer` parameter on `/order` or `/build` to subsidize all gas costs. Routes through Metis only. --- ## Slippage - Default: auto-calculated by Jupiter's RTSE (Real-Time Slippage Estimator) - Custom: pass `slippageBps` parameter (e.g., `50` = 0.5%) - Recommended: use auto unless the user has a specific requirement - Note: `slippageBps` is incompatible with automatic gasless swaps --- ## Common Mints | Token | Mint Address | |---|---| | SOL | `So11111111111111111111111111111111111111112` | | USDC | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | | USDT | `Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB` | For other tokens, use the Jupiter Tokens API (`references/jupiter-tokens-price.md`) to look up mint addresses. --- ## Error Codes ### `/execute` Error Codes | Code | Category | Meaning | |------|----------|---------| | 0 | Success | Transaction confirmed | | -1 | Execute | Missing cached order (requestId not found or expired) | | -2 | Execute | Invalid signed transaction | | -3 | Execute | Invalid message bytes | | -1000 | Aggregator | Failed to land | | -1001 | Aggregator | Unknown error | | -1002 | Aggregator | Invalid transaction | | -1003 | Aggregator | Transaction not fully signed | | -1004 | Aggregator | Invalid block height | | -2000 | RFQ | Failed to land | | -2001 | RFQ | Unknown error | | -2002 | RFQ | Invalid payload | | -2003 | RFQ | Quote expired | | -2004 | RFQ | Swap rejected | Negative codes = Jupiter-internal (routing, slippage, etc.) — typically transient, retry with fresh quote. Positive codes = on-chain program errors. ### Timeout Handling - Set 5-second timeout for `/order` (quote) requests - Set 30-second timeout for `/execute` requests - If `/execute` times out, re-call with the same `requestId` and `signedTransaction` to check status — do NOT get a new quote without checking first --- ## Production Checklist 1. Always include `x-api-key` header 2. Always use `requestId` for idempotent retries 3. Set appropriate timeouts (5s quotes, 30s executions) 4. Implement exponential backoff for 429 responses 5. Validate mint addresses before calling the API 6. Enforce slippage guardrails for user protection 7. On timeout, re-call `/execute` with same requestId to check status 8. Check `mode` field to verify expected routing behavior 9. Log all API interactions with latency metrics --- ## Migration from Ultra / Metis - **From Ultra**: Update base URL from `https://ultra-api.jup.ag` to `https://api.jup.ag/swap/v2`. Request params and response format are identical. - **From Metis**: Consolidates `/quote` + `/swap-instructions` into single `/build` endpoint. `userPublicKey` becomes `taker`. Route plan uses `bps` instead of `percent` (10000 bps = 100%). --- ## Resources - Swap API V2 Docs: [dev.jup.ag/docs/swap](https://dev.jup.ag/docs/swap) - Jupiter Portal (API keys): [developers.jup.ag/portal](https://developers.jup.ag/portal) --- ## jupiter-tokens-price.md # Jupiter Tokens & Price APIs ## What This Covers Token discovery, metadata, and pricing via Jupiter's Tokens and Price APIs — searching for tokens, verifying legitimacy, and getting real-time prices. --- ## Tokens API (v2) ### Base URL & Auth ``` Base: https://api.jup.ag/tokens/v2 Auth: x-api-key header (required) ``` ### GET /search — Search Tokens Search for tokens by name, symbol, or mint address: ```typescript const response = await fetch( `https://api.jup.ag/tokens/v2/search?query=bonk`, { headers: { 'x-api-key': process.env.JUPITER_API_KEY! } } ); const tokens = await response.json(); // Returns array of matching tokens with metadata ``` Each token result includes: - `id` — Mint address - `name` — Token name - `symbol` — Token symbol - `decimals` — Decimal places - `icon` — Token logo URL - `isVerified` — Whether the token is verified - `organicScore` — Trading activity and community validation score - `mcap` — Market capitalization - `usdPrice` — Current USD price - `liquidity` — Available liquidity ### Looking Up Tokens by Mint To look up specific tokens, use search with comma-separated mint addresses (up to 100): ```typescript const mints = 'So11111111111111111111111111111111111111112,EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'; const response = await fetch( `https://api.jup.ag/tokens/v2/search?query=${mints}`, { headers: { 'x-api-key': process.env.JUPITER_API_KEY! } } ); ``` ### Token Verification & Organic Score Jupiter assigns tokens an **organic score** based on trading activity and community validation. Use this to filter out low-quality or potentially malicious tokens: ```typescript // Filter for verified tokens only const verifiedTokens = tokens.filter(t => t.isVerified); ``` **Best practice**: Always verify tokens before displaying them in a UI. Show verification status to users. --- ## Price API (v3) ### Base URL & Auth ``` Base: https://api.jup.ag/price/v3 Auth: x-api-key header (required) ``` ### GET /price — Get Token Prices ```typescript const mints = [ 'So11111111111111111111111111111111111111112', // SOL 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC ].join(','); const response = await fetch( `https://api.jup.ag/price/v3?ids=${mints}`, { headers: { 'x-api-key': process.env.JUPITER_API_KEY! } } ); const prices = await response.json(); // Returns mint addresses at the TOP LEVEL (no `data` wrapper): // { // "So11111111111111111111111111111111111111112": { // "usdPrice": 82.04, // "blockId": 412733640, // "decimals": 9, // "priceChange24h": -2.61 // }, // ... // } ``` **Constraints**: - Maximum **50 mint IDs** per request - Prices are in USD ### Response Fields Mints are keyed at the top level — there is NO `data` wrapper and NO `id` field on each entry. ```typescript const solPrice = prices['So11111111111111111111111111111111111111112']; console.log(`SOL: $${solPrice.usdPrice}`); console.log(`24h change: ${solPrice.priceChange24h}%`); console.log(`Block: ${solPrice.blockId}`); console.log(`Decimals: ${solPrice.decimals}`); ``` --- ## Token Shield — Security Checks Jupiter provides a security check endpoint to detect potentially dangerous tokens. ### GET /swap/v2/shield — Check Token Safety ```typescript const response = await fetch( `https://api.jup.ag/swap/v2/shield?mints=${mintAddress}`, { headers: { 'x-api-key': process.env.JUPITER_API_KEY! } } ); const shield = await response.json(); // Returns warnings about: freeze authority, mint authority, low organic activity, etc. ``` The `mints` parameter accepts comma-separated mint addresses (up to 100). ### Helius Synergy Combine Token Shield with Helius DAS for comprehensive token safety: ```typescript // 1. Jupiter Token Shield — check for freeze/mint authority risks const shieldData = await checkTokenShield(mintAddress); // 2. Helius DAS — check token metadata, supply, and holder distribution // Use getAsset MCP tool for metadata // Use getTokenHolders MCP tool for holder concentration // High holder concentration + freeze authority = high risk ``` **Best practice**: Always run Token Shield before displaying unknown tokens in a swap UI. Show warnings to users. --- ## Building a Token Selector Combine Jupiter Tokens API with Helius DAS for a complete token selector: ```typescript // 1. Get user's token holdings via Helius // Use getAssetsByOwner MCP tool with showFungible: true // 2. Enrich with Jupiter metadata // For each holding, fetch token info from Jupiter Tokens API v2 // 3. Get live prices // Batch mint addresses into Price API v3 calls (max 50 per request) // 4. Display with verification status // Show verified badge, price, and balance ``` See `references/integration-patterns.md` Pattern 2 for the complete implementation. --- ## Common Pitfalls 1. **Max 50 mints per price request** — Batch larger lists into multiple calls 2. **Max 100 mints per Token Shield / token lookup** — Use comma-separated values 3. **Verify tokens before displaying** — Check `isVerified` and `organicScore` to filter scam tokens 4. **Prices are in USD** — The field is `usdPrice`, not `price` 5. **Price API v3 has no `data` wrapper** — Access prices as `response[mint]`, NOT `response.data[mint]`. There is also no `id` field per entry. Using `response.data[mint]` will silently return `undefined`. 5. **Use Helius DAS for ownership data** — Jupiter Tokens API provides metadata, not wallet-specific data 6. **Tokens API is v2, Price API is v3** — Don't use the old v1/v2 endpoints --- ## Resources - Tokens API Docs: [dev.jup.ag/docs/tokens](https://dev.jup.ag/docs/tokens) - Price API Docs: [dev.jup.ag/docs/price](https://dev.jup.ag/docs/price) --- ## jupiter-trigger.md # Jupiter Trigger API V2 — Limit Orders ## What This Covers Limit orders via Jupiter's Trigger API V2 — placing price-triggered orders (single, OCO, OTOCO), managing vault deposits, viewing order history, canceling orders, and updating order parameters. V2 uses JWT authentication, vault-based deposits, and USD price triggers. --- ## Base URL & Auth ``` Base: https://api.jup.ag/trigger/v2 Auth: x-api-key header (required) + JWT Bearer token (required for most endpoints) Status: Beta, under active development ``` > **Trigger V2 is in active beta.** Endpoints, response shapes, and onboarding flows shift without notice. Verify against [dev.jup.ag/docs/trigger](https://dev.jup.ag/docs/trigger) before relying on this reference. --- ## Authentication (JWT Challenge-Response) Before placing or managing orders, authenticate via a two-step challenge-response flow to obtain a JWT. ### Step 1: Request Challenge ```typescript const challengeRes = await fetch('https://api.jup.ag/trigger/v2/auth/challenge', { method: 'POST', headers: { 'x-api-key': process.env.JUPITER_API_KEY!, 'Content-Type': 'application/json', }, body: JSON.stringify({ walletPubkey: walletPublicKey, type: 'message', // 'message' for software wallets, 'transaction' for hardware wallets }), }); const challenge = await challengeRes.json(); // message type: { type: "message", challenge: "Sign this message to authenticate..." } // transaction type: { type: "transaction", transaction: "" } ``` Challenge TTL: **5 minutes**. Request a new one if it expires. ### Step 2: Sign & Verify ```typescript // Sign the challenge message with the wallet const signature = await wallet.signMessage(new TextEncoder().encode(challenge.challenge)); const verifyRes = await fetch('https://api.jup.ag/trigger/v2/auth/verify', { method: 'POST', headers: { 'x-api-key': process.env.JUPITER_API_KEY!, 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'message', walletPubkey: walletPublicKey, signature: bs58.encode(signature), // base58-encoded signature }), }); const { token } = await verifyRes.json(); // token: JWT valid for 24 hours ``` JWT TTL: **24 hours**. No refresh endpoint — re-authenticate when expired. **Security**: A leaked JWT allows order cancellation and parameter edits, but **not** fund withdrawal — all fund operations require wallet-signed transactions. --- ## Vault Management Each wallet gets **one vault** (Privy-managed custodial account). Deposits go from wallet into vault, which backs all orders. ```typescript const headers = { 'x-api-key': process.env.JUPITER_API_KEY!, 'Authorization': `Bearer ${jwtToken}`, }; // Check if a vault exists for this wallet const vaultRes = await fetch('https://api.jup.ag/trigger/v2/vault', { headers }); // Returns: { userPubkey, vaultPubkey, privyVaultId, privyUserId? } // Returns 404 if no vault exists (user has not completed onboarding) ``` ### Vault Onboarding Programmatic vault registration via the public API is **not currently available**. Jupiter's `POST /trigger/v2/vault/register` route returns a router-level plain-text `404 Not Found` in production, even with a valid JWT and `x-api-key`. Vault provisioning happens through Privy onboarding inside the **jup.ag web UI**. If `GET /trigger/v2/vault` returns `404`, surface a clear message to the user instructing them to visit [jup.ag](https://jup.ag) and complete the Trigger onboarding flow once. Subsequent `GET /vault` calls (and `POST /deposit/craft`, `POST /orders/price`, etc.) will succeed against the provisioned vault. There is no need to repeat the web flow per session — vaults are permanent per wallet. For headless agents that cannot route a user through the web UI, contact Jupiter support — there is no documented programmatic onboarding path at present. > **Error shapes.** Trigger V2 app-level errors return JSON like `{"error":"..."}`. A plain-text `404 Not Found` response body means the route is not registered server-side — re-check [dev.jup.ag/docs/trigger](https://dev.jup.ag/docs/trigger) rather than assuming a parameter, header, or auth issue. This distinction saves a debugging round-trip on a beta API. --- ## How Trigger V2 Orders Work Jupiter Trigger V2 creates off-chain limit orders that execute automatically when the target **USD price** is reached. Orders are stored off-chain (MEV-resistant) and executed by Jupiter's keeper network. ### Order Types - **Single** — Triggers when USD price crosses above or below a threshold. Standard limit orders and stop-losses. - **OCO (One-Cancels-Other)** — Two orders sharing one deposit: one take-profit, one stop-loss. When one fills, the other cancels automatically. - **OTOCO (One-Triggers-One-Cancels-Other)** — A parent order triggers first, then activates a TP/SL pair (OCO) on the output tokens. ### Fees - **Non-stable pairs**: 0.1% execution fee - **Stable pairs** (e.g., USDC/USDT): 0.03% execution fee Fees are deducted from the output amount at execution time. ### Minimums - **Minimum order value**: $10 USD equivalent --- ## Order Creation (3-Step Process) ### Step 1: Craft Deposit Transaction ```typescript const depositRes = await fetch('https://api.jup.ag/trigger/v2/deposit/craft', { method: 'POST', headers: { 'x-api-key': process.env.JUPITER_API_KEY!, 'Authorization': `Bearer ${jwtToken}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ inputMint: 'So11111111111111111111111111111111111111112', // SOL outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC userAddress: walletPublicKey, amount: '1000000000', // 1 SOL in lamports }), }); const deposit = await depositRes.json(); // Returns: { transaction, requestId, receiverAddress, mint, amount, tokenDecimals } ``` ### Step 2: Sign the Deposit Transaction ```typescript import { VersionedTransaction } from '@solana/web3.js'; const transaction = VersionedTransaction.deserialize( Buffer.from(deposit.transaction, 'base64') ); transaction.sign([keypair]); const depositSignedTx = Buffer.from(transaction.serialize()).toString('base64'); ``` ### Step 3: Create Order with Signed Deposit ```typescript // Single limit order example: sell 1 SOL when price hits $200 const orderRes = await fetch('https://api.jup.ag/trigger/v2/orders/price', { method: 'POST', headers: { 'x-api-key': process.env.JUPITER_API_KEY!, 'Authorization': `Bearer ${jwtToken}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ orderType: 'single', depositRequestId: deposit.requestId, depositSignedTx: depositSignedTx, userPubkey: walletPublicKey, inputMint: 'So11111111111111111111111111111111111111112', inputAmount: '1000000000', outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', triggerMint: 'So11111111111111111111111111111111111111112', // Monitor SOL price triggerCondition: 'above', // Trigger when price goes above target triggerPriceUsd: 200, // $200 USD expiresAt: Date.now() + 7 * 24 * 60 * 60 * 1000, // 7 days (milliseconds) // Optional: // slippageBps: 50, }), }); const order = await orderRes.json(); // Returns: { id, txSignature } ``` ### Common Required Fields (All Order Types) | Field | Type | Description | |---|---|---| | `orderType` | `"single"` / `"oco"` / `"otoco"` | Order type | | `depositRequestId` | string | From `/deposit/craft` response | | `depositSignedTx` | string | Base64-encoded signed deposit transaction | | `userPubkey` | string | Wallet public key | | `inputMint` | string | Token being sold | | `inputAmount` | string | Amount in atomic units | | `outputMint` | string | Token being bought | | `triggerMint` | string | Token whose USD price to monitor | | `expiresAt` | number | Expiration timestamp in **milliseconds** | ### Single Order Fields | Field | Type | Required | Description | |---|---|---|---| | `triggerCondition` | `"above"` / `"below"` | Yes | Price direction trigger | | `triggerPriceUsd` | number | Yes | USD price threshold | | `slippageBps` | number | No | 0-10000 basis points | ### OCO Order Fields | Field | Type | Required | Description | |---|---|---|---| | `tpPriceUsd` | number | Yes | Take-profit USD price | | `slPriceUsd` | number | Yes | Stop-loss USD price | | `tpSlippageBps` | number | No | Take-profit slippage in bps | | `slSlippageBps` | number | No | Stop-loss slippage in bps | Constraint: `tpPriceUsd` must be greater than `slPriceUsd`. ### OTOCO Order Fields | Field | Type | Required | Description | |---|---|---|---| | `triggerCondition` | `"above"` / `"below"` | Yes | Parent trigger direction | | `triggerPriceUsd` | number | Yes | Parent trigger USD price | | `tpPriceUsd` | number | Yes | Secondary take-profit price | | `slPriceUsd` | number | Yes | Secondary stop-loss price | | `slippageBps` | number | No | Parent slippage | | `tpSlippageBps` | number | No | Secondary TP slippage | | `slSlippageBps` | number | No | Secondary SL slippage | --- ## OCO Example (Take-Profit + Stop-Loss) ```typescript const ocoOrder = await fetch('https://api.jup.ag/trigger/v2/orders/price', { method: 'POST', headers: { 'x-api-key': process.env.JUPITER_API_KEY!, 'Authorization': `Bearer ${jwtToken}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ orderType: 'oco', depositRequestId: deposit.requestId, depositSignedTx: depositSignedTx, userPubkey: walletPublicKey, inputMint: 'So11111111111111111111111111111111111111112', inputAmount: '1000000000', outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', triggerMint: 'So11111111111111111111111111111111111111112', tpPriceUsd: 200, // Take profit at $200 slPriceUsd: 120, // Stop loss at $120 expiresAt: Date.now() + 30 * 24 * 60 * 60 * 1000, // 30 days }), }); ``` --- ## Order Update Update trigger prices and slippage on existing orders without canceling: ```typescript const updateRes = await fetch(`https://api.jup.ag/trigger/v2/orders/price/${orderId}`, { method: 'PATCH', headers: { 'x-api-key': process.env.JUPITER_API_KEY!, 'Authorization': `Bearer ${jwtToken}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ orderType: 'single', triggerPriceUsd: 210, // Updated price slippageBps: 100, }), }); // Returns: { id } ``` Editable fields: trigger prices and slippage only. Amount/mint changes require canceling and recreating the order. --- ## Order Cancellation (2-Step Process) ### Step 1: Initiate Cancellation ```typescript const cancelRes = await fetch(`https://api.jup.ag/trigger/v2/orders/price/cancel/${orderId}`, { method: 'POST', headers: { 'x-api-key': process.env.JUPITER_API_KEY!, 'Authorization': `Bearer ${jwtToken}`, }, }); const cancel = await cancelRes.json(); // Returns: { id, transaction, requestId } // Order transitions to "ready_to_cancel" — will NOT be filled even before step 2 ``` ### Step 2: Sign & Confirm ```typescript // Sign the withdrawal transaction const cancelTx = VersionedTransaction.deserialize( Buffer.from(cancel.transaction, 'base64') ); cancelTx.sign([keypair]); const confirmRes = await fetch( `https://api.jup.ag/trigger/v2/orders/price/confirm-cancel/${orderId}`, { method: 'POST', headers: { 'x-api-key': process.env.JUPITER_API_KEY!, 'Authorization': `Bearer ${jwtToken}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ signedTransaction: Buffer.from(cancelTx.serialize()).toString('base64'), cancelRequestId: cancel.requestId, }), }, ); // Returns: { id, txSignature } ``` If step 2 fails, retry with the **same** `cancelRequestId`. Expired orders use this same 2-step flow to recover vault funds. --- ## Order History ```typescript const historyRes = await fetch( 'https://api.jup.ag/trigger/v2/orders/history?state=active&limit=20&offset=0&sort=updated_at&dir=desc', { headers: { 'x-api-key': process.env.JUPITER_API_KEY!, 'Authorization': `Bearer ${jwtToken}`, }, }, ); const history = await historyRes.json(); // Returns: { orders: OrderHistoryItem[], pagination: { total, limit, offset } } ``` **Query parameters**: - `state` — `active` or `past` - `mint` — Filter by token mint address - `limit` — 1-100 (default: 20) - `offset` — Pagination offset (default: 0) - `sort` — `updated_at`, `created_at`, or `expires_at` (default: `updated_at`) - `dir` — `asc` or `desc` (default: `desc`) **Order states**: `pending`, `open`, `executing`, `filled`, `pending_withdraw`, `cancelled`, `expired`, `failed` --- ## Slippage Defaults | Order Type | Default | Recommendation | |---|---|---| | Take-profit / buy-below | Auto via RTSE | Keep default | | Stop-loss / buy-above | 20% (2000 bps) | Keep high for execution reliability | | OTOCO parent | Auto via RTSE | Keep default | Stop-loss orders use a higher default because execution certainty matters more than price precision when cutting losses. --- ## Common Pitfalls 1. **Minimum $10 order value** — Orders below this are rejected 2. **USD price triggers** — V2 uses `triggerPriceUsd` (USD price), not token ratios or raw amounts 3. **Expiration is required** — No indefinite (GTC) orders in V2. Use 7-30 days; renew via `PATCH` for longer duration 4. **`expiresAt` is in milliseconds** — Not seconds. Use `Date.now() + duration_ms` 5. **JWT expires after 24 hours** — Re-authenticate via challenge-response; no refresh endpoint 6. **Vault must be onboarded first** — `/vault/register` is not callable programmatically (returns plain-text `404`). If `GET /vault` returns `404`, route the user through jup.ag web onboarding once. See the "Vault Onboarding" section above. 7. **3-step order creation** — Craft deposit → sign → create order. All three steps are required 8. **2-step cancellation** — Initiate → sign withdrawal. Order won't fill after step 1 even if step 2 is delayed 9. **Amounts are in atomic units** — 1 SOL = 1_000_000_000 lamports, 1 USDC = 1_000_000 10. **Orders are stored off-chain** — Private by default, reducing MEV attack vectors 11. **Token-2022 (transfer tax tokens) not supported** 12. **Open orders continue executing after JWT expiration** — JWT is for management, not execution --- ## Resources - Trigger API V2 Docs: [dev.jup.ag/docs/trigger](https://dev.jup.ag/docs/trigger) ---