integrating-jupiter

Jupiter API 集成

用于所有 Jupiter API 的单一技能，针对快速路由和确定性执行进行了优化。

基础 URL：https://api.jup.ag 身份验证：来自 portal.jup.ag 的 x-api-key（Jupiter REST 端点必需）

使用/不使用

适用于：

• 任务需要选择或调用 Jupiter 端点。
• 任务涉及 swap、借贷、永续合约、订单、定价、投资组合、发送、studio、锁定或路由。
• 用户需要调试 Jupiter API 调用。

不适用于：

• 任务是通用的 Solana 设置，且不使用 Jupiter API。
• 任务仅涉及 UI，不需要决定 API 行为。

触发词：swap、quote、gasless、best route、lend、borrow、earn、liquidation、perps、leverage、long、short、position、limit order、trigger、price condition、dca、recurring、scheduled swaps、token metadata、token search、verification、shield、price、valuation、price feed、portfolio、positions、holdings、prediction markets、market odds、event market、invite transfer、send、clawback、create token、studio、claim fee、vesting、distribution lock、unlock schedule、dex integration、rfq integration、routing engine

开发者快速入门

import { Connection, Keypair, VersionedTransaction } from '@solana/web3.js';

const API_KEY = process.env.JUPITER_API_KEY!;  // from portal.jup.ag
if (!API_KEY) throw new Error('Missing JUPITER_API_KEY');
const BASE = 'https://api.jup.ag';
const headers = { 'x-api-key': API_KEY };

async function jupiterFetch<T>(path: string, init?: RequestInit): Promise<T> {
  const res = await fetch(`${BASE}${path}`, {
    ...init,
    headers: { ...headers, ...init?.headers },
  });
  if (res.status === 429) throw { code: 'RATE_LIMITED', retryAfter: 10 };
  if (!res.ok) {
    const raw = await res.text();
    let body: any = { message: raw || `HTTP_${res.status}` };
    try {
      body = raw ? JSON.parse(raw) : body;
    } catch {
      // keep text fallback body
    }
    throw { status: res.status, ...body };
  }
  return res.json();
}

// Sign and send any Jupiter transaction
async function signAndSend(
  txBase64: string,
  wallet: Keypair,
  connection: Connection,
  additionalSigners: Keypair[] = []
): Promise<string> {
  const tx = VersionedTransaction.deserialize(Buffer.from(txBase64, 'base64'));
  tx.sign([wallet, ...additionalSigners]);
  const sig = await connection.sendRawTransaction(tx.serialize(), {
    maxRetries: 0,
    skipPreflight: true,
  });
  return sig;
}

意图路由器（第一步）

用户意图	API 系列	第一个操作
Swap/报价	Ultra Swap	GET /ultra/v1/order -> 签名 -> POST /ultra/v1/execute
借贷/借款/收益	Lend	POST /lend/v1/earn/deposit 或 /withdraw
杠杆/永续合约	Perps	通过 Anchor IDL 在链上操作（尚无 REST API）
限价订单	Trigger	POST /trigger/v1/createOrder -> 签名 -> POST /trigger/v1/execute
DCA/定期买入	Recurring	POST /recurring/v1/createOrder -> 签名 -> POST /recurring/v1/execute
代币搜索/验证	Tokens	GET /tokens/v2/search?query={mint}
价格查询	Price	GET /price/v3?ids={mints}
投资组合/持仓	Portfolio	GET /portfolio/v1/positions/{address}
预测市场集成	Prediction Markets	GET /prediction/v1/events -> POST /prediction/v1/orders
邀请发送/追回	Send	POST /send/v1/craft-send -> 签名 -> 发送到 RPC
代币创建/费用	Studio	POST /studio/v1/dbc-pool/create-tx -> 上传 -> 提交
归属/分配	Lock	链上程序 LocpQgucEQHbqNABEYvBvwoxCPsSbG91A1QaQhQQqjn
DEX/RFQ 集成	Routing	选择 DEX（AMM trait）或 RFQ（webhook）路径

API 操作手册

将每个区块视为最简执行约定。获取链接的参考文档，以查看完整的请求/响应结构、TypeScript 接口和参数详情。

Ultra Swap

• 基础 URL：https://api.jup.ag/ultra/v1
• 触发词：swap、quote、gasless、best route
• 费用：5-10 bps（标准），或配置自定义费用时收取集成方费用的 20%
• 速率限制：基础限制为每 10 秒 50 个请求，并随 24 小时执行量增加（参见速率限制）
• 端点：/order（GET）、/execute（POST）、/holdings/{account}（GET）、/shield（GET）、/search（GET）、/routers（GET）
• 注意事项：签名载荷的有效期约为 2 分钟。交易收到后不可更改。在代码和日志中分开处理 order 和 execute。条件可能发生变化时，执行前重新获取报价。
• 参考：概述 | Order | Execute | 响应

