integrating-jupiter
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseJupiter API Integration
Jupiter API 集成
Single skill for all Jupiter APIs, optimized for fast routing and deterministic execution.
Base URL:
Auth: from portal.jup.ag (required for Jupiter REST endpoints)
https://api.jup.agx-api-key一站式掌握所有Jupiter API技能,针对快速路由和确定性执行进行优化。
Use/Do Not Use
适用场景/不适用场景
Use when:
- The task requires choosing or calling Jupiter endpoints.
- The task involves swap, lending, perps, orders, pricing, portfolio, send, studio, lock, or routing.
- The user needs debugging help for Jupiter API calls.
Do not use when:
- The task is generic Solana setup with no Jupiter API usage.
- The task is UI-only with no API behavior decisions.
Triggers: , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,
swapquotegaslessbest routelendborrowearnliquidationperpsleveragelongshortpositionlimit ordertriggerprice conditiondcarecurringscheduled swapstoken metadatatoken searchverificationshieldpricevaluationprice feedportfoliopositionsholdingsprediction marketsmarket oddsevent marketinvite transfersendclawbackcreate tokenstudioclaim feevestingdistribution lockunlock scheduledex integrationrfq integrationrouting engine适用场景:
- 任务需要选择或调用Jupiter端点时
- 任务涉及兑换、借贷、永续合约、订单、定价、投资组合、转账、Studio、锁仓或路由时
- 用户需要Jupiter API调用的调试帮助时
不适用场景:
- 任务是通用Solana设置,未使用Jupiter API时
- 任务仅涉及UI,无需API行为决策时
触发词:、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、
swapquotegaslessbest routelendborrowearnliquidationperpsleveragelongshortpositionlimit ordertriggerprice conditiondcarecurringscheduled swapstoken metadatatoken searchverificationshieldpricevaluationprice feedportfoliopositionsholdingsprediction marketsmarket oddsevent marketinvite transfersendclawbackcreate tokenstudioclaim feevestingdistribution lockunlock scheduledex integrationrfq integrationrouting engineDeveloper Quickstart
开发者快速入门
typescript
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;
}typescript
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;
}Intent Router (first step)
意图路由(第一步)
| User intent | API family | First action |
|---|---|---|
| Swap/quote | Ultra Swap | |
| Lend/borrow/yield | Lend | |
| Leverage/perps | Perps | On-chain via Anchor IDL (no REST API yet) |
| Limit orders | Trigger | |
| DCA/recurring buys | Recurring | |
| Token search/verification | Tokens | |
| Price lookup | Price | |
| Portfolio/positions | Portfolio | |
| Prediction market integration | Prediction Markets | |
| Invite send/clawback | Send | |
| Token creation/fees | Studio | |
| Vesting/distribution | Lock | On-chain program |
| DEX/RFQ integration | Routing | Choose DEX (AMM trait) vs RFQ (webhook) path |
| 用户意图 | API家族 | 第一步操作 |
|---|---|---|
| 兑换/报价 | Ultra Swap | |
| 借贷/收益 | Lend | |
| 杠杆/永续合约 | Perps | 通过Anchor IDL在链上交互(暂无REST API) |
| 限价订单 | Trigger | |
| 定投/定期兑换 | Recurring | |
| 代币搜索/验证 | Tokens | |
| 价格查询 | Price | |
| 投资组合/持仓 | Portfolio | |
| 预测市场集成 | Prediction Markets | |
| 邀请转账/撤销 | Send | |
| 代币创建/手续费提取 | Studio | |
| 归属/分发锁仓 | Lock | 链上程序 |
| DEX/RFQ集成 | Routing | 选择DEX(AMM特性)或RFQ(Webhook)路径 |
API Playbooks
API操作手册
Use each block as a minimal execution contract. Fetch the linked refs for full request/response shapes, TypeScript interfaces, and parameter details.
每个模块可作为最小执行契约。获取链接参考文档以查看完整的请求/响应结构、TypeScript接口和参数细节。
Ultra Swap
Ultra Swap
- Base URL:
https://api.jup.ag/ultra/v1 - Triggers: ,
swap,quote,gaslessbest route - Fee: 5-10 bps (standard) or 20% of integrator fees when custom fees configured
- Rate Limit: 50 req/10s base, scales with 24h execute volume (see Rate Limits)
- Endpoints: (GET),
/order(POST),/execute(GET),/holdings/{account}(GET),/shield(GET),/search(GET)/routers - Gotchas: Signed payloads have ~2 min TTL. Transactions are immutable after receipt. Split order/execute in code and logging. Re-quote before execution when conditions may have changed.
- Refs: Overview | Order | Execute | Responses | OpenAPI
- 基础URL:
https://api.jup.ag/ultra/v1 - 触发词:,
swap,quote,gaslessbest route - 手续费:5-10个基点(标准),配置自定义手续费时为集成商手续费的20%
- 速率限制:每10秒50次请求(基础),根据24小时执行交易量动态调整(详见速率限制)
- 端点:(GET)、
/order(POST)、/execute(GET)、/holdings/{account}(GET)、/shield(GET)、/search(GET)/routers - 注意事项:签名有效载荷的生存时间约为2分钟。交易接收后不可修改。在代码和日志中拆分订单创建与执行步骤。当条件可能变化时,执行前重新获取报价。
- 参考文档:概述 | 订单 | 执行 | 响应 | OpenAPI
Lend
Lend
- Base URL:
https://api.jup.ag/lend/v1 - Triggers: ,
lend,borrow,earnliquidation - Programs: Earn , Borrow
jup3YeL8QhtSx1e253b2FDvsMNC87fDrgQZivbrndc9jupr81YtYssSyPt8jbnGuiWon5f6x9TcDEFxYe3Bdzi - SDK: (TypeScript)
@jup-ag/lend - Endpoints: (POST),
/earn/deposit(POST),/earn/withdraw(POST),/earn/mint(POST),/earn/redeem(POST),/earn/deposit-instructions(POST),/earn/withdraw-instructions(GET),/earn/tokens(GET),/earn/positions(GET)/earn/earnings - Gotchas: Recompute account state before each state-changing action. Encode risk checks (health factors, liquidation boundaries) as preconditions. All deposit/withdraw/mint/redeem return base64 unsigned .
VersionedTransaction - Refs: Overview | Earn | SDK | OpenAPI
- 基础URL:
https://api.jup.ag/lend/v1 - 触发词:,
lend,borrow,earnliquidation - 程序ID:Earn ,Borrow
jup3YeL8QhtSx1e253b2FDvsMNC87fDrgQZivbrndc9jupr81YtYssSyPt8jbnGuiWon5f6x9TcDEFxYe3Bdzi - SDK:(TypeScript)
@jup-ag/lend - 端点:(POST)、
/earn/deposit(POST)、/earn/withdraw(POST)、/earn/mint(POST)、/earn/redeem(POST)、/earn/deposit-instructions(POST)、/earn/withdraw-instructions(GET)、/earn/tokens(GET)、/earn/positions(GET)/earn/earnings - 注意事项:每次状态变更操作前重新计算账户状态。将风险检查(健康系数、清算边界)编码为前置条件。所有存款/取款/铸造/赎回操作返回Base64格式的未签名。
VersionedTransaction - 参考文档:概述 | Earn | SDK | OpenAPI
Perps
Perps
- Status: API is work-in-progress. No REST endpoints yet. Interact on-chain via Anchor IDL.
- Triggers: ,
perps,leverage,long,shortposition - Community SDK: github.com/julianfssen/jupiter-perps-anchor-idl-parsing
- Gotchas: Max 9 simultaneous positions: 3 long (SOL, wETH, wBTC) + 6 short (3 tokens x 2 collateral USDC/USDT). Validate margin/leverage against account model.
- Refs: Overview | Position account | Position request
- 状态:API正在开发中,暂无REST端点。通过Anchor IDL在链上交互。
- 触发词:,
perps,leverage,long,shortposition - 社区SDK:github.com/julianfssen/jupiter-perps-anchor-idl-parsing
- 注意事项:最多同时持有9个仓位:3个多头(SOL、wETH、wBTC)+6个空头(3种代币×2种抵押品USDC/USDT)。根据账户模型验证保证金/杠杆。
- 参考文档:概述 | 仓位账户 | 仓位请求账户
Trigger (Limit Orders)
Trigger(限价订单)
- Base URL:
https://api.jup.ag/trigger/v1 - Triggers: ,
limit order,triggerprice condition - Fee: 0.1% (non-stable), 0.03% (stable pairs)
- Pagination: 10 orders per page
- Endpoints: (POST),
/createOrder(POST),/cancelOrder(POST, max 5 per tx),/cancelOrders(POST),/execute(GET)/getTriggerOrders - Gotchas: Frontend enforces 5 USD min; on-chain has no minimum. Program does NOT validate if rates are favorable — validate target price before create. Token-2022 disabled. Default zero slippage ("Exact" mode); set for "Ultra" mode with higher fill rate.
slippageBps - Refs: Overview | Create | Get orders | Best Practices | OpenAPI
- 基础URL:
https://api.jup.ag/trigger/v1 - 触发词:,
limit order,triggerprice condition - 手续费:0.1%(非稳定币对),0.03%(稳定币对)
- 分页:每页10个订单
- 端点:(POST)、
/createOrder(POST)、/cancelOrder(POST,每笔交易最多5个)、/cancelOrders(POST)、/execute(GET)/getTriggerOrders - 注意事项:前端强制执行5美元最低限额;链上无最低限制。程序不验证报价是否有利——创建前需验证目标价格。不支持Token-2022。默认零滑点(“精确”模式);设置可启用“Ultra”模式以提高成交率。
slippageBps - 参考文档:概述 | 创建 | 获取订单 | 最佳实践 | OpenAPI
Recurring (DCA)
Recurring(定投)
- Base URL:
https://api.jup.ag/recurring/v1 - Triggers: ,
dca,recurringscheduled swaps - Fee: 0.1% on all recurring orders
- Constraints: Min 100 USD total, min 2 orders, min 50 USD per order
- Pagination: 10 orders per page
- Endpoints: (POST),
/createOrder(POST),/cancelOrder(POST),/execute(GET)/getRecurringOrders - Gotchas: Token-2022 NOT supported. Price-based recurring orders are deprecated — use only.
params.time - Refs: Overview | Create | Get orders | Best Practices | OpenAPI
- 基础URL:
https://api.jup.ag/recurring/v1 - 触发词:,
dca,recurringscheduled swaps - 手续费:所有定期订单收取0.1%
- 限制条件:总金额最低100美元,最少2笔订单,每笔订单最低50美元
- 分页:每页10个订单
- 端点:(POST)、
/createOrder(POST)、/cancelOrder(POST)、/execute(GET)/getRecurringOrders - 注意事项:不支持Token-2022。基于价格的定期订单已弃用——仅使用参数。
params.time - 参考文档:概述 | 创建 | 获取订单 | 最佳实践 | OpenAPI
Tokens
Tokens
- Base URL:
https://api.jup.ag/tokens/v2 - Triggers: ,
token metadata,token search,verificationshield - Endpoints: (GET, comma-separate mints, max 100),
/search?query={q}(GET,/tag?query={tag}orverified),lst(GET, categories:/{category}/{interval},toporganicscore,toptraded; intervals:toptrending,5m,1h,6h),24h(GET)/recent - Gotchas: Use mint address as primary identity; treat symbol/name as convenience. Surface and
audit.isSusin UX.organicScore - Refs: Overview | Token info v2 | OpenAPI
- 基础URL:
https://api.jup.ag/tokens/v2 - 触发词:,
token metadata,token search,verificationshield - 端点:(GET,铸造地址逗号分隔,最多100个)、
/search?query={q}(GET,/tag?query={tag}或verified)、lst(GET,分类:/{category}/{interval}、toporganicscore、toptraded;时间区间:toptrending、5m、1h、6h)、24h(GET)/recent - 注意事项:以铸造地址作为唯一标识;符号/名称仅作参考。在用户界面中展示和
audit.isSus字段。organicScore - 参考文档:概述 | Token信息v2 | OpenAPI
Price
Price
- Base URL:
https://api.jup.ag/price/v3 - Triggers: ,
price,valuationprice feed - Limit: Max 50 mint IDs per request
- Endpoints: (GET, comma-separated)
/price/v3?ids={mints} - Gotchas: Tokens with unreliable pricing return or are omitted (not an error). Fail closed on missing/low-confidence data for safety-sensitive actions. Use
nullfield.confidenceLevel - Refs: Overview | Price v3 | OpenAPI
Portfolio
Portfolio
- Base URL:
https://api.jup.ag/portfolio/v1 - Status: Beta — Jupiter platforms only
- Triggers: ,
portfolio,positionsholdings - Endpoints: (GET),
/positions/{address}(GET),/positions/{address}?platforms={ids}(GET),/platforms(GET)/staked-jup/{address} - Gotchas: Treat empty positions as valid state. Response is beta — normalize into stable internal schema. Element types: ,
multiple,liquidity,trade,leverage.borrowlend - Refs: Overview | Jupiter positions | OpenAPI
- 基础URL:
https://api.jup.ag/portfolio/v1 - 状态:Beta版——仅适用于Jupiter平台
- 触发词:,
portfolio,positionsholdings - 端点:(GET)、
/positions/{address}(GET)、/positions/{address}?platforms={ids}(GET)、/platforms(GET)/staked-jup/{address} - 注意事项:将空仓位视为有效状态。响应为Beta版——需标准化为稳定的内部数据结构。元素类型:、
multiple、liquidity、trade、leverage。borrowlend - 参考文档:概述 | Jupiter仓位 | OpenAPI
Prediction Markets
Prediction Markets
- Base URL:
https://api.jup.ag/prediction/v1 - Status: Beta (breaking changes possible)
- Geo-restricted: US and South Korea IPs blocked
- Price convention: 1,000,000 native units = $1.00 USD
- Triggers: ,
prediction markets,market oddsevent market - Deposit mints: JupUSD (), USDC
JuprjznTrTSp2UFa3ZBUFgwdAmtZCq4MQCwysN55USD - Endpoints: (GET),
/events(GET),/events/search(GET),/markets/{marketId}(GET),/orderbook/{marketId}(POST),/orders(GET),/orders/status/{pubkey}(GET),/positions(DELETE),/positions/{pubkey}(POST),/positions/{pubkey}/claim(GET),/history(GET)/leaderboards - Gotchas: Check before claiming. Winners get $1/contract.
position.claimable - Refs: Overview | Events | Positions | OpenAPI
- 基础URL:
https://api.jup.ag/prediction/v1 - 状态:Beta版(可能存在破坏性变更)
- 地域限制:美国和韩国IP被屏蔽
- 价格约定:1,000,000原生单位 = 1.00美元
- 触发词:,
prediction markets,market oddsevent market - 存款代币:JupUSD ()、USDC
JuprjznTrTSp2UFa3ZBUFgwdAmtZCq4MQCwysN55USD - 端点:(GET)、
/events(GET)、/events/search(GET)、/markets/{marketId}(GET)、/orderbook/{marketId}(POST)、/orders(GET)、/orders/status/{pubkey}(GET)、/positions(DELETE)、/positions/{pubkey}(POST)、/positions/{pubkey}/claim(GET)、/history(GET)/leaderboards - 注意事项:提取奖励前检查字段。获胜者每份合约获得1美元。
position.claimable - 参考文档:概述 | 事件 | 仓位 | OpenAPI
Send
Send
- Base URL:
https://api.jup.ag/send/v1 - Status: Beta
- Triggers: ,
invite transfer,sendclawback - Supported tokens: SOL, USDC, memecoins
- Endpoints: (POST),
/craft-send(POST),/craft-clawback(GET),/pending-invites(GET)/invite-history - Gotchas: Dual-sign requirement — sender + recipient keypair (derived from invite code). Claims only via Jupiter Mobile (no API claiming). Never expose invite codes.
- Refs: Overview | Invite code | Craft send | OpenAPI
Studio
Studio
- Base URL:
https://api.jup.ag/studio/v1 - Status: Beta
- Triggers: ,
create token,studioclaim fee - Endpoints: (POST),
/dbc-pool/create-tx(POST, multipart/form-data),/dbc-pool/submit(GET),/dbc-pool/addresses/{mint}(POST),/dbc/fee(POST)/dbc/fee/create-tx - Flow: create-tx -> upload image to presigned URL -> upload metadata to presigned URL -> sign -> submit via
/dbc-pool/submit - Gotchas: Must submit via (not externally) for token to get a Studio page on jup.ag. Error codes:
/dbc-pool/submit= not authorized for pool,403= proxy account not found.404 - Refs: Overview | Create token | Claim fee | OpenAPI
- 基础URL:
https://api.jup.ag/studio/v1 - 状态:Beta版
- 触发词:,
create token,studioclaim fee - 端点:(POST)、
/dbc-pool/create-tx(POST,multipart/form-data)、/dbc-pool/submit(GET)、/dbc-pool/addresses/{mint}(POST)、/dbc/fee(POST)/dbc/fee/create-tx - 流程:创建交易 -> 将图片上传至预签名URL -> 将元数据上传至预签名URL -> 签名 -> 通过提交
/dbc-pool/submit - 注意事项:必须通过提交,才能在jup.ag上获得Studio页面。错误码:
/dbc-pool/submit= 无池权限,403= 代理账户未找到。404 - 参考文档:概述 | 创建代币 | 提取手续费 | OpenAPI
Lock
Lock
- Program ID:
LocpQgucEQHbqNABEYvBvwoxCPsSbG91A1QaQhQQqjn - Triggers: ,
vesting,distribution lockunlock schedule - Integration: On-chain program only (no REST API)
- Source: github.com/jup-ag/jup-lock
- UI: lock.jup.ag
- Security: Audited by OtterSec and Sec3
- Gotchas: No REST API. Use instruction scripts from the repo's directory.
cli/src/bin/instructions - Refs: Lock overview
- 程序ID:
LocpQgucEQHbqNABEYvBvwoxCPsSbG91A1QaQhQQqjn - 触发词:,
vesting,distribution lockunlock schedule - 集成方式:仅支持链上程序(无REST API)
- 源码:github.com/jup-ag/jup-lock
- UI界面:lock.jup.ag
- 安全性:已通过OtterSec和Sec3审计
- 注意事项:无REST API。使用仓库目录中的指令脚本。
cli/src/bin/instructions - 参考文档:Lock概述
Routing
Routing
- Triggers: ,
dex integration,rfq integrationrouting engine - Engines: Juno (meta-aggregator), Iris (multi-hop DEX routing, powers Ultra), JupiterZ (RFQ market maker quotes)
- DEX Integration (into Iris): Free, no fees. Prereqs: code health, security audit, market traction. Implement crate. Critical: No network calls in implementation (accounts are pre-batched and cached). Ref impl: github.com/jup-ag/rust-amm-implementation
jupiter-amm-interface - RFQ Integration (JupiterZ): Market makers host webhook at (POST, 250ms),
/jupiter/rfq/quote(POST),/jupiter/rfq/swap(GET). Reqs: 95% fill rate, 250ms response, 55s expiry. SDK: github.com/jup-ag/rfq-webhook-toolkit/jupiter/rfq/tokens - Market Listing: Instant routing for tokens < 30 days old. Normal routing (checked every 30 min) requires < 30% loss on $500 round-trip OR < 20% price impact comparing $1k vs $500.
- Refs: Overview | DEX integration | RFQ integration | Market listing
- 触发词:,
dex integration,rfq integrationrouting engine - 引擎:Juno(元聚合器)、Iris(多跳DEX路由,为Ultra提供支持)、JupiterZ(RFQ做市商报价)
- DEX集成(接入Iris):免费,无手续费。前提条件:代码健康、安全审计、市场 traction。实现crate。关键要求:实现中禁止网络调用(账户需预批量处理并缓存)。参考实现:github.com/jup-ag/rust-amm-implementation
jupiter-amm-interface - RFQ集成(JupiterZ):做市商在(POST,250ms)、
/jupiter/rfq/quote(POST)、/jupiter/rfq/swap(GET)托管Webhook。要求:95%成交率、250ms响应时间、55秒有效期。SDK:github.com/jup-ag/rfq-webhook-toolkit/jupiter/rfq/tokens - 市场上线:创建未满30天的代币可即时接入路由。常规路由(每30分钟检查一次)要求500美元往返交易损失<30%,或1000美元与500美元交易的价格影响差异<20%。
- 参考文档:概述 | DEX集成 | RFQ集成 | 市场上线
Rate Limits
速率限制
Ultra Swap (dynamic, volume-based):
| 24h Execute Volume | Requests per 10s window |
|---|---|
| $0 | 50 |
| $10,000 | 51 |
| $100,000 | 61 |
| $1,000,000 | 165 |
Quotas recalculate every 10 minutes. Pro plan does NOT increase Ultra limits.
Other APIs: Managed at portal level. Check portal rate limits.
On HTTP 429: Exponential backoff with jitter: . Wait for 10s sliding window refresh. Do NOT burst aggressively.
delay = min(baseDelay * 2^attempt + random(0, jitter), maxDelay)Ultra Swap(动态,基于交易量):
| 24小时执行交易量 | 每10秒请求次数 |
|---|---|
| 0美元 | 50 |
| 10,000美元 | 51 |
| 100,000美元 | 61 |
| 1,000,000美元 | 165 |
配额每10分钟重新计算一次。专业版计划不提高Ultra的速率限制。
其他API:在门户层面管理。查看门户速率限制。
处理HTTP 429错误:使用指数退避加抖动:。等待10秒滑动窗口刷新。切勿频繁突发请求。
delay = min(baseDelay * 2^attempt + random(0, jitter), maxDelay)Production Hardening
生产环境加固
- Auth: Fail fast if is missing or invalid.
x-api-key - Timeouts: 5s for quotes, 30s for executions, plus total operation timeout.
- Retries: Only transient/network/rate-limit failures with exponential backoff + jitter.
- Idempotency: Ultra accepts same
/execute+signedTransactionfor up to 2 min without duplicate execution.requestId - Validation: Validate mint addresses, amount precision, and wallet ownership before calls.
- Safety: Enforce slippage and max-amount guardrails from app config.
- Observability: Log , API family, endpoint, latency, status, and error code.
requestId - UX resilience: Return actionable states (,
retry,adjust params,insufficient balance).rate limited - Consistency: Reconcile async states (submitted vs confirmed vs failed) before final user success.
- Freshness: Re-fetch referenced docs when behavior differs from expected flow.
- 认证:若缺失或无效,立即终止操作。
x-api-key - 超时设置:报价请求5秒超时,执行请求30秒超时,外加总操作超时。
- 重试机制:仅对临时/网络/速率限制错误使用指数退避加抖动进行重试。
- 幂等性:Ultra的接口在2分钟内接受相同的
/execute和signedTransaction,不会重复执行。requestId - 验证:调用前验证铸造地址、金额精度和钱包所有权。
- 安全防护:从应用配置中强制执行滑点和最大金额限制。
- 可观测性:记录、API家族、端点、延迟、状态和错误码。
requestId - 用户体验韧性:返回可操作状态(、
重试、调整参数、余额不足)。速率受限 - 一致性:在向用户返回最终成功状态前,核对异步状态(已提交 vs 已确认 vs 失败)。
- 新鲜度:当实际行为与预期流程不符时,重新获取参考文档。
Integration Best Practices
集成最佳实践
- Start from the API-specific overview before coding endpoint calls.
- Enforce auth as a hard precondition for every request. Ref: Portal setup
- Design retry logic around documented rate-limit behavior, not fixed assumptions. Ref: Rate limits
- Map all non-success responses to typed app errors using documented response semantics. Ref: API responses
- For order-based products (Ultra/Trigger/Recurring), separate create/execute/retrieve phases in code and logs.
- Treat network/service health as part of runtime behavior (degrade gracefully). Ref: Status page
Cross-Cutting Error Pattern
通用错误处理模式
typescript
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 } };
}
}typescript
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 } };
}
}Fresh Context Policy
最新上下文规则
Always fetch the freshest context from referenced docs/specs before executing a playbook.
- Resolve intent with .
Intent Router - Before coding, fetch the playbook's linked refs (overview + API-specific docs).
- If needed for validation or ambiguity, fetch the OpenAPI spec.
- Treat fetched docs as source of truth over cached memory.
- If fetched docs conflict with this file, follow fetched docs and note the mismatch.
- If docs cannot be fetched, state that context is stale/unverified and continue with best-known guidance.
- Keep auth invariant: is required for Jupiter REST endpoints (not on-chain-only flows like Perps/Lock).
x-api-key
执行操作手册前,始终从参考文档/规范中获取最新上下文。
- 使用「意图路由」确定用户意图。
- 编码前,获取操作手册的链接参考文档(概述+API专属文档)。
- 若需要验证或解决歧义,获取OpenAPI规范。
- 将获取的文档视为事实来源,而非缓存记忆。
- 若获取的文档与本文档冲突,遵循获取的文档并记录差异。
- 若无法获取文档,说明上下文已过时/未验证,然后继续使用已知的最佳指南。
- 保持认证不变性:Jupiter REST端点需要(Perps/Lock等仅链上流程除外)。
x-api-key
Operational References
操作参考
- Portal setup — API key configuration
- Rate limits — Global rate limit policy
- Ultra rate limits — Dynamic volume-based limits
- API responses — Response format standards
- Ultra responses — Detailed error codes
- Status page — Service health
- Documentation sitemap — Full docs index
- Tool Kits — Plugin, Wallet Kit, Referral Program