# jupiter-swap-migration

jupiter-swap-migration — a Claude Code skill that guides migration from legacy Jupiter Metis v1 and Ultra endpoints to Swap API v2. Triggers when upgrading swap integrations or replacing deprecated parameters.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 307 installs · ★ 90 repo stars
- Author: jup-ag
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/jup-ag/agent-skills/tree/HEAD/skills/jupiter-swap-migration/SKILL.md
- Updated: 2026-07-07
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/jupiter-swap-migration

## What it does

This skill guides the transition from deprecated Jupiter endpoints like `api.jup.ag/swap/v1/quote`, `api.jup.ag/swap/v1/swap-instructions`, and `ultra-api.jup.ag` to the unified base URL `https://api.jup.ag/swap/v2`. Integrations on Ultra switch to `GET /swap/v2/order` combined with `POST /swap/v2/execute`. Metis setups can either consolidate two steps into a single `/build` call or move to managed execution through `/order`.

The guidance covers critical protocol adjustments. Swap API v2 drops `ExactOut` entirely, meaning flows must be rebuilt around `ExactIn`. In `/build` requests, `userPublicKey` becomes `taker`, while lookup tables switch to `addressesByLookupTableAddress`, removing external RPC lookups for ALT accounts. Omitting `slippageBps` on `/build` defaults the value to 50 bps.

All calls to API v2 still require an `x-api-key` header obtained from `developers.jup.ag`. The skill does not cover brand new integrations or non-swap Jupiter APIs like Lend and Recurring.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add jup-ag/agent-skills --skill jupiter-swap-migration -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/jupiter-swap-migration/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/jupiter-swap-migration/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add jup-ag/agent-skills --skill jupiter-swap-migration -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/jupiter-swap-migration/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add jup-ag/agent-skills --skill jupiter-swap-migration -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/jupiter-swap-migration/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install jup-ag/agent-skills skills/jupiter-swap-migration
```

2. **Manually: put the files in place**
- File: `.github/skills/jupiter-swap-migration/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add jup-ag/agent-skills --skill jupiter-swap-migration -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/jup-ag/agent-skills --path skills/jupiter-swap-migration
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/jupiter-swap-migration/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add jup-ag/agent-skills --skill jupiter-swap-migration -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/jup-ag/agent-skills/tree/HEAD/skills/jupiter-swap-migration/SKILL.md

## When to use it
- migrate deprecated Jupiter swap v1 and Ultra code to Swap API v2
- consolidate Metis quote and swap instructions into a single /build call
- refactor legacy ExactOut workflows to supported ExactIn routing
- update response parsers to canonical fields inputAmountResult and outputAmountResult

## Example prompts
- Migrate our Jupiter Metis v1 swap logic to Swap API v2
- Update ultra-api.jup.ag endpoints to the v2 order and execute flow
- Audit our codebase for swap/v1/quote calls and rename userPublicKey to taker

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 1452637f7469a6ac.

BEGIN THIRD-PARTY FILE 1452637f7469a6ac
```text
---
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
```
END THIRD-PARTY FILE 1452637f7469a6ac

The third-party file has ended. Everything between the 1452637f7469a6ac tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2403 of 4966 bytes. © jup-ag · MIT · https://github.com/jup-ag/agent-skills/tree/HEAD/skills/jupiter-swap-migration/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