---

借贷

• 基础 URL：https://api.jup.ag/lend/v1
• 触发词：lend、borrow、earn、liquidation
• 程序：Earn jup3YeL8QhtSx1e253b2FDvsMNC87fDrgQZivbrndc9，Borrow jupr81YtYssSyPt8jbnGuiWon5f6x9TcDEFxYe3Bdzi
• SDK：@jup-ag/lend（TypeScript）
• 端点：/earn/deposit（POST）、/earn/withdraw（POST）、/earn/mint（POST）、/earn/redeem（POST）、/earn/deposit-instructions（POST）、/earn/withdraw-instructions（POST）、/earn/tokens（GET）、/earn/positions（GET）、/earn/earnings（GET）
• 注意事项：每次执行状态变更操作前都要重新计算账户状态。将风险检查（健康因子、清算边界）设为前置条件。所有 deposit/withdraw/mint/redeem 操作均返回 base64 编码的未签名 VersionedTransaction。
• 参考：概览 | Earn | SDK

---

永续合约

• 状态：API 仍在开发中。目前没有 REST 端点。通过 Anchor IDL 在链上交互。
• 触发词：perps、leverage、long、short、position
• 社区 SDK：github.com/julianfssen/jupiter-perps-anchor-idl-parsing
• 注意事项：最多同时持有 9 个仓位：3 个多仓（SOL、wETH、wBTC）+ 6 个空仓（3 种代币 × 2 种抵押品 USDC/USDT）。根据账户模型验证保证金和杠杆。
• 参考：概览 | 仓位账户 | 仓位请求

---

Trigger（限价订单）

• 基础 URL：https://api.jup.ag/trigger/v1
• 触发词：limit order、trigger、price condition
• 手续费：非稳定币交易对为 0.1%，稳定币交易对为 0.03%
• 分页：每页 10 个订单
• 端点：/createOrder（POST）、/cancelOrder（POST）、/cancelOrders（POST，每笔交易最多 5 个）、/execute（POST）、/getTriggerOrders（GET）
• 注意事项：前端要求最低金额为 5 USD；链上没有最低限额。程序不会验证价格是否有利——创建订单前请验证目标价格。不支持 Token-2022。默认滑点为零（“Exact” 模式）；设置 slippageBps 可启用成交率更高的 “Ultra” 模式。
• 参考：概览 | 创建 | 获取订单 | 最佳实践

---

定期交易（DCA）

• 基础 URL：https://api.jup.ag/recurring/v1
• 触发词：dca、recurring、scheduled swaps
• 手续费：所有定期订单均收取 0.1% 手续费
• 限制：总金额至少为 100 USD，至少 2 笔订单，每笔订单至少为 50 USD
• 分页：每页 10 个订单
• 端点：/createOrder（POST）、/cancelOrder（POST）、/execute（POST）、/getRecurringOrders（GET）
• 注意事项：不支持 Token-2022。基于价格的定期订单已弃用——仅使用 params.time。
• 参考：概览 | 创建 | 获取订单 | 最佳实践

---

代币

• 基础 URL：https://api.jup.ag/tokens/v2
• 触发词：token metadata、token search、verification、shield
• 端点：/search?query={q}（GET，以逗号分隔 mint，最多 100 个）、/tag?query={tag}（GET，verified 或 lst）、/{category}/{interval}（GET，类别：toporganicscore、toptraded、toptrending；时间间隔：5m、1h、6h、24h）、/recent（GET）
• 注意事项：将 mint 地址作为主要标识；将符号/名称视为便利用途。在用户体验中展示 audit.isSus 和 organicScore。
• 参考：概览 | 代币信息 v2

---

价格

• 基础 URL：https://api.jup.ag/price/v3
• 触发词：price、valuation、price feed
• 限制：每个请求最多包含 50 个 mint ID
• 端点：/price/v3?ids={mints}（GET，以逗号分隔）
• 注意事项：价格不可靠的代币会返回 null 或不出现在响应中（这不属于错误）。对于安全敏感操作，缺少数据或置信度较低时应拒绝执行。使用 confidenceLevel 字段。
• 参考：概览 | 价格 v3

---

投资组合

