Integrating Jupiter

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(path: string, init?: RequestInit): Promise {
  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 {
  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;
}

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 (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 /confirm-cancel/{orderId} with signedTransaction + cancelRequestId.
• Create response field is id (not orderId); order history objects use orderState/rawState (no status field).
• Refs: Overview | Authentication | Create order | Order history | Manage orders | OpenAPI

---

Recurring (DCA)

• Base URL: https://api.jup.ag/recurring/v1
• Triggers: dca, recurring, scheduled swaps
• Fee: 0.1% on all recurring orders
• Constraints: Min 100 USD total, min 2 orders, min 50 USD per order
• Pagination: 10 orders per page
• Endpoints: /createOrder (POST), /cancelOrder (POST), /execute (POST), /getRecurringOrders (GET)
• Gotchas: Token-2022 NOT supported. Use params.time for order scheduling; price-based ordering is not supported.
• Refs: Overview | Create | Get orders | Best Practices | OpenAPI

---

Tokens

• Base URL: https://api.jup.ag/tokens/v2
• Triggers: token metadata, token search, shield
• Endpoints: /search?query={q} (GET, comma-separate mints, max 100), /tag?query={tag} (GET, verified or lst), /{category}/{interval} (GET, categories: toporganicscore, toptraded, toptrending; intervals: 5m, 1h, 6h, 24h), /recent (GET)
• Gotchas:
• Use mint address as primary identity; treat symbol/name as convenience.
• Primary trust signal is top-level isVerified (boolean) plus organicScore (0-100) and organicScoreLabel (high/medium/low).
• Secondary risk flag: audit.isSus — a boolean present ONLY when true (a safe token has no isSus key at all), so check it defensively as token.audit?.isSus === true, never read it directly. Verified live on flagged tokens (dev holds ~100% of supply); those also carry isVerified: null and organicScoreLabel: "low". Absence of isSus is NOT proof of safety — not all risky tokens carry the flag.
• Other conditional audit fields the live API returns: mintAuthorityDisabled, freezeAuthorityDisabled, topHoldersPercentage, devBalancePercentage, devMigrations, devMints (all nullable, any may be absent; devMigrations is returned but missing from the current OpenAPI schema).
• Refs: Overview | Token info v2 | OpenAPI

---

Price

• Base URL: https://api.jup.ag/price/v3
• Triggers: price, valuation, price feed
• Limit: Max 50 mint IDs per request
• Endpoints: /price/v3?ids={mints} (GET, comma-separated)
• Response: keyed by mint, each value has usdPrice, blockId, decimals, priceChange24h, liquidity, createdAt (some tokens add conditional fields like launchpad, stockData, scaledUiConfig). Price API V3 has NO confidenceLevel field (that was V2).
• Gotchas: Tokens with unreliable pricing are omitted from the response entirely (not an error, no null placeholder). Fail closed when a requested mint is missing from the response for safety-sensitive actions. Use blockId to check price recency.
• Refs: Overview | OpenAPI

---

Portfolio

• Base URL: https://api.jup.ag/portfolio/v1
• Status: Beta — Jupiter platforms only
• Triggers: portfolio, positions, holdings
• Endpoints: /positions/{address} (GET), /positions/{address}?platforms={ids} (GET), /platforms (GET), /staked-jup/{address} (GET)
• Gotchas: Treat empty positions as valid state. Response is beta — normalize into stable internal schema. Element types: multiple, liquidity, trade, leverage, borrowlend.
• Refs: Overview | Jupiter positions | OpenAPI

---

Prediction Markets

• Base URL: https://api.jup.ag/prediction/v1
• Status: Beta (breaking changes possible)
• Geo-restricted: US and South Korea IPs blocked
• Price convention: 1,000,000 native units = $1.00 USD
• Triggers: prediction markets, market odds, event market
• Deposit mints: JupUSD (JuprjznTrTSp2UFa3ZBUFgwdAmtZCq4MQCwysN55USD), USDC
• Min order: $5 (5,000,000 native units)
• Endpoints: /events (GET, returns {data, pagination}), /events/search (GET), /markets/{marketId} (GET), /orderbook/{marketId} (GET, returns {yes, no, yes_dollars, no_dollars}), /orders (POST, requires isBuy boolean + ownerPubkey), /orders/status/{orderPubkey} (GET), /positions (GET, ?ownerPubkey=), /positions/{positionPubkey} (DELETE), /positions/{positionPubkey}/claim (POST), /history (GET), /leaderboards (GET)
• Gotchas:
• Check position.claimable before claiming. Winners get $1/contract.
• Markets are FLAT — fields like provider, marketId, result, resolveAt, outcomes, clobTokenIds live at the top level, not nested under metadata.
• Contracts are fractional: use contractsMicro (1,000,000 = 1 contract) or contractsDecimal, not the legacy whole-number contracts.
• Refs: Overview | Events | Positions | OpenAPI

---

Send

• Base URL: https://api.jup.ag/send/v1
• Status: Beta
• Triggers: invite transfer, send, clawback
• Supported tokens: SOL, USDC, memecoins
• Endpoints: /craft-send (POST), /craft-clawback (POST), /pending-invites (GET), /invite-history (GET)
• Gotchas: Dual-sign requirement — sender + recipient keypair (derived from invite code). Claims only via Jupiter Mobile (no API claiming). Never expose invite codes.
• Refs: Overview | Invite code | Craft send | OpenAPI

---

Studio

• Base URL: https://api.jup.ag/studio/v1
• Status: Beta
• Triggers: create token, studio, claim fee
• Endpoints: /dbc-pool/create-tx (POST), /dbc-pool/submit (POST, multipart/form-data), /dbc-pool/addresses/{mint} (GET), /dbc/fee (POST), /dbc/fee/create-tx (POST)
• Flow: create-tx -> upload image to presigned URL -> upload metadata to presigned URL -> sign -> submit via /dbc-pool/submit
• Gotchas: Must submit via /dbc-pool/submit (not externally) for token to get a Studio page on jup.ag. Error codes: 403 = not authorized for pool, 404 = proxy account not found.
• Refs: Overview | Create token | Claim fee | OpenAPI

---

Lock

• Program ID: LocpQgucEQHbqNABEYvBvwoxCPsSbG91A1QaQhQQqjn
• Triggers: vesting, distribution lock, unlock schedule
• Integration: On-chain program only (no REST API)
• Source: github.com/jup-ag/jup-lock
• UI: lock.jup.ag
• Security: Audited by OtterSec and Sec3
• Gotchas: No REST API. Use instruction scripts from the repo's cli/src/bin/instructions directory.
• Refs: Lock overview

---

Routing

• Triggers: dex integration, rfq integration, routing engine
• Engines: Juno (meta-aggregator), Metis (multi-hop DEX routing, powers the Swap API; formerly called Iris), JupiterZ (RFQ market maker quotes)
• DEX Integration (into Metis): Free, no fees. Prereqs: code health, security audit, market traction. Implement jupiter-amm-interface crate. Critical: No network calls in implementation (accounts are pre-batched and cached). Ref impl: github.com/jup-ag/rust-amm-implementation
• RFQ Integration (JupiterZ): Market makers host webhook at /jupiter/rfq/quote (POST, 250ms), /jupiter/rfq/swap (POST), /jupiter/rfq/tokens (GET). Reqs: 95% fill rate, 250ms response, 55s expiry. SDK: github.com/jup-ag/rfq-webhook-toolkit
• Market Listing: Instant routing for tokens {

ok: boolean; result?: T; error?: { code: string | number; message: string; retryable: boolean }; }

async function jupiterAction(action: () => Promise): Promise> {

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jup-ag
• Source: jup-ag/agent-skills
• License: MIT
• Homepage: https://jup.md

Install and usage instructions live in the source repository linked above.