feat: [swap] unified Swap API V2 documentation by 0xYankee-Raccoons · Pull Request #854 · jup-ag/docs

0xYankee-Raccoons · 2026-03-16T08:57:08Z

Summary

Unified Swap API V2 documentation. New top-level "Swap" section with /order (happy path, managed execution) and /build (advanced path, raw instructions) at api.jup.ag/swap/v2. Existing Ultra and Metis docs preserved as collapsed sub-sections.

Changes

New pages (8)

Overview (docs/swap/index.mdx) — comparison table, decision tree, endpoint summary
Order & Execute (docs/swap/v2/order-and-execute.mdx) — happy path with @solana/kit and @solana/web3.js examples
Build Custom Transactions (docs/swap/v2/build/index.mdx) — advanced path with full code examples for both libraries
Swap Instructions (docs/swap/v2/build/swap-instructions.mdx) — common instructions to compose with /build
Parameters & Routing (docs/swap/v2/parameters.mdx) — per-param routing badges + full routing impact matrix
Fees (docs/swap/v2/fees.mdx) — fee models for both paths (no swap fees on /build)
Advanced Techniques (docs/swap/v2/advanced.mdx) — CU simulation, fast mode, gasless, maxAccounts
Migration Guide (docs/swap/v2/migration.mdx) — Metis → /build, Ultra → /order, V1 → V2 instruction differences

OpenAPI spec

New: openapi-spec/swap/v2/swap.yaml (GET /order, GET /build, POST /execute)
Moved: openapi-spec/swap/swap.yaml → openapi-spec/swap/v1/swap.yaml

API reference (5 new pages)

api-reference/swap.mdx — updated overview with V2 and V1 card groups
api-reference/swap/v2.mdx — V2 overview with endpoint cards
api-reference/swap/v2/order.mdx, build.mdx, execute.mdx — generated from OpenAPI spec
api-reference/swap/v1.mdx — V1 (Metis) overview with endpoint cards

Structural

Metis docs moved to docs/swap/v1/
Metis API ref moved to api-reference/swap/v1/
Nav: "Swap" top-level with V2 primary, Ultra + Metis V1 collapsed
12 redirects for old Metis paths

Linear Issues

Fixes DEVREL-83 — [Docs] Unified Swap API (/swap/v2)

Checklist

node generate-llms-from-docs.js run
mint broken-links passes
All pages have title, description, llmsDescription
docs.json navigation updated
Redirects added for moved paths
Changelog entry added to updates/index.mdx
.claude/rules/ updated with learnings and decisions