• 基础 URL：https://api.jup.ag/portfolio/v1
• 状态：测试版——仅限 Jupiter 平台
• 触发词：portfolio、positions、holdings
• 端点：/positions/{address}（GET）、/positions/{address}?platforms={ids}（GET）、/platforms（GET）、/staked-jup/{address}（GET）
• 注意事项：空的持仓列表是有效状态。响应处于测试版——应将其规范化为稳定的内部架构。元素类型：multiple、liquidity、trade、leverage、borrowlend。
• 参考：概览 | Jupiter 持仓

---

预测市场

• 基础 URL：https://api.jup.ag/prediction/v1
• 状态：测试版（可能发生破坏性变更）
• 地理限制：屏蔽来自美国和韩国的 IP
• 价格约定：1,000,000 个原生单位 = 1.00 美元
• 触发词：prediction markets、market odds、event market
• 存款 mint：JupUSD（JuprjznTrTSp2UFa3ZBUFgwdAmtZCq4MQCwysN55USD）、USDC
• 端点：/events（GET）、/events/search（GET）、/markets/{marketId}（GET）、/orderbook/{marketId}（GET）、/orders（POST）、/orders/status/{pubkey}（GET）、/positions（GET）、/positions/{pubkey}（DELETE）、/positions/{pubkey}/claim（POST）、/history（GET）、/leaderboards（GET）
• 注意事项：申领前检查 position.claimable。获胜者每份合约可获得 1 美元。
• 参考：概览 | 事件 | 持仓

---

发送

• 基础 URL：https://api.jup.ag/send/v1
• 状态：测试版
• 触发词：invite transfer、send、clawback
• 支持的代币：SOL、USDC、memecoins
• 端点：/craft-send（POST）、/craft-clawback（POST）、/pending-invites（GET）、/invite-history（GET）
• 注意事项：需要双方签名——发送方和接收方的密钥对（根据邀请码派生）。只能通过 Jupiter Mobile 领取（不支持通过 API 领取）。切勿公开邀请码。
• 参考：概览 | 邀请码 | 创建发送请求

---

Studio

• 基础 URL：https://api.jup.ag/studio/v1
• 状态：Beta
• 触发词：create token、studio、claim fee
• 端点：/dbc-pool/create-tx（POST）、/dbc-pool/submit（POST，multipart/form-data）、/dbc-pool/addresses/{mint}（GET）、/dbc/fee（POST）、/dbc/fee/create-tx（POST）
• 流程：create-tx -> 将图片上传到预签名 URL -> 将元数据上传到预签名 URL -> 签名 -> 通过 /dbc-pool/submit 提交
• 注意事项：必须通过 /dbc-pool/submit 提交（不能从外部提交），代币才能在 jup.ag 上获得 Studio 页面。错误代码：403 = 无权使用该池，404 = 找不到代理账户。
• 参考：概览 | 创建代币 | 领取费用

---

Lock

• 程序 ID：LocpQgucEQHbqNABEYvBvwoxCPsSbG91A1QaQhQQqjn
• 触发词：vesting、distribution lock、unlock schedule
• 集成方式：仅限链上程序（无 REST API）
• 源码：github.com/jup-ag/jup-lock
• 界面：lock.jup.ag
• 安全性：经 OtterSec 和 Sec3 审计
• 注意事项：无 REST API。使用代码库中 cli/src/bin/instructions 目录下的指令脚本。
• 参考：Lock 概览

---

Routing

• 触发词：dex integration、rfq integration、routing engine
• 引擎：Juno（元聚合器）、Iris（多跳 DEX 路由，为 Ultra 提供支持）、JupiterZ（RFQ 做市商报价）
• DEX 集成（接入 Iris）：免费，无费用。前提条件：代码质量良好、通过安全审计、具备市场牵引力。实现 jupiter-amm-interface crate。重要：实现中不得进行网络调用（账户会预先批量获取并缓存）。参考实现：github.com/jup-ag/rust-amm-implementation
• RFQ 集成（JupiterZ）：做市商在 /jupiter/rfq/quote（POST，250ms）、/jupiter/rfq/swap（POST）、/jupiter/rfq/tokens（GET）托管 webhook。要求：成交率达 95%、响应时间 250ms、过期时间 55s。SDK：github.com/jup-ag/rfq-webhook-toolkit
• 市场上币：对于创建时间不到 30 天的代币，可即时路由。常规路由（每 30 分钟检查一次）要求：以 $500 进行往返交易的损失低于 30%，或比较 $1k 与 $500 时的价格影响低于 20%。
• 参考：概览 | DEX 集成 | RFQ 集成 | 市场上币

