jupiter-swap-migration
installsforks
How to install jupiter-swap-migration?
jup-ag/agent-skills/jupiter-swap-migration
$npx -y skills add jup-ag/agent-skills --skill jupiter-swap-migrationMigration guide from Jupiter Metis (v1) or Ultra to Swap API v2. Use when migrating existing Jupiter swap integrations, updating base URLs, or transitioning from quote+swap-instructions to the unified build endpoint.
SKILL.md
| 1 | # Jupiter Swap Migration Guide |
| 2 | |
| 3 | Migrate existing Jupiter swap integrations from **Metis (v1)** or **Ultra** to the unified **Swap API v2**. |
| 4 | |
| 5 | **Target Base URL**: `https://api.jup.ag/swap/v2` |
| 6 | **Auth**: `x-api-key` from [developers.jup.ag](https://developers.jup.ag/) (unchanged) |
| 7 | |
| 8 | ## Use/Do Not Use |
| 9 | |
| 10 | Use when: |
| 11 | - Migrating code that calls `api.jup.ag/swap/v1/quote`, `api.jup.ag/swap/v1/swap-instructions`, or `ultra-api.jup.ag`. |
| 12 | - Updating Jupiter swap endpoints to v2. |
| 13 | - Switching from Metis two-step flow to the unified `/build` or `/order` endpoint. |
| 14 | |
| 15 | Do not use when: |
| 16 | - Building a new Jupiter integration from scratch (use `integrating-jupiter` skill instead). |
| 17 | - Working with non-swap Jupiter APIs (Lend, Trigger, Recurring, etc.). |
| 18 | |
| 19 | **Triggers**: `ultra`, `metis`, `ultra swap`, `ultra api`, `ultra-api.jup.ag`, `/ultra/v1`, `swap/v1`, `swap-instructions`, `migrate swap`, `ultra migration`, `metis migration`, `swap v1 to v2`, `v1 to v2`, `upgrade jupiter`, `swap-instructions deprecated`, `deprecated swap`, `old jupiter api`, `swap upgrade`, `update swap api`, `quote endpoint deprecated`, `swap stopped working`, `swap broken`, `ExactOut removed`, `swapMode removed`, `userPublicKey`, `parameter rename`, `addressLookupTable`, `response format changed` |
| 20 | |
| 21 | --- |
| 22 | |
| 23 | ## Migration Paths |
| 24 | |
| 25 | | Source | Target | Effort | When to choose | |
| 26 | |--------|--------|--------|----------------| |
| 27 | | Ultra → `/order` | `GET /swap/v2/order` + `POST /swap/v2/execute` | Minimal (URL change only) | Default for Ultra users | |
| 28 | | Metis → `/build` | `GET /swap/v2/build` | Moderate (parameter + response mapping) | Need transaction composability | |
| 29 | | Metis → `/order` | `GET /swap/v2/order` + `POST /swap/v2/execute` | Moderate (flow change) | Don't need tx modification, want managed execution | |
| 30 | |
| 31 | ## Path Details |
| 32 | |
| 33 | Each path has a dedicated example with before/after code, parameter mappings, and response changes: |
| 34 | |
| 35 | - [Path 1: Ultra → `/order`](./examples/ultra-to-order.md) — Minimal migration, base URL change only |
| 36 | - [Path 2: Metis → `/build`](./examples/metis-to-build.md) — Consolidates 2 calls into 1, parameter and response mapping |
| 37 | - [Path 3: Metis → `/order`](./examples/metis-to-order.md) — Flow change to managed execution with multi-router competition |
| 38 | |
| 39 | --- |
| 40 | |
| 41 | ## Post-Migration Checklist |
| 42 | |
| 43 | 1. **URL audit**: Search codebase for `ultra-api.jup.ag`, `/ultra/v1/`, `/swap/v1/quote`, `/swap/v1/swap-instructions` — all should be replaced |
| 44 | 2. **Parameter rename**: `userPublicKey` → `taker` (for `/build` path) |
| 45 | 3. **`swapMode` removal**: V2 only supports `ExactIn`. If using `ExactOut`, redesign the flow — this mode is no longer available |
| 46 | 4. **`slippageBps` default**: `/build` defaults to 50 bps if omitted. For `/order`, verify the default if your integration relies on a specific value |
| 47 | 5. **Response field names**: Verify your code uses `inputAmountResult`/`outputAmountResult` for the `/execute` response (the canonical v2 field names) |
| 48 | 6. **ALT handling**: If using `/build`, switch from `addressLookupTableAddresses` (array) to `addressesByLookupTableAddress` (object) — remove RPC ALT resolution code |
| 49 | 7. **Fee event parsing**: V2 instructions don't emit fee events — update any transaction parser that depends on them |
| 50 | 8. **Route plan format**: If parsing route plans, use `bps` field (canonical) instead of `percent` |
| 51 | 9. **Error codes**: Update error handling to match [Swap v2 error codes](https://developers.jup.ag/docs/swap/order-and-execute.md) |
| 52 | 10. **Test**: Run end-to-end swap on devnet/mainnet with small amount to verify |
| 53 | |
| 54 | ## Sunset |
| 55 | |
| 56 | Remove this skill once Jupiter decommissions the v1 (`/swap/v1`) endpoints and the Ultra (`ultra-api.jup.ag`) domain. At that point all integrations will already be on v2. |
| 57 | |
| 58 | **Review by**: 2026-09-01 — check if v1/Ultra endpoints have been decommissioned. |
| 59 | |
| 60 | ## References |
| 61 | |
| 62 | Migration is split into three profile-targeted guides (the old single `migration` page no longer exists): |
| 63 | |
| 64 | - [Migration: Ultra → /order](https://developers.jup.ag/docs/swap/migration/ultra-to-order.md) |
| 65 | - [Migration: Metis → /build](https://developers.jup.ag/docs/swap/migration/metis-to-build.md) |
| 66 | - [Migration: Metis → Meta-Aggregator (/order + /execute)](https://developers.jup.ag/docs/swap/migration/metis-to-meta-aggregator.md) |
| 67 | - [Order & Execute](https://developers.jup.ag/docs/swap/order-and-execute.md) |
| 68 | - [Build](https://developers.jup.ag/docs/swap/build/index.md) |
| 69 | - [Swap overview](https://developers.jup.ag/docs/swap/index.md) (routing and fees) |
| 70 | - [OpenAPI spec](https://developers.jup.ag/docs/openapi-spec/swap/v2/swap.yaml) |
People who liked this also viewed
6 picksType
- remotion-to-hyperframesPort an existing Remotion (React) composition''s source to HyperFrames HTML. Use ONLY on an explicit ask to port/convert/migrate/translate a Remotion source — one-way, Remotion-only. A passing RemotioSkillsJul 2026
- solana-devUse when user asks to "build a Solana dapp", "write an Anchor program", "create a token", "debug Solana errors", "set up wallet connection", "test my Solana program", "deploy to devnet", or "explain SSkillsJul 2026
- grimoire-polymarketQueries Polymarket market data and CLOB state, and manages CLOB orders via the Grimoire venue CLI wrapper backed by the official Polymarket CLI.SkillsMay 2026
- shopify-storefront-graphqlUse for custom storefronts requiring direct GraphQL queries/mutations for data fetching and cart operations. Choose this when you need full control over data fetching and rendering your own UI. NOT foSkillsJul 2026
- agentic-walletCrypto wallet operations via the awal CLI — sign in, check balances, send USDC/ETH/POL/SOL, trade tokens, fund the wallet, and use the x402 payment protocol to discover paid services, pay for API callSkillsJun 2026
- quicknode-skillQuicknode blockchain infrastructure for 80+ chains: Core RPC API, Streams, Webhooks, Blazar WSS, Solana gRPC, HyperCore gRPC, SQL Explorer, Metaplex DAS API, Blockbook, Ordinals & Runes API, Swap API,SkillsJul 2026
