jupiter-swap-migration

Jupiter Swap 迁移指南

将现有的 Jupiter swap 集成从 Metis（v1） 或 Ultra 迁移到统一的 Swap API v2。

目标基础 URL：https://api.jup.ag/swap/v2 身份验证：来自 developers.jup.ag 的 x-api-key（不变）

适用/不适用场景

适用于：

• 迁移调用 api.jup.ag/swap/v1/quote、api.jup.ag/swap/v1/swap-instructions 或 ultra-api.jup.ag 的代码。
• 将 Jupiter swap 端点更新至 v2。
• 从 Metis 两步流程切换到统一的 /build 或 /order 端点。

不适用于：

• 从头开始构建新的 Jupiter 集成（请改用 integrating-jupiter 技能）。
• 使用非 swap 的 Jupiter API（Lend、Trigger、Recurring 等）。

触发词：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

---

迁移路径

来源	目标	工作量	适用场景
Ultra → /order	GET /swap/v2/order + POST /swap/v2/execute	最少（仅需更改 URL）	Ultra 用户的默认选择
Metis → /build	GET /swap/v2/build	中等（参数和响应映射）	需要交易可组合性
Metis → /order	GET /swap/v2/order + POST /swap/v2/execute	中等（流程变更）	不需要修改交易，希望由服务管理执行

路径详情

每条路径都有专门的示例，包含迁移前后代码、参数映射和响应变更：

• 路径 1：Ultra → /order — 最小化迁移，仅更改基础 URL
• 路径 2：Metis → /build — 将 2 次调用合并为 1 次，并进行参数和响应映射
• 路径 3：Metis → /order — 切换流程，改用由服务管理的执行，并支持多路由器竞争

---

迁移后检查清单

1. URL 审查：在代码库中搜索 ultra-api.jup.ag、/ultra/v1/、/swap/v1/quote、/swap/v1/swap-instructions——这些都应替换
2. 参数重命名：userPublicKey → taker（适用于 /build 路径）
3. 移除 swapMode：V2 仅支持 ExactIn。如果使用 ExactOut，请重新设计流程——此模式已不再提供
4. slippageBps 默认值：如果省略，/build 默认使用 50 bps。对于 /order，如果集成依赖特定值，请确认默认值
5. 响应字段名称：确认代码在处理 /execute 响应时使用 inputAmountResult/outputAmountResult（v2 的规范字段名称）
6. ALT 处理：如果使用 /build，请将 addressLookupTableAddresses（数组）改为 addressesByLookupTableAddress（对象）——删除 RPC ALT 解析代码
7. 费用事件解析：V2 指令不会发出费用事件——请更新依赖此类事件的交易解析器
8. 路由计划格式：如果要解析路由计划，请使用 bps 字段（规范字段），而不是 percent
9. 错误代码：更新错误处理逻辑，使其符合 Swap v2 错误代码
10. 测试：在 devnet/mainnet 上使用小额资金运行端到端 swap，以验证功能

退役

Jupiter 停用 v1（/swap/v1）端点和 Ultra（ultra-api.jup.ag）域名后，请移除本技能。届时所有集成都已迁移至 v2。

复查日期：2026-09-01——检查 v1/Ultra 端点是否已停用。

参考资料

迁移分为三个针对不同配置文件的指南（旧的单一 migration 页面已不再存在）：

• 迁移：Ultra → /order
• 迁移：Metis → /build
• 迁移：Metis → Meta-Aggregator（/order + /execute）
• Order 与 Execute
• Build
• Swap 概览（路由和费用）
• OpenAPI 规范