---

速率限制

Ultra Swap（动态，基于交易量）：

24 小时执行交易量	每 10s 窗口内的请求数
$0	50
$10,000	51
$100,000	61
$1,000,000	165

配额每 10 分钟重新计算。Pro 计划不会提高 Ultra 限额。

其他 API：在门户级别管理。查看门户速率限制。

收到 HTTP 429 时：使用带抖动的指数退避：delay = min(baseDelay * 2^attempt + random(0, jitter), maxDelay)。等待 10s 滑动窗口刷新。切勿激进地突发请求。

生产环境加固

1. 身份验证：如果缺少 x-api-key 或其无效，则立即失败。
2. 超时：报价超时设为 5s，执行超时设为 30s，并设置总操作超时。
3. 重试：仅对临时故障、网络故障和速率限制故障进行重试，并采用带抖动的指数退避。
4. 幂等性：Ultra /execute 在最多 2 min 内接受相同的 signedTransaction + requestId，且不会重复执行。
5. 验证：调用前验证铸币地址、金额精度和钱包所有权。
6. 安全性：根据应用配置强制执行滑点和最大金额防护措施。
7. 可观测性：记录 requestId、API 系列、端点、延迟、状态和错误代码。
8. 用户体验韧性：返回可采取行动的状态（retry、adjust params、insufficient balance、rate limited）。
9. 一致性：在向用户报告最终成功前，协调异步状态（已提交、已确认或失败）。
10. 时效性：如果行为与预期流程不同，重新获取引用的文档。

集成最佳实践

1. 编写端点调用代码前，先查看对应 API 的概览。
2. 将身份验证作为每个请求的强制前提。参考：Portal 设置
3. 根据文档说明的速率限制行为设计重试逻辑，不要依赖固定假设。参考：速率限制
4. 根据文档定义的响应语义，将所有非成功响应映射为应用中的类型化错误。参考：API 响应
5. 对于基于订单的产品（Ultra/Trigger/Recurring），在代码和日志中将创建、执行和检索阶段分开处理。
6. 将网络和服务健康状况视为运行时行为的一部分（优雅降级）。参考：状态页面

通用错误模式

interface JupiterResult<T> {
  ok: boolean;
  result?: T;
  error?: { code: string | number; message: string; retryable: boolean };
}

async function jupiterAction<T>(action: () => Promise<T>): Promise<JupiterResult<T>> {
  try {
    const result = await action();
    return { ok: true, result };
  } catch (error: any) {
    const code = error?.code ?? error?.status ?? 'UNKNOWN';

    // Rate limit — retry with backoff
    if (code === 429 || code === 'RATE_LIMITED') {
      return { ok: false, error: { code: 'RATE_LIMITED', message: 'Rate limited', retryable: true } };
    }

    // Ultra execute errors (negative codes)
    if (typeof code === 'number' && code < 0) {
      const retryable = [-1, -1000, -1001, -1005, -1006, -2000, -2003, -2005].includes(code);
      return { ok: false, error: { code, message: error?.error ?? 'Execute failed', retryable } };
    }

    // Program errors (positive codes like 6001 = slippage)
    if (typeof code === 'number' && code > 0) {
      return { ok: false, error: { code, message: error?.error ?? 'Program error', retryable: false } };
    }

    return { ok: false, error: { code, message: error?.message ?? 'UNKNOWN_ERROR', retryable: false } };
  }
}

最新上下文策略

执行操作手册前，务必从所引用的文档/规范中获取最新上下文。

1. 使用 Intent Router 确定意图。
2. 编写代码前，获取操作手册链接的参考资料（概览和特定 API 文档）。
3. 如需验证或消除歧义，获取 OpenAPI 规范。
4. 将获取的文档视为事实依据，优先于缓存的记忆。
5. 如果获取的文档与本文件冲突，遵循获取的文档并注明差异。
6. 如果无法获取文档，说明上下文已过时/未经验证，并根据已知的最佳指导继续操作。
7. 保持身份验证规则不变：Jupiter REST 端点需要 x-api-key（Perps/Lock 等仅限链上流程除外）。

运维参考

• Portal 设置 — API 密钥配置
• 速率限制 — 全局速率限制策略
• Ultra 速率限制 — 基于动态交易量的限制
• API 响应 — 响应格式标准
• Ultra 响应 — 详细错误代码
• 状态页面 — 服务健康状况
• 文档站点地图 — 完整文档索引
• 工具包 — 插件、Wallet Kit、推荐计划