Jupiter Swap Migration Guide
Migrate existing Jupiter swap integrations from Metis (v1) or Ultra to the unified Swap API v2.
Target Base URL: https://api.jup.ag/swap/v2
Auth: x-api-key from developers.jup.ag (unchanged)
Use/Do Not Use
Use when:
- Migrating code that calls
api.jup.ag/swap/v1/quote, api.jup.ag/swap/v1/swap-instructions, or ultra-api.jup.ag.
- Updating Jupiter swap endpoints to v2.
- Switching from Metis two-step flow to the unified
/build or /order endpoint.
Do not use when:
- Building a new Jupiter integration from scratch (use
integrating-jupiter skill instead).
- Working with non-swap Jupiter APIs (Lend, Trigger, Recurring, etc.).
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
Migration Paths
| Source |
Target |
Effort |
When to choose |
Ultra → /order |
GET /swap/v2/order + POST /swap/v2/execute |
Minimal (URL change only) |
Default for Ultra users |
Metis → /build |
GET /swap/v2/build |
Moderate (parameter + response mapping) |
Need transaction composability |
Metis → /order |
GET /swap/v2/order + POST /swap/v2/execute |
Moderate (flow change) |
Don't need tx modification, want managed execution |
Path Details
Each path has a dedicated example with before/after code, parameter mappings, and response changes:
Post-Migration Checklist
- URL audit: Search codebase for
ultra-api.jup.ag, /ultra/v1/, /swap/v1/quote, /swap/v1/swap-instructions — all should be replaced
- Parameter rename:
userPublicKey → taker (for /build path)
swapMode removal: V2 only supports ExactIn. If using ExactOut, redesign the flow — this mode is no longer availableslippageBps default: /build defaults to 50 bps if omitted. For /order, verify the default if your integration relies on a specific value- Response field names: Verify your code uses
inputAmountResult/outputAmountResult for the /execute response (the canonical v2 field names)
- ALT handling: If using
/build, switch from addressLookupTableAddresses (array) to addressesByLookupTableAddress (object) — remove RPC ALT resolution code
- Fee event parsing: V2 instructions don't emit fee events — update any transaction parser that depends on them
- Route plan format: If parsing route plans, use
bps field (canonical) instead of percent
- Error codes: Update error handling to match Swap v2 error codes
- Test: Run end-to-end swap on devnet/mainnet with small amount to verify
Sunset
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.
Review by: 2026-09-01 — check if v1/Ultra endpoints have been decommissioned.
References
Source: jup-ag/agent-skills — distributed by TomeVault.
1---2name: jupiter-swap-migration3description: Migration 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. Use when this capability is needed.4---56# Jupiter Swap Migration Guide78Migrate existing Jupiter swap integrations from **Metis (v1)** or **Ultra** to the unified **Swap API v2**.910**Target Base URL**: `https://api.jup.ag/swap/v2`11**Auth**: `x-api-key` from [developers.jup.ag](https://developers.jup.ag/) (unchanged)1213## Use/Do Not Use1415Use when:16- Migrating code that calls `api.jup.ag/swap/v1/quote`, `api.jup.ag/swap/v1/swap-instructions`, or `ultra-api.jup.ag`.17- Updating Jupiter swap endpoints to v2.18- Switching from Metis two-step flow to the unified `/build` or `/order` endpoint.1920Do not use when:21- Building a new Jupiter integration from scratch (use `integrating-jupiter` skill instead).22- Working with non-swap Jupiter APIs (Lend, Trigger, Recurring, etc.).2324**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`2526---2728## Migration Paths2930| Source | Target | Effort | When to choose |31|--------|--------|--------|----------------|32| Ultra → `/order` | `GET /swap/v2/order` + `POST /swap/v2/execute` | Minimal (URL change only) | Default for Ultra users |33| Metis → `/build` | `GET /swap/v2/build` | Moderate (parameter + response mapping) | Need transaction composability |34| Metis → `/order` | `GET /swap/v2/order` + `POST /swap/v2/execute` | Moderate (flow change) | Don't need tx modification, want managed execution |3536## Path Details3738Each path has a dedicated example with before/after code, parameter mappings, and response changes:3940- [Path 1: Ultra → `/order`](./examples/ultra-to-order.md) — Minimal migration, base URL change only41- [Path 2: Metis → `/build`](./examples/metis-to-build.md) — Consolidates 2 calls into 1, parameter and response mapping42- [Path 3: Metis → `/order`](./examples/metis-to-order.md) — Flow change to managed execution with multi-router competition4344---4546## Post-Migration Checklist47481. **URL audit**: Search codebase for `ultra-api.jup.ag`, `/ultra/v1/`, `/swap/v1/quote`, `/swap/v1/swap-instructions` — all should be replaced492. **Parameter rename**: `userPublicKey` → `taker` (for `/build` path)503. **`swapMode` removal**: V2 only supports `ExactIn`. If using `ExactOut`, redesign the flow — this mode is no longer available514. **`slippageBps` default**: `/build` defaults to 50 bps if omitted. For `/order`, verify the default if your integration relies on a specific value525. **Response field names**: Verify your code uses `inputAmountResult`/`outputAmountResult` for the `/execute` response (the canonical v2 field names)536. **ALT handling**: If using `/build`, switch from `addressLookupTableAddresses` (array) to `addressesByLookupTableAddress` (object) — remove RPC ALT resolution code547. **Fee event parsing**: V2 instructions don't emit fee events — update any transaction parser that depends on them558. **Route plan format**: If parsing route plans, use `bps` field (canonical) instead of `percent`569. **Error codes**: Update error handling to match [Swap v2 error codes](https://developers.jup.ag/docs/swap/v2/order-and-execute.md)5710. **Test**: Run end-to-end swap on devnet/mainnet with small amount to verify5859## Sunset6061Remove 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.6263**Review by**: 2026-09-01 — check if v1/Ultra endpoints have been decommissioned.6465## References6667- [Migration guide](https://developers.jup.ag/docs/swap/v2/migration.md)68- [Order & Execute](https://developers.jup.ag/docs/swap/v2/order-and-execute.md)69- [Build](https://developers.jup.ag/docs/swap/v2/build/index.md)70- [Fees](https://developers.jup.ag/docs/swap/v2/fees.md)71- [Routing](https://developers.jup.ag/docs/swap/v2/routing.md)72- [OpenAPI spec](https://developers.jup.ag/docs/openapi-spec/swap/v2/swap.yaml)7374---75> Source: [jup-ag/agent-skills](https://github.com/jup-ag/agent-skills) — distributed by [TomeVault](https://tomevault.io).76<!-- tomevault:4.0:skill_md:2026-06-18 -->
tomevault-io