Move existing Metis swap pages, API reference, and OpenAPI spec into v1 subdirectories to make room for the new Swap API V2. - docs/swap/*.mdx -> docs/swap/v1/ - api-reference/swap/*.mdx -> api-reference/swap/v1/ - openapi-spec/swap/swap.yaml -> openapi-spec/swap/v1/swap.yaml - Update V1 API ref pages to point to new spec path Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

New OpenAPI 3.0.3 spec for the unified Swap API V2 at api.jup.ag/swap/v2. Three endpoints: GET /order, GET /build, POST /execute. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

8 new pages for the unified Swap API V2: - Overview with comparison table and decision tree - Order & Execute (happy path with @solana/kit and @solana/web3.js examples) - Build Custom Transactions (advanced path with full code examples) - Swap Instructions (common instructions to compose with /build) - Parameters & Routing (per-param routing badges + full routing matrix) - Fees (fee models for both paths) - Advanced Techniques (CU simulation, fast mode, gasless, maxAccounts) - Migration Guide (Metis -> /build, Ultra -> /order, V1 -> V2 differences) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- api-reference/swap.mdx: Updated overview with V2 and V1 card groups - api-reference/swap/v2.mdx: V2 overview with endpoint cards - api-reference/swap/v2/order.mdx: GET /order endpoint (from OpenAPI) - api-reference/swap/v2/build.mdx: GET /build endpoint (from OpenAPI) - api-reference/swap/v2/execute.mdx: POST /execute endpoint (from OpenAPI) - api-reference/swap/v1.mdx: V1 (Metis) overview with endpoint cards Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- New top-level "Swap" nav item replacing "Ultra Swap" - V2 as primary expanded section with all new pages - Ultra Swap collapsed under Swap - Metis V1 collapsed under Swap (pointing to v1/ paths) - API reference: Swap group with V2 and V1 (Metis) sub-groups - 12 redirects for old Metis docs and API reference paths Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Delete original files that were moved to v1/ subdirectories. api-reference/swap.mdx updated in an earlier commit but had unstaged changes from the linter. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove Ultra, Swap V1, Tokens V1, and Price V2 from API Reference nav. Pages remain live but are hidden from discovery: - Add deprecated: true frontmatter to all 22 deprecated API ref pages - Add <Warning> deprecation callouts pointing to replacements - Update llmsDescription with DEPRECATED prefix on overview pages - Modify generate-llms-from-docs.js to skip pages with deprecated: true - Update llms.txt Quick Reference to recommend Swap API V2 - Clean up api-reference/swap.mdx overview (V2 only, no V1 cards) API Reference nav now shows only current versions: - Swap: overview + V2 endpoints - Tokens: overview + V2 endpoints - Price: overview + V3 endpoints Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Add "Deprecating API Versions" workflow to CLAUDE.md (6-step process for phasing out old API versions without breaking links or AI agents) - Drop redundant version overview pages from nav (swap/v2, tokens/v2, price/v3) since top-level overviews cover them - Add llmsDescription to all 3 Swap V2 API reference pages - Add Swap API V2 changelog entry to updates/index.mdx - Regenerate llms.txt Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

0xYankee-Raccoons · 2026-03-16T14:26:00Z

Latest changes (deprecation workflow + API ref cleanup)

Deprecation workflow added to CLAUDE.md

Reusable 6-step process for phasing out old API versions
generate-llms-from-docs.js now skips deprecated: true pages from llms.txt
Old pages stay live (searchable via Mintlify UI) but hidden from nav and AI agents

API Reference nav cleanup

Removed: Ultra, Swap V1, Tokens V1, Price V2 (22 pages deprecated with Warning callouts)
Dropped redundant version overview pages (swap/v2, tokens/v2, price/v3) — top-level overviews cover them
Added llmsDescription to all 3 Swap V2 API ref endpoint pages

Changelog + llms.txt

Swap API V2 changelog entry added to updates/index.mdx
llms.txt Quick Reference updated to recommend Swap V2

All pre-commit checks pass.

…DE.md - Drop redundant version overview pages from nav (swap/v2, tokens/v2, price/v3) — top-level overviews now show endpoint cards directly - Update tokens.mdx and price.mdx overviews to show only current version endpoints (no links to deprecated versions) - Add llmsDescription to tokens and price overview pages - Add "Deprecating API Versions" workflow to CLAUDE.md with expanded context on human vs agentic reader handling - Regenerate llms.txt Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…kflow Apply the deprecation pattern to docs pages (not just API reference): - Add deprecated: true + Warning callout to all 16 docs/ultra/ pages - Add deprecated: true + Warning callout to all 8 docs/swap/v1/ pages - Add llmsDescription with DEPRECATED prefix to both overview pages - All 24 docs pages now excluded from llms.txt Refine CLAUDE.md deprecation workflow: - Applies to both API reference and docs pages - "What to deprecate" decision table for human/Claude to determine scope - Covers collapsed nav sub-sections (keep if needed for hierarchy) - Expanded "When to apply" list including product doc rewrites Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

0xYankee-Raccoons · 2026-03-16T14:48:20Z

Latest: deprecate Ultra + Metis V1 docs pages

Applied the same deprecation pattern to docs pages (not just API reference):

24 docs pages deprecated: 16 under docs/ultra/ + 8 under docs/swap/v1/
All have deprecated: true frontmatter + <Warning> callout pointing to Swap V2
Both overview pages have llmsDescription with DEPRECATED prefix
All 46 deprecated pages total (22 API ref + 24 docs) excluded from llms.txt

CLAUDE.md deprecation workflow refined:

Now applies to both API reference and docs pages
Added "What to deprecate" decision table for human/Claude to determine scope
Covers collapsed nav sub-sections
Expanded "When to apply" list

All pre-commit checks pass.

Drop hidden/undocumented params from V2 spec and docs: - closeAuthority, nozomiTipLamports, gasMint - Advanced integrator fees (feeBps, feeFlat, feeReducer, feeReceiver, feeMint, AdvancedFee schema) - useWsol - All ExactOut references (swapMode enum, routing matrix row, build comparison) Enrich parameter descriptions with bullet points (matching Ultra V1 style): - receiver: ATA behaviour, SOL handling, wSOL limitation - payer: gasless flow implications - excludeDexes: Iris-only caveat - slippageBps/priorityFeeLamports: auto-optimisation notes - referralFee: range 50-255 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…r & execute - Rename docs/swap/v2/build/swap-instructions.mdx to other-instructions.mdx - Update order-and-execute page with improved descriptions Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…cation - Add fee schedule table (0 bps for Jupiter tokens, 2 for SOL-Stable, etc.) - Add fee mint priority list (SOL > Stablecoins > LSTs > Bluechips > Others) - Add full referral account setup guide with code examples (SDK install, create referralAccount, create referralTokenAccount per mint) - Clarify /build feeAccount can be any SPL token account (no referral program account needed) - Add Jupiter 20% integrator fee share note Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replace monolithic Advanced Techniques page with an index linking to 5 standalone pages: - Gasless Swaps: rewritten from Ultra docs, covers both /order (automatic gasless + integrator payer) and /build (payer changes fee payer accounts), no "Ultra" naming, includes scenario matrix - Priority Fees: /order priority fee and Jito tip parameters - Estimate Compute Units: CU simulation pattern for /build - Reduce Transaction Size: maxAccounts + removing no-op createIdempotent - Reduce Latency: fast mode on /build Also: - Add gasless row to overview comparison table - Update payer description in parameters page (Iris only, link to gasless) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Must fix: - Fix blockhash type mismatch in /build kit example (convert byte array to base58 string before passing to setTransactionMessageLifetimeUsingBlockhash) - Fix extra closing parenthesis in overview gasless row Should fix: - Fix V1 index recommending Ultra (now points to Swap API V2) - Fix undefined accountExists in reduce-transaction-size (replaced with concrete ATA existence check pattern) - Fix V1 index internal links to use canonical /docs/swap/v1/ paths - Deduplicate blockhash conversion in web3.js /build example Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Consistency: - Standardise router naming: "Metis" in prose, iris noted once in params - "JupiterZ" used consistently (not alternating with "RFQ") - Remove horizontal rules from order-and-execute - Convert Mode section to Note callout in parameters Editorial: - RTSE: inline explanation (adjusts slippage at execution time) - Jupiter Beam: inline explanation (accelerated sending across RPCs) - Grammar fix: "Parses both successful and failed transactions" - reduce-latency: "extracting" -> "optimising" Cuts: - v1/index: remove marketing paragraphs, Card components, blog links - overview: remove "Two paths" heading Fixes: - compute-units: add getTransactionEncoder import and base64 conversion Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Order & Execute: - Add wallet loading accordion (base58 .env, Solana CLI keyfile, raw bytes) - Split into prerequisites (imports, types, constants) + code example - Expand OrderResponse (outAmount, router, mode, feeBps, feeMint) - Expand ExecuteResponse (code, inputAmountResult, outputAmountResult, error) - Use partiallySignTransaction for kit (JupiterZ MM co-signer) - Standardise BS58_PRIVATE_KEY env var Build Custom Transactions: - Split into prerequisites (types + helpers per library) + code example - Add SOL transfer as custom instruction example (after swap, before cleanup) - Include CU simulation inline (steps 4-5 in kit) - Add CU simulation explanation with Solana fee structure link - Fix build/index.mdx TODO comments - Standardise BS58_PRIVATE_KEY env var Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Routing: - Rename parameters.mdx to routing.mdx (new file, no redirect needed) - Strip parameter tables (duplicates API ref), keep routing overview, impact matrix, and ultra vs manual mode - Update all internal links from parameters -> routing Code examples: - Rewrite order-and-execute with workbench code (kit + web3.js) - Rewrite build with workbench code including CU simulation - Add wallet loading accordion (3 methods: .env, CLI keyfile, raw bytes) - Add SOL transfer as custom instruction example in /build - Standardise BS58_PRIVATE_KEY env var across all pages - Prerequisites/code split structure CPI: - Add full CPI section to other-instructions.mdx from Ultra docs - CPI with jupiter-cpi crate (Rust example) - Flash Fill alternative with flow explanation - GitHub reference links Editorial (from review): - Standardise router naming (Metis everywhere, iris noted once) - RTSE/Jupiter Beam inline explanations - Cut marketing copy from v1/index.mdx - Remove horizontal rules, convert Mode to Note callout - Fix compute-units missing import - Remove "Two paths" heading from overview - Fix V1 internal links to canonical paths Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Remove priority-fees.mdx (not useful as standalone advanced guide) and all links to it - Compute units: rewrite as concise pattern guide, link to Solana fee structure, reference /build code example instead of duplicating code - Reduce transaction size: add Warning for maxAccounts too low (below 50 can cause no route found), add Note about RPC latency cost of ATA existence checks - Reduce latency: add technical details for fast mode (Bellman-Ford with no splitting, parallel getRecentPriorityFee), add Note about priority fee estimation trade-off, expand trade-offs section Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

0xanmol · 2026-03-17T10:38:18Z

Question: Does `/build` return a compute unit limit?

Three sources in this PR say different things:

1. docs/swap/v2/advanced/compute-units.mdx (line 9):

"The /build response includes computeBudgetInstructions with the compute unit price but not the compute unit limit."

2. docs/swap/v2/build/index.mdx (line 525):

"The code example above demonstrates this in steps 4-5 (kit) or is handled automatically by the compute budget instructions (web3.js)."

3. openapi-spec/swap/v2/swap.yaml (computeBudgetInstructions field):

description: "Compute unit price and limit instructions"

The code examples also diverge:

Kit example simulates CU usage, builds its own SetComputeUnitLimit instruction at 1.2x the simulated value, then adds the CU price from the response (steps 4-5)
Web3.js example uses computeBudgetInstructions from the response as-is, with no simulation

These can't both be right:

If the response does not include a CU limit: the web3.js example is missing simulation, and the OpenAPI description is wrong
If the response does include a CU limit: the kit example adds a redundant limit instruction, and the compute-units docs page is misleading

Can you clarify what /build actually returns so we can align all three sources and both code examples?

Answer: /build returns compute unit price only, not limit. Confirmed from source code (build/index.ts line 296: computeBudgetInstructions: [setComputeUnitPrice(cup)]).

All three inconsistencies fixed:

OpenAPI spec → "Compute unit price instruction (does not include compute unit limit)" (e19fe96)
build/index.mdx "handled automatically" → removed, clarified both examples now simulate (e19fe96)
Web3.js example → added full CU simulation matching kit pattern (e623c28)

- Fix typo: expanadable -> expandable in build code block (broke Mintlify collapse) - Fix em dash in build code comment (style guide) - Fix inconsistent slippageBps: add to web3.js /build example to match kit example - Fix unescaped $ in gasless llmsDescription - Delete redundant api-reference/swap/v2.mdx (merged base URL + API key info into swap overview) - Remove api-reference/swap/v2 from docs.json nav

- Revert \$ -> $ in gasless.mdx llmsDescription (YAML doesn't support \$ escape sequences, causing Mintlify parse failure) - Update style guide: frontmatter is YAML, body is markdown, escaping rules differ. Don't use markdown escaping in YAML frontmatter. - Add .env and audit/ to .gitignore

0xYankee-Raccoons · 2026-03-17T13:02:14Z

Answer: `/build` returns compute unit price only, not limit

Confirmed from source code (ultra-api/src/routes/build/index.ts, line 296):

computeBudgetInstructions: [setComputeUnitPrice(cup)],

The computeBudgetInstructions array contains one instruction: setComputeUnitPrice. No setComputeUnitLimit is included.

What this means for the three inconsistencies:

Source	Current state	Fix
`compute-units.mdx`	"price but not limit"	Correct, no change needed
`build/index.mdx` line 163	"handled automatically by the compute budget instructions (web3.js)"	Wrong — will fix. The web3.js example includes `computeBudgetInstructions` as-is (which only sets the price, not the limit). This means the web3.js example sends with no explicit CU limit, relying on the Solana runtime default.
OpenAPI spec (`computeBudgetInstructions` description)	"Compute unit price and limit instructions"	Wrong — will fix to "Compute unit price instruction"

What happens without a CU limit?

If no SetComputeUnitLimit instruction is present, Solana uses a default of 200,000 CU per instruction × number of instructions. For a typical swap with 5-6 instructions, that's ~1M CU — which is usually enough but not optimal for fee calculation.

Action items:

Fix OpenAPI spec description: "Compute unit price and limit instructions" → "Compute unit price instruction"
Fix build/index.mdx line 163: remove "handled automatically" claim
Optionally: add CU simulation to the web3.js example to match the kit example (separate commit since it's a larger change)

Source confirmed: computeBudgetInstructions contains only setComputeUnitPrice (build/index.ts line 296). - Fix OpenAPI spec: "Compute unit price and limit" -> "Compute unit price instruction (does not include compute unit limit)" - Fix build/index.mdx: remove "handled automatically" claim for web3.js, clarify web3.js needs manual CU simulation for production - Update response fields table description Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

The web3.js example was using computeBudgetInstructions as-is (which only includes CU price, not limit). Now matches the kit example: - Step 4: simulate with ComputeBudgetProgram.setComputeUnitLimit at max - Step 5: rebuild with 1.2x simulated value + CU price from response - Add ComputeBudgetProgram and COMPUTE_UNIT_LIMIT_MAX to prerequisites - Update "How it works" section to reference both examples Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

0xYankee-Raccoons and others added 7 commits March 16, 2026 16:55

feat: add Swap API V2 OpenAPI spec

10df270

New OpenAPI 3.0.3 spec for the unified Swap API V2 at api.jup.ag/swap/v2. Three endpoints: GET /order, GET /build, POST /execute. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

chore: regenerate llms.txt

48f107c

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

chore: remove old Metis files replaced by v1 sub-section

869d0a1

Delete original files that were moved to v1/ subdirectories. api-reference/swap.mdx updated in an earlier commit but had unstaged changes from the linter. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

mintlify bot deployed to staging March 16, 2026 08:58 View deployment

mintlify bot deployed to staging March 16, 2026 14:05 View deployment

mintlify bot deployed to staging March 16, 2026 14:26 View deployment

mintlify bot deployed to staging March 16, 2026 14:36 View deployment

mintlify bot deployed to staging March 16, 2026 14:48 View deployment

mintlify bot deployed to staging March 16, 2026 16:07 View deployment

0xYankee-Raccoons and others added 3 commits March 17, 2026 00:49

refactor: rename swap-instructions to other-instructions, update orde…

283739f

…r & execute - Rename docs/swap/v2/build/swap-instructions.mdx to other-instructions.mdx - Update order-and-execute page with improved descriptions Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

mintlify bot deployed to staging March 16, 2026 16:50 View deployment

mintlify bot deployed to staging March 17, 2026 00:33 View deployment

fix: update broken links from swap-instructions to other-instructions

e3bf08e

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

mintlify bot deployed to staging March 17, 2026 01:10 View deployment

mintlify bot deployed to staging March 17, 2026 02:29 View deployment

0xYankee-Raccoons and others added 2 commits March 17, 2026 10:53

fix: order and execute code examples

7099785

mintlify bot deployed to staging March 17, 2026 06:28 View deployment

mintlify bot deployed to staging March 17, 2026 07:43 View deployment

mintlify bot deployed to staging March 17, 2026 08:05 View deployment

Merge branch 'main' into feat/swap-v2-docs

f18bb8c

mintlify bot deployed to staging March 17, 2026 08:08 View deployment

0xYankee-Raccoons requested a review from 0xanmol March 17, 2026 08:27

fix: remove ultra and metis from api ref overview

b16f6ea

mintlify bot deployed to staging March 17, 2026 08:31 View deployment

fix: userPublicKey in /build is now taker

7ffb82d

mintlify bot deployed to staging March 17, 2026 08:58 View deployment

0xanmol added 2 commits March 17, 2026 18:43

mintlify bot deployed to staging March 17, 2026 12:54 View deployment

mintlify bot deployed to staging March 17, 2026 13:10 View deployment

mintlify bot deployed to staging March 17, 2026 13:42 View deployment

boxme approved these changes Mar 17, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: [swap] unified Swap API V2 documentation#854

feat: [swap] unified Swap API V2 documentation#854
0xYankee-Raccoons wants to merge 29 commits intomainfrom
feat/swap-v2-docs

0xYankee-Raccoons commented Mar 16, 2026 •

edited by 0xanmol

Loading

Uh oh!

0xYankee-Raccoons commented Mar 16, 2026

Uh oh!

0xYankee-Raccoons commented Mar 16, 2026

Uh oh!

0xanmol commented Mar 17, 2026 •

edited by 0xYankee-Raccoons

Loading

Uh oh!

0xYankee-Raccoons commented Mar 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

0xYankee-Raccoons commented Mar 16, 2026 • edited by 0xanmol Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

New pages (8)

OpenAPI spec

API reference (5 new pages)

Structural

Linear Issues

Checklist

Uh oh!

0xYankee-Raccoons commented Mar 16, 2026

Latest changes (deprecation workflow + API ref cleanup)

Uh oh!

0xYankee-Raccoons commented Mar 16, 2026

Latest: deprecate Ultra + Metis V1 docs pages

Uh oh!

0xanmol commented Mar 17, 2026 • edited by 0xYankee-Raccoons Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Question: Does /build return a compute unit limit?

Uh oh!

0xYankee-Raccoons commented Mar 17, 2026

Answer: /build returns compute unit price only, not limit

What this means for the three inconsistencies:

What happens without a CU limit?

Action items:

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

0xYankee-Raccoons commented Mar 16, 2026 •

edited by 0xanmol

Loading

0xanmol commented Mar 17, 2026 •

edited by 0xYankee-Raccoons

Loading

Question: Does `/build` return a compute unit limit?

Answer: `/build` returns compute unit price only, not limit