internet-court/internet-court-skill / vendored/jupiter/jupiter-swap-migration
jupiter-swap-migration
VerifiedMigration 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.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 1.0 KB |
| README.md | markdown | 1.1 KB |
| SKILL.md | skill md | 4.8 KB |
| examples/metis-to-build.md | markdown | 4.2 KB |
| examples/metis-to-order.md | markdown | 2.4 KB |
| examples/ultra-to-order.md | markdown | 2.1 KB |
SKILL.md
View on GitHub---
name: jupiter-swap-migration
description: 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.
license: MIT
metadata:
author: jup-ag
version: "1.1.0"
tags:
- jupiter
- swap-migration
- metis
- ultra
- swap-v2
- jup-ag
---
# 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](https://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:
- [Path 1: Ultra → `/order`](./examples/ultra-to-order.md) — Minimal migration, base URL change only
- [Path 2: Metis → `/build`](./examples/metis-to-build.md) — Consolidates 2 calls into 1, parameter and response mapping
- [Path 3: Metis → `/order`](./examples/metis-to-order.md) — Flow change to managed execution with multi-router competition
---
## Post-Migration Checklist
1. **URL audit**: Search codebase for `ultra-api.jup.ag`, `/ultra/v1/`, `/swap/v1/quote`, `/swap/v1/swap-instructions` — all should be replaced
2. **Parameter rename**: `userPublicKey` → `taker` (for `/build` path)
3. **`swapMode` removal**: V2 only supports `ExactIn`. If using `ExactOut`, redesign the flow — this mode is no longer available
4. **`slippageBps` default**: `/build` defaults to 50 bps if omitted. For `/order`, verify the default if your integration relies on a specific value
5. **Response field names**: Verify your code uses `inputAmountResult`/`outputAmountResult` for the `/execute` response (the canonical v2 field names)
6. **ALT handling**: If using `/build`, switch from `addressLookupTableAddresses` (array) to `addressesByLookupTableAddress` (object) — remove RPC ALT resolution code
7. **Fee event parsing**: V2 instructions don't emit fee events — update any transaction parser that depends on them
8. **Route plan format**: If parsing route plans, use `bps` field (canonical) instead of `percent`
9. **Error codes**: Update error handling to match [Swap v2 error codes](https://developers.jup.ag/docs/swap/order-and-execute.md)
10. **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
Migration is split into three profile-targeted guides (the old single `migration` page no longer exists):
- [Migration: Ultra → /order](https://developers.jup.ag/docs/swap/migration/ultra-to-order.md)
- [Migration: Metis → /build](https://developers.jup.ag/docs/swap/migration/metis-to-build.md)
- [Migration: Metis → Meta-Aggregator (/order + /execute)](https://developers.jup.ag/docs/swap/migration/metis-to-meta-aggregator.md)
- [Order & Execute](https://developers.jup.ag/docs/swap/order-and-execute.md)
- [Build](https://developers.jup.ag/docs/swap/build/index.md)
- [Swap overview](https://developers.jup.ag/docs/swap/index.md) (routing and fees)
- [OpenAPI spec](https://developers.jup.ag/docs/openapi-spec/swap/v2/swap.yaml)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |