From 700594497d3cebfedba4bcc36cb0a1e6d840cb79 Mon Sep 17 00:00:00 2001 From: YY <0xyankee@gmail.com> Date: Tue, 30 Jun 2026 18:39:10 +0800 Subject: [PATCH 1/8] docs: [ai] add Jupiter Trading MCP page Document the hosted Jupiter Trading MCP server (mcp.jup.ag): 47 tools across 8 domains, Bearer-token auth, and setup for Claude Desktop, Claude Code, Cursor, and Windsurf. Wire it into the AI nav and the AI overview card. Include a findings report cross-checking the MCP against current docs. Co-Authored-By: Claude Opus 4.8 (1M context) --- ai/index.mdx | 4 +- ai/trading-mcp.mdx | 167 ++++++++++++++++++++++++++++++++++++++++++++ docs.json | 1 + jup-mcp-findings.md | 105 ++++++++++++++++++++++++++++ llms.txt | 1 + 5 files changed, 276 insertions(+), 2 deletions(-) create mode 100644 ai/trading-mcp.mdx create mode 100644 jup-mcp-findings.md diff --git a/ai/index.mdx b/ai/index.mdx index efaaaf16..c7a58a18 100644 --- a/ai/index.mdx +++ b/ai/index.mdx @@ -47,7 +47,7 @@ For agents that interact with Jupiter directly - swap tokens, check prices, plac Trade from your terminal, Telegram, or through AI agents. Non-interactive, JSON-native, designed for both humans and LLMs. - - Execute Jupiter operations via MCP from any hosted platform. Coming soon. + + Execute Jupiter operations via MCP from any client. Swap, trade, lend, and read positions. diff --git a/ai/trading-mcp.mdx b/ai/trading-mcp.mdx new file mode 100644 index 00000000..09bcb8a8 --- /dev/null +++ b/ai/trading-mcp.mdx @@ -0,0 +1,167 @@ +--- +title: "Jupiter Trading MCP" +sidebarTitle: "Trading MCP" +description: "Execute Jupiter trades and DeFi operations from any MCP client." +llmsDescription: "Jupiter's hosted Trading MCP server at https://mcp.jup.ag gives AI agents access to Jupiter's trading infrastructure through the Model Context Protocol. It exposes 47 tools across 8 domains: Swap (quote, execute), Tokens (search, discovery), Price, Trigger (limit orders), Recurring (DCA), Lend (earn yield), Prediction (prediction markets), and Portfolio (positions, staked JUP). Authentication is a stateless per-request Bearer token set to your Jupiter API key from the Developer Platform; the server stores no keys. Transport is HTTP (Streamable HTTP). Covers setup for Claude Desktop, Claude Code, Cursor, and Windsurf, plus example prompts. This is the read-write operations server, distinct from the read-only Documentation MCP." +--- + +The Jupiter Trading MCP is a hosted [Model Context Protocol](https://modelcontextprotocol.io/) server that lets AI agents trade and run DeFi operations on Jupiter. Connect any MCP client to `https://mcp.jup.ag`, authenticate with your Jupiter API key, and your agent can swap tokens, place orders, lend, and read on-chain positions. + + +This server executes operations. For an AI assistant that searches and reads Jupiter's documentation instead, see the read-only [Documentation MCP](/ai/mcp). + + +## What You Can Do + +The server exposes **47 tools across 8 domains**. Your MCP client discovers them automatically once connected. + +| Domain | What it does | +|:-------|:-------------| +| **Swap** | Get a quote and a ready-to-sign transaction, then execute the swap with managed landing. | +| **Tokens** | Search tokens by name, symbol, or mint, and list tokens by tag, category, or recent listings. | +| **Price** | Fetch real-time USD prices, liquidity, and 24h change for one or more tokens. | +| **Trigger** | Create, cancel, and list limit orders that execute when a token hits a target price. | +| **Recurring** | Set up and manage dollar-cost averaging (DCA) orders that buy at regular intervals. | +| **Lend** | Deposit into and withdraw from Jupiter Lend to earn yield, and read your lending positions. | +| **Prediction** | Browse prediction market events, place and close bets, and claim payouts. | +| **Portfolio** | Read a wallet's positions across Solana protocols and its staked JUP. | + +## Get a Jupiter API Key + +The server authenticates every request with your own Jupiter API key. Create one in the [Developer Platform](https://developers.jup.ag/portal). This key is the Bearer token in the setup below. The server forwards it to Jupiter's API on your behalf and never stores it, so you use your own rate limits and permissions. + +## Connect Your Client + +Add the server to your MCP client's configuration. The key detail is passing your Jupiter API key as a Bearer token in the `Authorization` header. Replace `YOUR_JUPITER_API_KEY` with your key in every example. + + + + Open **Settings > Developer > Edit Config** and add: + + ```json + { + "mcpServers": { + "jupiter": { + "type": "http", + "url": "https://mcp.jup.ag", + "headers": { + "Authorization": "Bearer YOUR_JUPITER_API_KEY" + } + } + } + } + ``` + + Restart Claude Desktop to load the server. + + + + Add the server from your terminal: + + ```bash + claude mcp add --transport http jupiter https://mcp.jup.ag --header "Authorization: Bearer YOUR_JUPITER_API_KEY" + ``` + + Or add it manually to `.claude/settings.json`: + + ```json + { + "mcpServers": { + "jupiter": { + "type": "http", + "url": "https://mcp.jup.ag", + "headers": { + "Authorization": "Bearer YOUR_JUPITER_API_KEY" + } + } + } + } + ``` + + Verify with: + + ```bash + claude mcp list + ``` + + + + Open **Settings > MCP** and add a new server, or edit `.cursor/mcp.json`: + + ```json + { + "mcpServers": { + "jupiter": { + "url": "https://mcp.jup.ag", + "headers": { + "Authorization": "Bearer YOUR_JUPITER_API_KEY" + } + } + } + } + ``` + + Save and reload Cursor. + + + + Open **Settings > MCP** and add a new server, or edit `~/.codeium/windsurf/mcp_config.json`: + + ```json + { + "mcpServers": { + "jupiter": { + "serverUrl": "https://mcp.jup.ag", + "headers": { + "Authorization": "Bearer YOUR_JUPITER_API_KEY" + } + } + } + } + ``` + + Save and restart Windsurf. + + + +### Other MCP-Compatible Tools + +Any tool that supports the MCP protocol can connect to `https://mcp.jup.ag` over HTTP transport, with the Jupiter API key in the `Authorization: Bearer` header. + +## Authentication + +Authentication is stateless: each request carries your Jupiter API key as a Bearer token, and the server stores nothing. + +- Pass the key on every request via the `Authorization: Bearer YOUR_JUPITER_API_KEY` header. +- Requests without a valid Bearer token receive a `401 Unauthorized` response. +- The MCP endpoint is `https://mcp.jup.ag`. A separate `GET /health` endpoint needs no auth. + +## Example Prompts + +Once connected, ask your AI assistant in plain language. Each prompt maps to one or more tools. + +| Prompt | Tools used | +|:-------|:-----------| +| "What is the current price of SOL and JUP?" | `price_get` | +| "Swap 10 USDC for SOL" | `swap_get_order`, then `swap_execute_order` | +| "Place a limit order to sell 50 USDC for SOL at the current price." | `trigger_build_order` | +| "DCA 100 USDC into SOL daily for 10 days." | `recurring_build_order` | +| "What tokens can I lend on Jupiter and what APY do they offer?" | `lend_list_tokens` | +| "Are there any prediction markets about Bitcoin?" | `prediction_search_events` | + +Trading prompts that move funds return an unsigned transaction. Your client signs it with your wallet and submits it, so you stay in control of every transaction. + + +If a tool call returns `401 Unauthorized`, check that the `Authorization: Bearer` header is set correctly in your client config. + + +## Resources + + + + Create the Jupiter API key used as your Bearer token. + + + The read-only server for searching and querying Jupiter docs. + + diff --git a/docs.json b/docs.json index 6fb6cd9c..9b221bc1 100644 --- a/docs.json +++ b/docs.json @@ -591,6 +591,7 @@ "ai/llms-txt", "ai/skills", "ai/mcp", + "ai/trading-mcp", "ai/cli" ] } diff --git a/jup-mcp-findings.md b/jup-mcp-findings.md new file mode 100644 index 00000000..434c2874 --- /dev/null +++ b/jup-mcp-findings.md @@ -0,0 +1,105 @@ +# Jupiter Trading MCP — findings report + +Cross-check of the `jup-ag/jup-mcp` server (source + live endpoint) against the current Jupiter +developer docs. Produced while documenting the server for [DEV-480](https://linear.app/raccoons/issue/DEV-480). + +**Working document — not part of the published docs site. Do not add to `docs.json`.** + +Method: read every tool file under `jup-ag/jup-mcp` `src/tools//*.ts` (tool name, +description, the Jupiter REST path it calls), the repo README, and probed the live endpoint. +Compared against the current docs under this repo and `.claude/rules/product-learning.md`. + +Date: 2026-06-30. MCP commit: `main` HEAD at time of check. + +--- + +## Summary + +- The server is **live** at `https://mcp.jup.ag` (`GET /health` → `200`). +- **47 tools across 8 domains**, confirmed from source. +- Most domains call the **current** API version (price v3, swap v2, tokens v2). The one real + staleness flag is **Trigger**, which calls the unmaintained `/trigger/v1/*` API. +- The DEV-480 description has several inaccuracies (endpoint, Prediction count, tokens/trigger/lend + domain descriptions) — corrected in section A. + +--- + +## A. DEV-480 description errors (fix in the issue) + +| # | Issue says | Reality (source / live) | +|---|------------|--------------------------| +| 1 | Hosted at `api.jup.ag/mcp` (once live) | Live now at `https://mcp.jup.ag`. `api.jup.ag/mcp` returns `404`. | +| 2 | "Blocked: waiting for the hosted server to be live" | Unblock — `https://mcp.jup.ag/health` returns `200`. | +| 3 | Prediction = 19 tools | Prediction = **20** tools. (Grand total of 47 is correct; the per-domain breakdown summed to 46.) | +| 4 | Tokens (4): "search tokens, get info, validate addresses, get top tokens" | Actual 4 tools: `tokens_search`, `tokens_list_by_tag`, `tokens_list_by_category`, `tokens_list_recent`. There is **no "validate addresses" tool**. | +| 5 | Trigger (5): "create/cancel/list limit orders & DCA" | Trigger = **limit orders only**. **DCA is the separate Recurring domain** (4 tools). | +| 6 | Lend (7): "lending/borrowing via marginfi" | Jupiter Lend is **Jupiter-owned** (Fluid-based per product-learning), **not marginfi**. The MCP exposes the **Earn side only** (deposit/withdraw/mint/redeem/positions/earnings/tokens). **No borrow tools.** | + +Auth / transport claims in the issue are **accurate**: stateless per-request Bearer token = your +Jupiter API key from portal.jup.ag; the server never stores it and forwards it as `x-api-key` to +`api.jup.ag`. Transport is HTTP (`type: http`, Streamable HTTP). + +--- + +## B. MCP-vs-docs staleness (flag to the MCP / Labs team) + +### F1 — high: Trigger tools use the unmaintained Trigger V1 API +All 5 trigger tools call `/trigger/v1/*`: + +| Tool | Path | +|------|------| +| `trigger_build_order` | `POST /trigger/v1/createOrder` | +| `trigger_build_cancel` | `POST /trigger/v1/cancelOrder` | +| `trigger_build_cancel_batch` | `POST /trigger/v1/cancelOrders` | +| `trigger_execute` | `POST /trigger/v1/execute` | +| `trigger_list_orders` | `GET /trigger/v1/getTriggerOrders` | + +Our docs mark **Trigger V1 as unmaintained** (superseded by Trigger V2: `api.jup.ag/trigger/v2`, +vault-based, JWT challenge-response, `/orders/price`). Trigger V1 still works, so the MCP is +functional, but it is a generation behind the current product. The docs page describes this as +generic "limit orders" and does not claim V2. + +### F2 — low (cosmetic): em dashes in tool descriptions +`prediction_get_trade_history`, `prediction_list_trades`, `swap_get_instructions`, and +`tokens_search` contain em dashes in their `description` strings. Conflicts with our style guide +if we ever lift this copy into docs. Upstream-repo concern only. + +--- + +## C. Docs gaps the MCP surfaces (our docs should answer) + +### G1 — Recurring minimums under-documented +`recurring_build_order` states and the schema enforces: **100 USD total order, at least 2 cycles, +50 USD per cycle** (schema: `numberOfOrders >= 2`, `interval >= 60s`). Our `recurring/` docs only +document the **100 USD total** minimum. + +Action (follow-up, out of scope for the docs-page PR unless requested): verify the 50 USD/cycle +and 2-cycle minimums against the live API / `recurring` source, then add them to +`recurring/best-practices.mdx` and record a `product-learning.md` entry. + +--- + +## D. Confirmed current / consistent (no action) + +| Domain | MCP path | Docs status | +|--------|----------|-------------| +| Price | `GET /price/v3` (max 50 mints, 24h change) | Current. Matches `price/index.mdx`. | +| Swap | `GET /swap/v2/order`, `GET /swap/v2/build`, `POST /swap/v2/execute` | Current V2. `/build` Metis-only / no-RFQ matches docs. | +| Tokens | `GET /tokens/v2/search \| /tag \| /{category}/{interval} \| /recent` | Current V2. (Minor: `tokens_search` omits the comma-separated batch-by-mint up-to-100 capability our docs note — tool-richness nit, not staleness.) | +| Recurring | `POST /recurring/v1/*`, `GET /recurring/v1/getRecurringOrders` | V1 is the only public version. Consistent. | +| Lend | `/lend/v1/earn/*` (deposit, withdraw, mint, redeem, positions, earnings, tokens) | Earn side, current. Correctly labelled "Jupiter Lend/Earn" in source. | +| Prediction | `/prediction/v1/*` (20 tools) | V1 beta. Amount in micro USD (1,000,000 = $1.00); price 0–1. Consistent. | +| Portfolio | `GET /portfolio/v1/platforms`, `/positions/{address}`, `/staked-jup/{address}` | V1 beta. Matches `portfolio/index.mdx` exactly. | + +--- + +## Tool inventory (47 total) + +- **Swap (3):** `swap_get_order`, `swap_get_instructions`, `swap_execute_order` +- **Tokens (4):** `tokens_search`, `tokens_list_by_tag`, `tokens_list_by_category`, `tokens_list_recent` +- **Price (1):** `price_get` +- **Trigger (5):** `trigger_build_order`, `trigger_build_cancel`, `trigger_build_cancel_batch`, `trigger_execute`, `trigger_list_orders` +- **Recurring (4):** `recurring_build_order`, `recurring_build_cancel`, `recurring_execute`, `recurring_list_orders` +- **Lend (7):** `lend_build_deposit`, `lend_build_withdraw`, `lend_build_mint_shares`, `lend_build_redeem_shares`, `lend_get_positions`, `lend_get_earnings`, `lend_list_tokens` +- **Prediction (20):** events (`get_event`, `list_events`, `search_events`, `list_suggested_events`), markets (`get_market`, `list_markets`, `get_orderbook`), orders (`build_order`, `list_orders`, `get_order`, `get_order_status`), positions (`list_positions`, `get_position`, `build_close_position`, `build_close_all_positions`, `build_claim_payout`), profile/feed (`get_profile`, `get_leaderboard`, `get_trade_history`, `list_trades`) +- **Portfolio (3):** `portfolio_list_platforms`, `portfolio_get_positions`, `portfolio_get_staked_jup` diff --git a/llms.txt b/llms.txt index 0da3b23d..de19008e 100644 --- a/llms.txt +++ b/llms.txt @@ -59,6 +59,7 @@ AI-first developer experience — AI-friendly docs, CLI, agent skills, llms.txt, - [llms.txt](https://developers.jup.ag/docs/ai/llms-txt.md): Jupiter provides two LLM-optimised documentation files: llms.txt (structured Markdown index of all APIs, guides, and resources with titles and descriptions, the perfect entrypoint for LLMs and AI agents) and llms-full.txt (the complete documentation site content including all code examples). Both follow the llmstxt.org standard. Additionally, any documentation page can be accessed as raw Markdown by appending .md to the URL or using the Accept: text/markdown header. - [Skills](https://developers.jup.ag/docs/ai/skills.md): Jupiter provides two agent skills in the jup-ag/agent-skills repository that AI coding agents can use as context when building with Jupiter. (1) integrating-jupiter: comprehensive integration guidance covering all Jupiter APIs (Swap, Lend, Perps, Trigger, Recurring, Tokens, Price, Portfolio, Prediction Markets, Send, Studio, Lock, Routing) with intent routing, API playbooks, error handling, and production hardening. (2) jupiter-lend: deep-dive into Jupiter Lend protocol (powered by Fluid) covering liquidity pools, lending markets (jlTokens), vaults, and flashloans with read (@jup-ag/lend-read) and write (@jup-ag/lend) SDKs. Skills are installed via npx skills add and provide SKILL.md files that AI agents consume as context. - [Documentation MCP](https://developers.jup.ag/docs/ai/mcp.md): Jupiter supports the Model Context Protocol (MCP) through Mintlify's native MCP server at https://developers.jup.ag/docs/mcp. This enables AI tools like Claude Code, Cursor, Windsurf, and other MCP-compatible editors to search and query Jupiter documentation and OpenAPI specifications in-context. The MCP server allows AI assistants to look up API endpoints, read documentation pages, and understand API schemas without leaving the editor. It is a read-only documentation server, not a tool for executing API calls. +- [Jupiter Trading MCP](https://developers.jup.ag/docs/ai/trading-mcp.md): Jupiter's hosted Trading MCP server at https://mcp.jup.ag gives AI agents access to Jupiter's trading infrastructure through the Model Context Protocol. It exposes 47 tools across 8 domains: Swap (quote, execute), Tokens (search, discovery), Price, Trigger (limit orders), Recurring (DCA), Lend (earn yield), Prediction (prediction markets), and Portfolio (positions, staked JUP). Authentication is a stateless per-request Bearer token set to your Jupiter API key from the Developer Platform; the server stores no keys. Transport is HTTP (Streamable HTTP). Covers setup for Claude Desktop, Claude Code, Cursor, and Windsurf, plus example prompts. This is the read-write operations server, distinct from the read-only Documentation MCP. - [Jupiter CLI](https://developers.jup.ag/docs/ai/cli.md): The Jupiter CLI (jup) is a command-line tool for interacting with Jupiter's products on Solana: Spot trading, Perpetual futures, and Lending. It is non-interactive and LLM-friendly by design, with JSON output mode for structured responses. Install via npm (npm i -g @jup-ag/cli). For full command references, key management, configuration, and JSON response schemas, see the CLI documentation at https://github.com/jup-ag/cli/tree/main/docs. Three usage paths: direct terminal, Telegram via OpenClaw/miniclaw, and AI agent integration. ## Swap From cedde6b5b0ca5d9ad5999ccf5743152809c6a090 Mon Sep 17 00:00:00 2001 From: YY <0xyankee@gmail.com> Date: Tue, 30 Jun 2026 23:07:53 +0800 Subject: [PATCH 2/8] docs: [ai] re-verify MCP findings, add portal-URL flag Re-confirmed all findings against live endpoints and source. Add F3: the jup-mcp README links portal.jup.ag (redirects to docs root) instead of developers.jup.ag/portal. Co-Authored-By: Claude Opus 4.8 (1M context) --- jup-mcp-findings.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/jup-mcp-findings.md b/jup-mcp-findings.md index 434c2874..0afcb5cd 100644 --- a/jup-mcp-findings.md +++ b/jup-mcp-findings.md @@ -16,12 +16,20 @@ Date: 2026-06-30. MCP commit: `main` HEAD at time of check. ## Summary - The server is **live** at `https://mcp.jup.ag` (`GET /health` → `200`). -- **47 tools across 8 domains**, confirmed from source. -- Most domains call the **current** API version (price v3, swap v2, tokens v2). The one real - staleness flag is **Trigger**, which calls the unmaintained `/trigger/v1/*` API. +- **47 tools across 8 domains**, confirmed from source (re-verified). +- Most domains call the **current** API version (price v3, swap v2, tokens v2). Two flags for the + MCP repo: **Trigger** calls the unmaintained `/trigger/v1/*` API (F1), and the README links the + wrong **portal URL** (F3). - The DEV-480 description has several inaccuracies (endpoint, Prediction count, tokens/trigger/lend domain descriptions) — corrected in section A. +Re-verification (2026-06-30): live checks — `mcp.jup.ag/health` `200`, `mcp.jup.ag/` `401` +(auth required), `api.jup.ag/mcp` `404`. Source tool counts confirmed exactly: lend 7, +portfolio 3, prediction 20, price 1, recurring 4, swap 3, tokens 4, trigger 5 = **47**. API +version prefixes confirmed: price `/v3`, swap `/v2`, tokens `/v2`, recurring/lend/portfolio/ +prediction/trigger `/v1`. Portal redirect confirmed: `portal.jup.ag` → `developers.jup.ag/` +(docs root), while `developers.jup.ag/portal` → portal sign-in. + --- ## A. DEV-480 description errors (fix in the issue) @@ -59,6 +67,14 @@ vault-based, JWT challenge-response, `/orders/price`). Trigger V1 still works, s functional, but it is a generation behind the current product. The docs page describes this as generic "limit orders" and does not claim V2. +### F3 — medium: README links the wrong portal URL +The README sends users to `https://portal.jup.ag/` to create an API key (3 places: quickstart +step 1, the Authentication section, and Support). That host **redirects to the docs root +`https://developers.jup.ag/`**, not to the Developer Platform. The canonical URL is +**`https://developers.jup.ag/portal`** (redirects to sign-in → portal). A new user following the +README lands on the docs homepage instead of the API-key page. Fix in the MCP repo's README. +(Our docs page already uses `https://developers.jup.ag/portal`.) + ### F2 — low (cosmetic): em dashes in tool descriptions `prediction_get_trade_history`, `prediction_list_trades`, `swap_get_instructions`, and `tokens_search` contain em dashes in their `description` strings. Conflicts with our style guide From ef671dc526105610024a32342e2093e9f82ac882 Mon Sep 17 00:00:00 2001 From: YY <0xyankee@gmail.com> Date: Tue, 30 Jun 2026 23:21:41 +0800 Subject: [PATCH 3/8] docs: [ai] add MCP auth-header nit (F4) to findings Inbound auth accepts only Authorization: Bearer; suggest also accepting x-api-key for consistency with the rest of Jupiter's API surface. Co-Authored-By: Claude Opus 4.8 (1M context) --- jup-mcp-findings.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/jup-mcp-findings.md b/jup-mcp-findings.md index 0afcb5cd..00e06b29 100644 --- a/jup-mcp-findings.md +++ b/jup-mcp-findings.md @@ -75,6 +75,17 @@ step 1, the Authentication section, and Support). That host **redirects to the d README lands on the docs homepage instead of the API-key page. Fix in the MCP repo's README. (Our docs page already uses `https://developers.jup.ag/portal`.) +### F4 — nit: inbound auth only accepts `Authorization: Bearer`, not `x-api-key` +The server's inbound auth (`src/infrastructure/security/auth.ts`) accepts **only** +`Authorization: Bearer ` and returns `401` otherwise. But the value is a Jupiter API key, +and the server forwards it **outbound as `x-api-key`** (`jupiter-client.ts`, +`API_KEY_HEADER = "x-api-key"`) — the convention every other Jupiter REST API uses. + +Suggestion: keep `Authorization: Bearer` as the documented/primary method (aligns with the MCP +Authorization spec and is forward-compatible with OAuth), but **also accept `x-api-key` inbound** +as a fallback — one extra check in `extractApiKey`. This matches the rest of the platform so +integrators can reuse the header they already send, with no downside. Additive, low-risk. + ### F2 — low (cosmetic): em dashes in tool descriptions `prediction_get_trade_history`, `prediction_list_trades`, `swap_get_instructions`, and `tokens_search` contain em dashes in their `description` strings. Conflicts with our style guide From e6fee1f85317b919eea2b937b0c42f4d7ab01c87 Mon Sep 17 00:00:00 2001 From: YY <0xyankee@gmail.com> Date: Tue, 30 Jun 2026 23:25:55 +0800 Subject: [PATCH 4/8] docs: [ai] add live e2e verification section to MCP findings Ran the MCP protocol against mcp.jup.ag: handshake, auth gating, tools/list (47 tools, live matches source), input validation, and MCP->Jupiter wiring all confirmed. Happy-path price call needs a real key. Co-Authored-By: Claude Opus 4.8 (1M context) --- jup-mcp-findings.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/jup-mcp-findings.md b/jup-mcp-findings.md index 00e06b29..18a208f5 100644 --- a/jup-mcp-findings.md +++ b/jup-mcp-findings.md @@ -120,6 +120,28 @@ and 2-cycle minimums against the live API / `recurring` source, then add them to --- +## E. End-to-end verification against the live server (2026-06-30) + +Ran the MCP protocol directly against `https://mcp.jup.ag` over Streamable HTTP (JSON-RPC POST). + +| Check | Result | +|-------|--------| +| `GET /health` | `200 {"status":"ok"}` | +| `initialize` (no `Authorization` header) | `401 {"error":"Unauthorized: API key required"}` | +| `initialize` (any Bearer token) | `200` — `serverInfo: jup-mcp v1.0.0`, `protocolVersion 2025-06-18`, `capabilities.tools.listChanged: true`. No `Mcp-Session-Id` returned → **stateless** server. | +| `tools/list` | `200` — **47 tools**, domain split exactly matches source (lend 7, portfolio 3, prediction 20, price 1, recurring 4, swap 3, tokens 4, trigger 5). **Live deployment matches source 1:1.** | +| `tools/call price_get` with wrong arg (`mints`) | MCP input-validation error `-32602` (schema requires `ids`). Tool schemas are enforced. | +| `tools/call price_get` with `ids=` + dummy key | `API error (401): {"code":401,"message":"Unauthorized"}` — the key is forwarded to `api.jup.ag` as `x-api-key` and Jupiter rejects the dummy. **Confirms the full MCP → Jupiter wiring.** | +| Happy-path execution (real price) | Not run — requires a valid Jupiter API key. | + +**Behaviour note (relates to F4):** the MCP auth boundary checks only that a Bearer token is +*present*, not that it is *valid* — `initialize` and `tools/list` succeed with any non-empty +Bearer. Key validity is enforced downstream by Jupiter's API on the first tool call that hits +`api.jup.ag`. This is expected for a stateless passthrough, but worth noting: a misconfigured key +surfaces as an `API error (401)` inside a tool result, not as a connection-time failure. + +--- + ## Tool inventory (47 total) - **Swap (3):** `swap_get_order`, `swap_get_instructions`, `swap_execute_order` From 08399e0b28fd1c1bf2f131647ec56cc772d646b7 Mon Sep 17 00:00:00 2001 From: YY <0xyankee@gmail.com> Date: Tue, 30 Jun 2026 23:30:50 +0800 Subject: [PATCH 5/8] docs: [ai] mark happy-path e2e verified in MCP findings price_get with a valid key returned live SOL/USDC prices over the live server. Full MCP -> Jupiter path now verified end to end. Co-Authored-By: Claude Opus 4.8 (1M context) --- jup-mcp-findings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jup-mcp-findings.md b/jup-mcp-findings.md index 18a208f5..c7b780ce 100644 --- a/jup-mcp-findings.md +++ b/jup-mcp-findings.md @@ -132,7 +132,7 @@ Ran the MCP protocol directly against `https://mcp.jup.ag` over Streamable HTTP | `tools/list` | `200` — **47 tools**, domain split exactly matches source (lend 7, portfolio 3, prediction 20, price 1, recurring 4, swap 3, tokens 4, trigger 5). **Live deployment matches source 1:1.** | | `tools/call price_get` with wrong arg (`mints`) | MCP input-validation error `-32602` (schema requires `ids`). Tool schemas are enforced. | | `tools/call price_get` with `ids=` + dummy key | `API error (401): {"code":401,"message":"Unauthorized"}` — the key is forwarded to `api.jup.ag` as `x-api-key` and Jupiter rejects the dummy. **Confirms the full MCP → Jupiter wiring.** | -| Happy-path execution (real price) | Not run — requires a valid Jupiter API key. | +| Happy-path execution with a **valid** key | `200`, `isError` unset. `price_get` for SOL + USDC returned live data: SOL `usdPrice ≈ 73.14`, USDC `≈ 0.9996`, each with `liquidity`, `decimals`, and `priceChange24h`. **Full path verified end to end.** | **Behaviour note (relates to F4):** the MCP auth boundary checks only that a Bearer token is *present*, not that it is *valid* — `initialize` and `tools/list` succeed with any non-empty From d31affebdca215059b7633363452a926e938f987 Mon Sep 17 00:00:00 2001 From: YY <0xyankee@gmail.com> Date: Tue, 30 Jun 2026 23:34:51 +0800 Subject: [PATCH 6/8] docs: [ai] add client-level (Claude Code) e2e to MCP findings Verified the documented Claude Code setup as a user would: claude mcp add connects, and a headless agent answered a natural-language price query by auto-discovering and calling the Jupiter MCP tools. Co-Authored-By: Claude Opus 4.8 (1M context) --- jup-mcp-findings.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/jup-mcp-findings.md b/jup-mcp-findings.md index c7b780ce..9c9d7178 100644 --- a/jup-mcp-findings.md +++ b/jup-mcp-findings.md @@ -134,6 +134,15 @@ Ran the MCP protocol directly against `https://mcp.jup.ag` over Streamable HTTP | `tools/call price_get` with `ids=` + dummy key | `API error (401): {"code":401,"message":"Unauthorized"}` — the key is forwarded to `api.jup.ag` as `x-api-key` and Jupiter rejects the dummy. **Confirms the full MCP → Jupiter wiring.** | | Happy-path execution with a **valid** key | `200`, `isError` unset. `price_get` for SOL + USDC returned live data: SOL `usdPrice ≈ 73.14`, USDC `≈ 0.9996`, each with `liquidity`, `decimals`, and `priceChange24h`. **Full path verified end to end.** | +### Client-level test (the documented user path) +Beyond raw JSON-RPC, the documented **Claude Code** setup was exercised exactly as a user would: + +| Check | Result | +|-------|--------| +| `claude mcp add --transport http jupiter-trading https://mcp.jup.ag --header "Authorization: Bearer "` | Server added to local config. | +| `claude mcp list` connection check | `jupiter-trading … ✔ Connected` (client ran the real `initialize` handshake with the key). | +| Headless agent, natural-language prompt ("look up the current USD price of SOL and JUP") | Agent auto-discovered the tools and called `price_get`, returning live prices (SOL ≈ \$73.2, JUP ≈ \$0.21). **The documented config + tool discovery + a real tool call all work from an actual MCP client.** | + **Behaviour note (relates to F4):** the MCP auth boundary checks only that a Bearer token is *present*, not that it is *valid* — `initialize` and `tools/list` succeed with any non-empty Bearer. Key validity is enforced downstream by Jupiter's API on the first tool call that hits From 22e44e17cc7b168351e156d4b25b488882fd164e Mon Sep 17 00:00:00 2001 From: YY <0xyankee@gmail.com> Date: Wed, 1 Jul 2026 00:01:14 +0800 Subject: [PATCH 7/8] docs: [ai] add read-sweep + real write-path e2e to MCP findings Exercised all 8 domains read-side and completed a real on-chain swap (0.01 SOL -> USDC) through swap_get_order -> sign -> swap_execute_order. Add F5 (prediction_list_events oversized payloads) and F6 (short blockhash validity; sign+submit immediately). Co-Authored-By: Claude Opus 4.8 (1M context) --- jup-mcp-findings.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/jup-mcp-findings.md b/jup-mcp-findings.md index 9c9d7178..07c508f5 100644 --- a/jup-mcp-findings.md +++ b/jup-mcp-findings.md @@ -143,6 +143,31 @@ Beyond raw JSON-RPC, the documented **Claude Code** setup was exercised exactly | `claude mcp list` connection check | `jupiter-trading … ✔ Connected` (client ran the real `initialize` handshake with the key). | | Headless agent, natural-language prompt ("look up the current USD price of SOL and JUP") | Agent auto-discovered the tools and called `price_get`, returning live prices (SOL ≈ \$73.2, JUP ≈ \$0.21). **The documented config + tool discovery + a real tool call all work from an actual MCP client.** | +### Read-tool sweep (8 domains) +Exercised one read tool per domain with live calls; all returned valid data: `price_get`, +`tokens_search`, `tokens_list_by_category`, `swap_get_order` (quote, no taker), `lend_list_tokens`, +`prediction_list_events`, `portfolio_list_platforms`. **F5 (usability) — `prediction_list_events` +returns oversized payloads:** even `limit=5` returned ~108 KB because each event embeds its full +`markets` array, which exceeds the MCP-client tool-result token cap. An agent will choke on the +default response. Suggest trimming embedded markets from the list response or adding a lightweight +list mode. + +### Write path — real on-chain execution +Completed the full `swap_get_order(taker)` → sign → `swap_execute_order` loop against the live +server with a real funded wallet: + +| Check | Result | +|-------|--------| +| `swap_get_order` with a real `taker` | Returned a signable base64 `transaction` + `requestId`, RTSE auto-slippage, fees attributed to the taker. No spend. | +| Sign locally + `swap_execute_order` | **`status: Success`**, real on-chain swap landed: 0.01 SOL → 0.732081 USDC, signature `49EtE9d…X438R`, slot 429909875. **Full write path verified end to end.** | + +**F6 (integration note, for docs) — short blockhash validity.** A first attempt failed with +`code -1005 "Transaction expired"` because model-in-the-loop latency between order, signing, and +execute exceeded the order's blockhash validity (~60s). Re-running build → sign → execute back to +back succeeded. Integrators (and the docs page) should treat the order as short-lived: sign and +submit immediately, and re-fetch the order rather than reusing a stale `requestId`. No funds are +spent on an expired submission. + **Behaviour note (relates to F4):** the MCP auth boundary checks only that a Bearer token is *present*, not that it is *valid* — `initialize` and `tools/list` succeed with any non-empty Bearer. Key validity is enforced downstream by Jupiter's API on the first tool call that hits From 5e299884a5710985a68646c492df1bd0f7856e65 Mon Sep 17 00:00:00 2001 From: YY <0xyankee@gmail.com> Date: Wed, 8 Jul 2026 23:21:33 +0800 Subject: [PATCH 8/8] =?UTF-8?q?docs:=20[ai]=20address=20PR=20review=20?= =?UTF-8?q?=E2=80=94=2075=20tools/11=20domains,=20key=20optional,=20trigge?= =?UTF-8?q?r=20v2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Re-verified against the live server. Update the Trading MCP page and findings report: 75 tools across 11 domains (add Send, Studio, Transaction), API key now optional (keyless works at lower rate limit, 401 = invalid key), and Trigger migrated to /trigger/v2 with the new challenge -> verify -> deposit -> create_order flow. Regenerate llms.txt. Co-Authored-By: Claude Opus 4.8 (1M context) --- ai/trading-mcp.mdx | 36 +++++++++++--------- jup-mcp-findings.md | 83 ++++++++++++++++++++++++++------------------- llms.txt | 2 +- 3 files changed, 69 insertions(+), 52 deletions(-) diff --git a/ai/trading-mcp.mdx b/ai/trading-mcp.mdx index 09bcb8a8..8986f62a 100644 --- a/ai/trading-mcp.mdx +++ b/ai/trading-mcp.mdx @@ -2,10 +2,10 @@ title: "Jupiter Trading MCP" sidebarTitle: "Trading MCP" description: "Execute Jupiter trades and DeFi operations from any MCP client." -llmsDescription: "Jupiter's hosted Trading MCP server at https://mcp.jup.ag gives AI agents access to Jupiter's trading infrastructure through the Model Context Protocol. It exposes 47 tools across 8 domains: Swap (quote, execute), Tokens (search, discovery), Price, Trigger (limit orders), Recurring (DCA), Lend (earn yield), Prediction (prediction markets), and Portfolio (positions, staked JUP). Authentication is a stateless per-request Bearer token set to your Jupiter API key from the Developer Platform; the server stores no keys. Transport is HTTP (Streamable HTTP). Covers setup for Claude Desktop, Claude Code, Cursor, and Windsurf, plus example prompts. This is the read-write operations server, distinct from the read-only Documentation MCP." +llmsDescription: "Jupiter's hosted Trading MCP server at https://mcp.jup.ag gives AI agents access to Jupiter's trading infrastructure through the Model Context Protocol. It exposes 75 tools across 11 domains: Swap (quote, execute), Tokens (search, discovery, verification), Price, Trigger (limit orders, v2 vault flow), Recurring (DCA), Lend (earn yield), Prediction (prediction markets), Portfolio (positions, staked JUP), Send (invite-based transfers), Studio (token launch pools), and Transaction (land signed transactions). An API key is optional: requests without one work at a lower rate limit, and passing your Jupiter API key from the Developer Platform as a Bearer token raises the limit. Transport is HTTP (Streamable HTTP). Covers setup for Claude Desktop, Claude Code, Cursor, and Windsurf, plus example prompts. This is the read-write operations server, distinct from the read-only Documentation MCP." --- -The Jupiter Trading MCP is a hosted [Model Context Protocol](https://modelcontextprotocol.io/) server that lets AI agents trade and run DeFi operations on Jupiter. Connect any MCP client to `https://mcp.jup.ag`, authenticate with your Jupiter API key, and your agent can swap tokens, place orders, lend, and read on-chain positions. +The Jupiter Trading MCP is a hosted [Model Context Protocol](https://modelcontextprotocol.io/) server that lets AI agents trade and run DeFi operations on Jupiter. Connect any MCP client to `https://mcp.jup.ag` and your agent can swap tokens, place orders, lend, and read on-chain positions. An API key is optional and only raises your rate limit. This server executes operations. For an AI assistant that searches and reads Jupiter's documentation instead, see the read-only [Documentation MCP](/ai/mcp). @@ -13,26 +13,29 @@ This server executes operations. For an AI assistant that searches and reads Jup ## What You Can Do -The server exposes **47 tools across 8 domains**. Your MCP client discovers them automatically once connected. +The server exposes **75 tools across 11 domains**. Your MCP client discovers them automatically once connected. | Domain | What it does | |:-------|:-------------| | **Swap** | Get a quote and a ready-to-sign transaction, then execute the swap with managed landing. | -| **Tokens** | Search tokens by name, symbol, or mint, and list tokens by tag, category, or recent listings. | +| **Tokens** | Search tokens by name, symbol, or mint, list by tag, category, or recent listings, and run token verification. | | **Price** | Fetch real-time USD prices, liquidity, and 24h change for one or more tokens. | -| **Trigger** | Create, cancel, and list limit orders that execute when a token hits a target price. | +| **Trigger** | Create, update, cancel, and list limit orders that execute when a token hits a target price. | | **Recurring** | Set up and manage dollar-cost averaging (DCA) orders that buy at regular intervals. | | **Lend** | Deposit into and withdraw from Jupiter Lend to earn yield, and read your lending positions. | -| **Prediction** | Browse prediction market events, place and close bets, and claim payouts. | +| **Prediction** | Browse prediction market events, place and close bets, claim payouts, and read scores and forecasts. | | **Portfolio** | Read a wallet's positions across Solana protocols and its staked JUP. | +| **Send** | Send tokens via Jupiter Send invites, claw back unclaimed invites, and list invite history. | +| **Studio** | Create Jupiter Studio token-launch (Dynamic Bonding Curve) pools and claim creator fees. | +| **Transaction** | Land any signed Solana transaction on-chain through Jupiter's Beam landing infrastructure. | -## Get a Jupiter API Key +## API Key (Optional) -The server authenticates every request with your own Jupiter API key. Create one in the [Developer Platform](https://developers.jup.ag/portal). This key is the Bearer token in the setup below. The server forwards it to Jupiter's API on your behalf and never stores it, so you use your own rate limits and permissions. +The server works without an API key at a lower rate limit, which is enough to try it out. For higher rate limits, create a key in the [Developer Platform](https://developers.jup.ag/portal) and pass it as a Bearer token (shown in the setup below). The server forwards the key to Jupiter's API on your behalf and never stores it, so you use your own rate limits and permissions. ## Connect Your Client -Add the server to your MCP client's configuration. The key detail is passing your Jupiter API key as a Bearer token in the `Authorization` header. Replace `YOUR_JUPITER_API_KEY` with your key in every example. +Add the server to your MCP client's configuration. To use a higher rate limit, pass your Jupiter API key as a Bearer token in the `Authorization` header and replace `YOUR_JUPITER_API_KEY` with your key. To start without a key, drop the `headers` block entirely. @@ -126,14 +129,15 @@ Add the server to your MCP client's configuration. The key detail is passing you ### Other MCP-Compatible Tools -Any tool that supports the MCP protocol can connect to `https://mcp.jup.ag` over HTTP transport, with the Jupiter API key in the `Authorization: Bearer` header. +Any tool that supports the MCP protocol can connect to `https://mcp.jup.ag` over HTTP transport. Add a Jupiter API key in the `Authorization: Bearer` header for a higher rate limit, or connect without one. ## Authentication -Authentication is stateless: each request carries your Jupiter API key as a Bearer token, and the server stores nothing. +Authentication is optional and stateless. When you send a key, each request carries it as a Bearer token and the server stores nothing. -- Pass the key on every request via the `Authorization: Bearer YOUR_JUPITER_API_KEY` header. -- Requests without a valid Bearer token receive a `401 Unauthorized` response. +- No key: requests work at a lower rate limit. Omit the `Authorization` header. +- With a key: pass `Authorization: Bearer YOUR_JUPITER_API_KEY` for a higher rate limit. +- A `401 Unauthorized` response means the key you sent is invalid, not that a key is missing. - The MCP endpoint is `https://mcp.jup.ag`. A separate `GET /health` endpoint needs no auth. ## Example Prompts @@ -144,7 +148,7 @@ Once connected, ask your AI assistant in plain language. Each prompt maps to one |:-------|:-----------| | "What is the current price of SOL and JUP?" | `price_get` | | "Swap 10 USDC for SOL" | `swap_get_order`, then `swap_execute_order` | -| "Place a limit order to sell 50 USDC for SOL at the current price." | `trigger_build_order` | +| "Place a limit order to sell 50 USDC for SOL at a target price." | `trigger_get_challenge` → `trigger_verify_challenge` → `trigger_build_deposit` → `trigger_create_order` | | "DCA 100 USDC into SOL daily for 10 days." | `recurring_build_order` | | "What tokens can I lend on Jupiter and what APY do they offer?" | `lend_list_tokens` | | "Are there any prediction markets about Bitcoin?" | `prediction_search_events` | @@ -152,14 +156,14 @@ Once connected, ask your AI assistant in plain language. Each prompt maps to one Trading prompts that move funds return an unsigned transaction. Your client signs it with your wallet and submits it, so you stay in control of every transaction. -If a tool call returns `401 Unauthorized`, check that the `Authorization: Bearer` header is set correctly in your client config. +If a tool call returns `401 Unauthorized`, the Jupiter API key you passed is invalid. Remove the `Authorization` header to run keyless at the lower rate limit, or replace it with a valid key from the [Developer Platform](https://developers.jup.ag/portal). ## Resources - Create the Jupiter API key used as your Bearer token. + Create an optional Jupiter API key for a higher rate limit. The read-only server for searching and querying Jupiter docs. diff --git a/jup-mcp-findings.md b/jup-mcp-findings.md index 07c508f5..4457a2fb 100644 --- a/jup-mcp-findings.md +++ b/jup-mcp-findings.md @@ -13,22 +13,34 @@ Date: 2026-06-30. MCP commit: `main` HEAD at time of check. --- +> **Update (2026-07-08, from PR review by the MCP maintainer + re-verification against the live +> server).** The server has grown since the original cross-check. It now exposes **75 tools across +> 11 domains** (added **Send** 4, **Studio** 4, **Transaction** 1; Lend 7→11, Tokens 4→7, +> Prediction 20→27, Trigger 5→10). **Trigger has migrated to `/trigger/v2`** (JWT + Privy vault +> flow), so **F1 is resolved** and `trigger_build_order` / `trigger_build_cancel_batch` / +> `trigger_execute` no longer exist. **An API key is now optional** — keyless requests work at a +> lower rate limit (`tools/list` and `price_get` verified returning `200` with no auth header); a +> `401` now means the key sent is invalid, not that a key is missing. The counts and version notes +> below are the original 2026-06-30 state, kept for history; the docs page reflects the current +> state. + ## Summary - The server is **live** at `https://mcp.jup.ag` (`GET /health` → `200`). -- **47 tools across 8 domains**, confirmed from source (re-verified). -- Most domains call the **current** API version (price v3, swap v2, tokens v2). Two flags for the - MCP repo: **Trigger** calls the unmaintained `/trigger/v1/*` API (F1), and the README links the - wrong **portal URL** (F3). -- The DEV-480 description has several inaccuracies (endpoint, Prediction count, tokens/trigger/lend +- **75 tools across 11 domains** (current; see the update note above). Original cross-check found 47 + tools across 8 domains. +- Domains now call current API versions across the board, including **Trigger on `/trigger/v2`**. + The one remaining repo flag is F3 (README links the wrong **portal URL**). +- The DEV-480 description had several inaccuracies (endpoint, Prediction count, tokens/trigger/lend domain descriptions) — corrected in section A. -Re-verification (2026-06-30): live checks — `mcp.jup.ag/health` `200`, `mcp.jup.ag/` `401` -(auth required), `api.jup.ag/mcp` `404`. Source tool counts confirmed exactly: lend 7, -portfolio 3, prediction 20, price 1, recurring 4, swap 3, tokens 4, trigger 5 = **47**. API -version prefixes confirmed: price `/v3`, swap `/v2`, tokens `/v2`, recurring/lend/portfolio/ -prediction/trigger `/v1`. Portal redirect confirmed: `portal.jup.ag` → `developers.jup.ag/` -(docs root), while `developers.jup.ag/portal` → portal sign-in. +Current counts (2026-07-08, live `tools/list`): lend 11, portfolio 3, prediction 27, price 1, +recurring 4, swap 3, tokens 7, trigger 10, send 4, studio 4, transaction 1 = **75**. + +Original re-verification (2026-06-30): source tool counts were lend 7, portfolio 3, prediction 20, +price 1, recurring 4, swap 3, tokens 4, trigger 5 = **47**; version prefixes price `/v3`, +swap `/v2`, tokens `/v2`, others `/v1`. Portal redirect confirmed: `portal.jup.ag` → +`developers.jup.ag/` (docs root), while `developers.jup.ag/portal` → portal sign-in. --- @@ -51,21 +63,15 @@ Jupiter API key from portal.jup.ag; the server never stores it and forwards it a ## B. MCP-vs-docs staleness (flag to the MCP / Labs team) -### F1 — high: Trigger tools use the unmaintained Trigger V1 API -All 5 trigger tools call `/trigger/v1/*`: - -| Tool | Path | -|------|------| -| `trigger_build_order` | `POST /trigger/v1/createOrder` | -| `trigger_build_cancel` | `POST /trigger/v1/cancelOrder` | -| `trigger_build_cancel_batch` | `POST /trigger/v1/cancelOrders` | -| `trigger_execute` | `POST /trigger/v1/execute` | -| `trigger_list_orders` | `GET /trigger/v1/getTriggerOrders` | - -Our docs mark **Trigger V1 as unmaintained** (superseded by Trigger V2: `api.jup.ag/trigger/v2`, -vault-based, JWT challenge-response, `/orders/price`). Trigger V1 still works, so the MCP is -functional, but it is a generation behind the current product. The docs page describes this as -generic "limit orders" and does not claim V2. +### F1 — RESOLVED (2026-07-08): Trigger migrated to `/trigger/v2` +Originally, all 5 trigger tools called the unmaintained `/trigger/v1/*` API. As of the +2026-07-08 review, Trigger is on **`/trigger/v2`** with the current vault-based, JWT +challenge-response flow, and now has **10 tools**: `trigger_get_challenge`, +`trigger_verify_challenge`, `trigger_get_vault`, `trigger_register_vault`, `trigger_build_deposit`, +`trigger_create_order`, `trigger_update_order`, `trigger_build_cancel`, `trigger_confirm_cancel`, +`trigger_list_orders`. The old `trigger_build_order`, `trigger_build_cancel_batch`, and +`trigger_execute` tools are gone. Placing a limit order is now: `trigger_get_challenge` → +`trigger_verify_challenge` → `trigger_build_deposit` → `trigger_create_order`. No action needed. ### F3 — medium: README links the wrong portal URL The README sends users to `https://portal.jup.ag/` to create an API key (3 places: quickstart @@ -113,10 +119,14 @@ and 2-cycle minimums against the live API / `recurring` source, then add them to | Price | `GET /price/v3` (max 50 mints, 24h change) | Current. Matches `price/index.mdx`. | | Swap | `GET /swap/v2/order`, `GET /swap/v2/build`, `POST /swap/v2/execute` | Current V2. `/build` Metis-only / no-RFQ matches docs. | | Tokens | `GET /tokens/v2/search \| /tag \| /{category}/{interval} \| /recent` | Current V2. (Minor: `tokens_search` omits the comma-separated batch-by-mint up-to-100 capability our docs note — tool-richness nit, not staleness.) | +| Trigger | `/trigger/v2/*` (JWT + Privy vault flow, 10 tools) | Current V2 (as of 2026-07-08; see F1). | | Recurring | `POST /recurring/v1/*`, `GET /recurring/v1/getRecurringOrders` | V1 is the only public version. Consistent. | -| Lend | `/lend/v1/earn/*` (deposit, withdraw, mint, redeem, positions, earnings, tokens) | Earn side, current. Correctly labelled "Jupiter Lend/Earn" in source. | -| Prediction | `/prediction/v1/*` (20 tools) | V1 beta. Amount in micro USD (1,000,000 = $1.00); price 0–1. Consistent. | +| Lend | `/lend/v1/earn/*` (deposit, withdraw, mint, redeem, positions, earnings, tokens; +instructions variants, 11 tools) | Earn side, current. Correctly labelled "Jupiter Lend/Earn" in source. | +| Prediction | `/prediction/v1/*` (27 tools) | V1 beta. Amount in micro USD (1,000,000 = $1.00); price 0–1. Consistent. | | Portfolio | `GET /portfolio/v1/platforms`, `/positions/{address}`, `/staked-jup/{address}` | V1 beta. Matches `portfolio/index.mdx` exactly. | +| Send | Jupiter Send invite transfers/clawback (4 tools) | New domain since original cross-check. | +| Studio | Jupiter Studio DBC launch pools + creator fees (4 tools) | New domain since original cross-check. | +| Transaction | `transaction_submit` (land signed tx via Beam, 1 tool) | New domain since original cross-check. | --- @@ -176,13 +186,16 @@ surfaces as an `API error (401)` inside a tool result, not as a connection-time --- -## Tool inventory (47 total) +## Tool inventory (75 total, live `tools/list` on 2026-07-08) -- **Swap (3):** `swap_get_order`, `swap_get_instructions`, `swap_execute_order` -- **Tokens (4):** `tokens_search`, `tokens_list_by_tag`, `tokens_list_by_category`, `tokens_list_recent` +- **Swap (3):** `swap_get_order`, `swap_execute_order`, `swap_get_instructions` +- **Tokens (7):** `tokens_search`, `tokens_list_by_tag`, `tokens_list_by_category`, `tokens_list_recent`, `tokens_get_verification_eligibility`, `tokens_build_verification_payment`, `tokens_execute_verification` - **Price (1):** `price_get` -- **Trigger (5):** `trigger_build_order`, `trigger_build_cancel`, `trigger_build_cancel_batch`, `trigger_execute`, `trigger_list_orders` +- **Trigger (10):** `trigger_get_challenge`, `trigger_verify_challenge`, `trigger_get_vault`, `trigger_register_vault`, `trigger_build_deposit`, `trigger_create_order`, `trigger_update_order`, `trigger_build_cancel`, `trigger_confirm_cancel`, `trigger_list_orders` - **Recurring (4):** `recurring_build_order`, `recurring_build_cancel`, `recurring_execute`, `recurring_list_orders` -- **Lend (7):** `lend_build_deposit`, `lend_build_withdraw`, `lend_build_mint_shares`, `lend_build_redeem_shares`, `lend_get_positions`, `lend_get_earnings`, `lend_list_tokens` -- **Prediction (20):** events (`get_event`, `list_events`, `search_events`, `list_suggested_events`), markets (`get_market`, `list_markets`, `get_orderbook`), orders (`build_order`, `list_orders`, `get_order`, `get_order_status`), positions (`list_positions`, `get_position`, `build_close_position`, `build_close_all_positions`, `build_claim_payout`), profile/feed (`get_profile`, `get_leaderboard`, `get_trade_history`, `list_trades`) -- **Portfolio (3):** `portfolio_list_platforms`, `portfolio_get_positions`, `portfolio_get_staked_jup` +- **Lend (11):** `lend_build_deposit`, `lend_build_withdraw`, `lend_build_mint_shares`, `lend_build_redeem_shares`, `lend_get_deposit_instructions`, `lend_get_withdraw_instructions`, `lend_get_mint_instructions`, `lend_get_redeem_instructions`, `lend_list_tokens`, `lend_get_positions`, `lend_get_earnings` +- **Prediction (27):** events (`search_events`, `list_events`, `get_event`, `list_suggested_events`), markets (`list_markets`, `get_market`, `get_orderbook`, `get_event_market`), orders (`build_order`, `list_orders`, `get_order`, `get_order_status`), positions (`list_positions`, `get_position`, `build_close_position`, `build_close_all_positions`, `build_claim_payout`), profile/feed (`get_profile`, `get_leaderboard`, `get_trade_history`, `list_trades`, `get_pnl_history`), live/scores (`get_trading_status`, `get_live_scores`, `get_event_score`, `get_forecast`, `get_vault_info`) +- **Portfolio (3):** `portfolio_get_positions`, `portfolio_list_platforms`, `portfolio_get_staked_jup` +- **Send (4):** `send_build_transfer`, `send_build_clawback`, `send_list_pending_invites`, `send_list_invite_history` +- **Studio (4):** `studio_build_create_pool`, `studio_get_pool_addresses`, `studio_get_fees`, `studio_build_claim_fee` +- **Transaction (1):** `transaction_submit` diff --git a/llms.txt b/llms.txt index de19008e..9ccb3b4b 100644 --- a/llms.txt +++ b/llms.txt @@ -59,7 +59,7 @@ AI-first developer experience — AI-friendly docs, CLI, agent skills, llms.txt, - [llms.txt](https://developers.jup.ag/docs/ai/llms-txt.md): Jupiter provides two LLM-optimised documentation files: llms.txt (structured Markdown index of all APIs, guides, and resources with titles and descriptions, the perfect entrypoint for LLMs and AI agents) and llms-full.txt (the complete documentation site content including all code examples). Both follow the llmstxt.org standard. Additionally, any documentation page can be accessed as raw Markdown by appending .md to the URL or using the Accept: text/markdown header. - [Skills](https://developers.jup.ag/docs/ai/skills.md): Jupiter provides two agent skills in the jup-ag/agent-skills repository that AI coding agents can use as context when building with Jupiter. (1) integrating-jupiter: comprehensive integration guidance covering all Jupiter APIs (Swap, Lend, Perps, Trigger, Recurring, Tokens, Price, Portfolio, Prediction Markets, Send, Studio, Lock, Routing) with intent routing, API playbooks, error handling, and production hardening. (2) jupiter-lend: deep-dive into Jupiter Lend protocol (powered by Fluid) covering liquidity pools, lending markets (jlTokens), vaults, and flashloans with read (@jup-ag/lend-read) and write (@jup-ag/lend) SDKs. Skills are installed via npx skills add and provide SKILL.md files that AI agents consume as context. - [Documentation MCP](https://developers.jup.ag/docs/ai/mcp.md): Jupiter supports the Model Context Protocol (MCP) through Mintlify's native MCP server at https://developers.jup.ag/docs/mcp. This enables AI tools like Claude Code, Cursor, Windsurf, and other MCP-compatible editors to search and query Jupiter documentation and OpenAPI specifications in-context. The MCP server allows AI assistants to look up API endpoints, read documentation pages, and understand API schemas without leaving the editor. It is a read-only documentation server, not a tool for executing API calls. -- [Jupiter Trading MCP](https://developers.jup.ag/docs/ai/trading-mcp.md): Jupiter's hosted Trading MCP server at https://mcp.jup.ag gives AI agents access to Jupiter's trading infrastructure through the Model Context Protocol. It exposes 47 tools across 8 domains: Swap (quote, execute), Tokens (search, discovery), Price, Trigger (limit orders), Recurring (DCA), Lend (earn yield), Prediction (prediction markets), and Portfolio (positions, staked JUP). Authentication is a stateless per-request Bearer token set to your Jupiter API key from the Developer Platform; the server stores no keys. Transport is HTTP (Streamable HTTP). Covers setup for Claude Desktop, Claude Code, Cursor, and Windsurf, plus example prompts. This is the read-write operations server, distinct from the read-only Documentation MCP. +- [Jupiter Trading MCP](https://developers.jup.ag/docs/ai/trading-mcp.md): Jupiter's hosted Trading MCP server at https://mcp.jup.ag gives AI agents access to Jupiter's trading infrastructure through the Model Context Protocol. It exposes 75 tools across 11 domains: Swap (quote, execute), Tokens (search, discovery, verification), Price, Trigger (limit orders, v2 vault flow), Recurring (DCA), Lend (earn yield), Prediction (prediction markets), Portfolio (positions, staked JUP), Send (invite-based transfers), Studio (token launch pools), and Transaction (land signed transactions). An API key is optional: requests without one work at a lower rate limit, and passing your Jupiter API key from the Developer Platform as a Bearer token raises the limit. Transport is HTTP (Streamable HTTP). Covers setup for Claude Desktop, Claude Code, Cursor, and Windsurf, plus example prompts. This is the read-write operations server, distinct from the read-only Documentation MCP. - [Jupiter CLI](https://developers.jup.ag/docs/ai/cli.md): The Jupiter CLI (jup) is a command-line tool for interacting with Jupiter's products on Solana: Spot trading, Perpetual futures, and Lending. It is non-interactive and LLM-friendly by design, with JSON output mode for structured responses. Install via npm (npm i -g @jup-ag/cli). For full command references, key management, configuration, and JSON response schemas, see the CLI documentation at https://github.com/jup-ag/cli/tree/main/docs. Three usage paths: direct terminal, Telegram via OpenClaw/miniclaw, and AI agent integration. ## Swap