integrating-jupiter

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Jupiter API Integration

Jupiter API 集成

Single skill for all Jupiter APIs, optimized for fast routing and deterministic execution.
Base URL:
https://api.jup.ag
Auth:
x-api-key
from portal.jup.ag (required for Jupiter REST endpoints)
一站式掌握所有Jupiter API技能,针对快速路由和确定性执行进行优化。
基础URL
https://api.jup.ag
认证方式:使用portal.jup.ag获取的
x-api-key
Jupiter REST端点必填

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:
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
适用场景:
  • 任务需要选择或调用Jupiter端点时
  • 任务涉及兑换、借贷、永续合约、订单、定价、投资组合、转账、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

Developer 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 intentAPI familyFirst action
Swap/quoteUltra Swap
GET /ultra/v1/order
-> sign ->
POST /ultra/v1/execute
Lend/borrow/yieldLend
POST /lend/v1/earn/deposit
or
/withdraw
Leverage/perpsPerpsOn-chain via Anchor IDL (no REST API yet)
Limit ordersTrigger
POST /trigger/v1/createOrder
-> sign ->
POST /trigger/v1/execute
DCA/recurring buysRecurring
POST /recurring/v1/createOrder
-> sign ->
POST /recurring/v1/execute
Token search/verificationTokens
GET /tokens/v2/search?query={mint}
Price lookupPrice
GET /price/v3?ids={mints}
Portfolio/positionsPortfolio
GET /portfolio/v1/positions/{address}
Prediction market integrationPrediction Markets
GET /prediction/v1/events
->
POST /prediction/v1/orders
Invite send/clawbackSend
POST /send/v1/craft-send
-> sign -> send to RPC
Token creation/feesStudio
POST /studio/v1/dbc-pool/create-tx
-> upload -> submit
Vesting/distributionLockOn-chain program
LocpQgucEQHbqNABEYvBvwoxCPsSbG91A1QaQhQQqjn
DEX/RFQ integrationRoutingChoose DEX (AMM trait) vs RFQ (webhook) path
用户意图API家族第一步操作
兑换/报价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
定投/定期兑换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特性)或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
    ,
    gasless
    ,
    best 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:
    /order
    (GET),
    /execute
    (POST),
    /holdings/{account}
    (GET),
    /shield
    (GET),
    /search
    (GET),
    /routers
    (GET)
  • 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
    ,
    gasless
    ,
    best route
  • 手续费:5-10个基点(标准),配置自定义手续费时为集成商手续费的20%
  • 速率限制:每10秒50次请求(基础),根据24小时执行交易量动态调整(详见速率限制
  • 端点
    /order
    (GET)、
    /execute
    (POST)、
    /holdings/{account}
    (GET)、
    /shield
    (GET)、
    /search
    (GET)、
    /routers
    (GET)
  • 注意事项:签名有效载荷的生存时间约为2分钟。交易接收后不可修改。在代码和日志中拆分订单创建与执行步骤。当条件可能变化时,执行前重新获取报价。
  • 参考文档概述 | 订单 | 执行 | 响应 | OpenAPI

Lend

Lend

  • Base URL:
    https://api.jup.ag/lend/v1
  • Triggers:
    lend
    ,
    borrow
    ,
    earn
    ,
    liquidation
  • Programs: Earn
    jup3YeL8QhtSx1e253b2FDvsMNC87fDrgQZivbrndc9
    , Borrow
    jupr81YtYssSyPt8jbnGuiWon5f6x9TcDEFxYe3Bdzi
  • SDK:
    @jup-ag/lend
    (TypeScript)
  • Endpoints:
    /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)
  • 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
    ,
    earn
    ,
    liquidation
  • 程序ID: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)
  • 注意事项:每次状态变更操作前重新计算账户状态。将风险检查(健康系数、清算边界)编码为前置条件。所有存款/取款/铸造/赎回操作返回Base64格式的未签名
    VersionedTransaction
  • 参考文档概述 | Earn | SDK | OpenAPI

Perps

Perps



Trigger (Limit Orders)

Trigger(限价订单)

  • Base URL:
    https://api.jup.ag/trigger/v1
  • Triggers:
    limit order
    ,
    trigger
    ,
    price condition
  • Fee: 0.1% (non-stable), 0.03% (stable pairs)
  • Pagination: 10 orders per page
  • Endpoints:
    /createOrder
    (POST),
    /cancelOrder
    (POST),
    /cancelOrders
    (POST, max 5 per tx),
    /execute
    (POST),
    /getTriggerOrders
    (GET)
  • 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
    slippageBps
    for "Ultra" mode with higher fill rate.
  • Refs: Overview | Create | Get orders | Best Practices | OpenAPI

  • 基础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美元最低限额;链上无最低限制。程序不验证报价是否有利——创建前需验证目标价格。不支持Token-2022。默认零滑点(“精确”模式);设置
    slippageBps
    可启用“Ultra”模式以提高成交率。
  • 参考文档概述 | 创建 | 获取订单 | 最佳实践 | OpenAPI

Recurring (DCA)

Recurring(定投)

  • Base URL:
    https://api.jup.ag/recurring/v1
  • Triggers:
    dca
    ,
    recurring
    ,
    scheduled 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:
    /createOrder
    (POST),
    /cancelOrder
    (POST),
    /execute
    (POST),
    /getRecurringOrders
    (GET)
  • Gotchas: Token-2022 NOT supported. Price-based recurring orders are deprecated — use
    params.time
    only.
  • Refs: Overview | Create | Get orders | Best Practices | OpenAPI

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

Tokens

Tokens

  • Base URL:
    https://api.jup.ag/tokens/v2
  • Triggers:
    token metadata
    ,
    token search
    ,
    verification
    ,
    shield
  • Endpoints:
    /search?query={q}
    (GET, comma-separate mints, max 100),
    /tag?query={tag}
    (GET,
    verified
    or
    lst
    ),
    /{category}/{interval}
    (GET, categories:
    toporganicscore
    ,
    toptraded
    ,
    toptrending
    ; intervals:
    5m
    ,
    1h
    ,
    6h
    ,
    24h
    ),
    /recent
    (GET)
  • Gotchas: Use mint address as primary identity; treat symbol/name as convenience. Surface
    audit.isSus
    and
    organicScore
    in UX.
  • Refs: Overview | Token info v2 | OpenAPI

  • 基础URL
    https://api.jup.ag/tokens/v2
  • 触发词
    token metadata
    ,
    token search
    ,
    verification
    ,
    shield
  • 端点
    /search?query={q}
    (GET,铸造地址逗号分隔,最多100个)、
    /tag?query={tag}
    (GET,
    verified
    lst
    )、
    /{category}/{interval}
    (GET,分类:
    toporganicscore
    toptraded
    toptrending
    ;时间区间:
    5m
    1h
    6h
    24h
    )、
    /recent
    (GET)
  • 注意事项:以铸造地址作为唯一标识;符号/名称仅作参考。在用户界面中展示
    audit.isSus
    organicScore
    字段。
  • 参考文档概述 | Token信息v2 | OpenAPI

Price

Price

  • Base URL:
    https://api.jup.ag/price/v3
  • Triggers:
    price
    ,
    valuation
    ,
    price feed
  • Limit: Max 50 mint IDs per request
  • Endpoints:
    /price/v3?ids={mints}
    (GET, comma-separated)
  • Gotchas: Tokens with unreliable pricing return
    null
    or are omitted (not an error). Fail closed on missing/low-confidence data for safety-sensitive actions. Use
    confidenceLevel
    field.
  • Refs: Overview | Price v3 | OpenAPI

  • 基础URL
    https://api.jup.ag/price/v3
  • 触发词
    price
    ,
    valuation
    ,
    price feed
  • 限制:每次请求最多50个铸造ID
  • 端点
    /price/v3?ids={mints}
    (GET,逗号分隔)
  • 注意事项:定价不可靠的代币会返回
    null
    或被省略(非错误)。对于安全敏感操作,若数据缺失或置信度低则终止操作。使用
    confidenceLevel
    字段。
  • 参考文档概述 | Price v3 | OpenAPI

Portfolio

Portfolio

  • Base URL:
    https://api.jup.ag/portfolio/v1
  • Status: Beta — Jupiter platforms only
  • Triggers:
    portfolio
    ,
    positions
    ,
    holdings
  • Endpoints:
    /positions/{address}
    (GET),
    /positions/{address}?platforms={ids}
    (GET),
    /platforms
    (GET),
    /staked-jup/{address}
    (GET)
  • 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
    ,
    positions
    ,
    holdings
  • 端点
    /positions/{address}
    (GET)、
    /positions/{address}?platforms={ids}
    (GET)、
    /platforms
    (GET)、
    /staked-jup/{address}
    (GET)
  • 注意事项:将空仓位视为有效状态。响应为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 odds
    ,
    event market
  • Deposit mints: JupUSD (
    JuprjznTrTSp2UFa3ZBUFgwdAmtZCq4MQCwysN55USD
    ), USDC
  • Endpoints:
    /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)
  • Gotchas: Check
    position.claimable
    before claiming. Winners get $1/contract.
  • Refs: Overview | Events | Positions | OpenAPI

  • 基础URL
    https://api.jup.ag/prediction/v1
  • 状态:Beta版(可能存在破坏性变更)
  • 地域限制:美国和韩国IP被屏蔽
  • 价格约定:1,000,000原生单位 = 1.00美元
  • 触发词
    prediction markets
    ,
    market odds
    ,
    event market
  • 存款代币: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美元。
  • 参考文档概述 | 事件 | 仓位 | OpenAPI

Send

Send

  • Base URL:
    https://api.jup.ag/send/v1
  • Status: Beta
  • Triggers:
    invite transfer
    ,
    send
    ,
    clawback
  • Supported tokens: SOL, USDC, memecoins
  • Endpoints:
    /craft-send
    (POST),
    /craft-clawback
    (POST),
    /pending-invites
    (GET),
    /invite-history
    (GET)
  • 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

  • 基础URL
    https://api.jup.ag/send/v1
  • 状态:Beta版
  • 触发词
    invite transfer
    ,
    send
    ,
    clawback
  • 支持代币:SOL、USDC、迷因币
  • 端点
    /craft-send
    (POST)、
    /craft-clawback
    (POST)、
    /pending-invites
    (GET)、
    /invite-history
    (GET)
  • 注意事项:需要双重签名——发送方+接收方密钥对(从邀请码派生)。仅可通过Jupiter Mobile提取奖励(无API提取方式)。切勿泄露邀请码。
  • 参考文档概述 | 邀请码 | 创建转账 | OpenAPI

Studio

Studio

  • Base URL:
    https://api.jup.ag/studio/v1
  • Status: Beta
  • Triggers:
    create token
    ,
    studio
    ,
    claim fee
  • Endpoints:
    /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)
  • Flow: create-tx -> upload image to presigned URL -> upload metadata to presigned URL -> sign -> submit via
    /dbc-pool/submit
  • Gotchas: Must submit via
    /dbc-pool/submit
    (not externally) for token to get a Studio page on jup.ag. Error codes:
    403
    = not authorized for pool,
    404
    = proxy account not found.
  • Refs: Overview | Create token | Claim fee | OpenAPI

  • 基础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)
  • 流程:创建交易 -> 将图片上传至预签名URL -> 将元数据上传至预签名URL -> 签名 -> 通过
    /dbc-pool/submit
    提交
  • 注意事项:必须通过
    /dbc-pool/submit
    提交,才能在jup.ag上获得Studio页面。错误码:
    403
    = 无池权限,
    404
    = 代理账户未找到。
  • 参考文档概述 | 创建代币 | 提取手续费 | OpenAPI

Lock

Lock

  • Program ID:
    LocpQgucEQHbqNABEYvBvwoxCPsSbG91A1QaQhQQqjn
  • Triggers:
    vesting
    ,
    distribution lock
    ,
    unlock 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
    cli/src/bin/instructions
    directory.
  • Refs: Lock overview

  • 程序ID
    LocpQgucEQHbqNABEYvBvwoxCPsSbG91A1QaQhQQqjn
  • 触发词
    vesting
    ,
    distribution lock
    ,
    unlock 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 integration
    ,
    routing 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
    jupiter-amm-interface
    crate. Critical: No network calls in implementation (accounts are pre-batched and cached). Ref impl: github.com/jup-ag/rust-amm-implementation
  • RFQ Integration (JupiterZ): Market makers host webhook at
    /jupiter/rfq/quote
    (POST, 250ms),
    /jupiter/rfq/swap
    (POST),
    /jupiter/rfq/tokens
    (GET). Reqs: 95% fill rate, 250ms response, 55s expiry. SDK: github.com/jup-ag/rfq-webhook-toolkit
  • 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 integration
    ,
    routing engine
  • 引擎:Juno(元聚合器)、Iris(多跳DEX路由,为Ultra提供支持)、JupiterZ(RFQ做市商报价)
  • DEX集成(接入Iris):免费,无手续费。前提条件:代码健康、安全审计、市场 traction。实现
    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响应时间、55秒有效期。SDK:github.com/jup-ag/rfq-webhook-toolkit
  • 市场上线:创建未满30天的代币可即时接入路由。常规路由(每30分钟检查一次)要求500美元往返交易损失<30%,或1000美元与500美元交易的价格影响差异<20%。
  • 参考文档概述 | DEX集成 | RFQ集成 | 市场上线

Rate Limits

速率限制

Ultra Swap (dynamic, volume-based):
24h Execute VolumeRequests per 10s window
$050
$10,00051
$100,00061
$1,000,000165
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:
delay = min(baseDelay * 2^attempt + random(0, jitter), maxDelay)
. Wait for 10s sliding window refresh. Do NOT burst aggressively.
Ultra Swap(动态,基于交易量)
24小时执行交易量每10秒请求次数
0美元50
10,000美元51
100,000美元61
1,000,000美元165
配额每10分钟重新计算一次。专业版计划不提高Ultra的速率限制。
其他API:在门户层面管理。查看门户速率限制
处理HTTP 429错误:使用指数退避加抖动:
delay = min(baseDelay * 2^attempt + random(0, jitter), maxDelay)
。等待10秒滑动窗口刷新。切勿频繁突发请求。

Production Hardening

生产环境加固

  1. Auth: Fail fast if
    x-api-key
    is missing or invalid.
  2. Timeouts: 5s for quotes, 30s for executions, plus total operation timeout.
  3. Retries: Only transient/network/rate-limit failures with exponential backoff + jitter.
  4. Idempotency: Ultra
    /execute
    accepts same
    signedTransaction
    +
    requestId
    for up to 2 min without duplicate execution.
  5. Validation: Validate mint addresses, amount precision, and wallet ownership before calls.
  6. Safety: Enforce slippage and max-amount guardrails from app config.
  7. Observability: Log
    requestId
    , API family, endpoint, latency, status, and error code.
  8. UX resilience: Return actionable states (
    retry
    ,
    adjust params
    ,
    insufficient balance
    ,
    rate limited
    ).
  9. Consistency: Reconcile async states (submitted vs confirmed vs failed) before final user success.
  10. Freshness: Re-fetch referenced docs when behavior differs from expected flow.
  1. 认证:若
    x-api-key
    缺失或无效,立即终止操作。
  2. 超时设置:报价请求5秒超时,执行请求30秒超时,外加总操作超时。
  3. 重试机制:仅对临时/网络/速率限制错误使用指数退避加抖动进行重试。
  4. 幂等性:Ultra的
    /execute
    接口在2分钟内接受相同的
    signedTransaction
    requestId
    ,不会重复执行。
  5. 验证:调用前验证铸造地址、金额精度和钱包所有权。
  6. 安全防护:从应用配置中强制执行滑点和最大金额限制。
  7. 可观测性:记录
    requestId
    、API家族、端点、延迟、状态和错误码。
  8. 用户体验韧性:返回可操作状态(
    重试
    调整参数
    余额不足
    速率受限
    )。
  9. 一致性:在向用户返回最终成功状态前,核对异步状态(已提交 vs 已确认 vs 失败)。
  10. 新鲜度:当实际行为与预期流程不符时,重新获取参考文档。

Integration Best Practices

集成最佳实践

  1. Start from the API-specific overview before coding endpoint calls.
  2. Enforce auth as a hard precondition for every request. Ref: Portal setup
  3. Design retry logic around documented rate-limit behavior, not fixed assumptions. Ref: Rate limits
  4. Map all non-success responses to typed app errors using documented response semantics. Ref: API responses
  5. For order-based products (Ultra/Trigger/Recurring), separate create/execute/retrieve phases in code and logs.
  6. Treat network/service health as part of runtime behavior (degrade gracefully). Ref: Status page
  1. 在编写端点调用代码前,先查看API专属的概述文档。
  2. 将认证作为每个请求的硬性前置条件。参考:门户设置
  3. 根据文档中说明的速率限制行为设计重试逻辑,而非基于固定假设。参考:速率限制
  4. 使用文档中定义的响应语义,将所有非成功响应映射为类型化的应用错误。参考:API响应
  5. 对于基于订单的产品(Ultra/Trigger/Recurring),在代码和日志中分离创建/执行/查询阶段。
  6. 将网络/服务健康状况视为运行时行为的一部分(优雅降级)。参考:状态页面

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.
  1. Resolve intent with
    Intent Router
    .
  2. Before coding, fetch the playbook's linked refs (overview + API-specific docs).
  3. If needed for validation or ambiguity, fetch the OpenAPI spec.
  4. Treat fetched docs as source of truth over cached memory.
  5. If fetched docs conflict with this file, follow fetched docs and note the mismatch.
  6. If docs cannot be fetched, state that context is stale/unverified and continue with best-known guidance.
  7. Keep auth invariant:
    x-api-key
    is required for Jupiter REST endpoints (not on-chain-only flows like Perps/Lock).
执行操作手册前,始终从参考文档/规范中获取最新上下文。
  1. 使用「意图路由」确定用户意图。
  2. 编码前,获取操作手册的链接参考文档(概述+API专属文档)。
  3. 若需要验证或解决歧义,获取OpenAPI规范。
  4. 将获取的文档视为事实来源,而非缓存记忆。
  5. 若获取的文档与本文档冲突,遵循获取的文档并记录差异。
  6. 若无法获取文档,说明上下文已过时/未验证,然后继续使用已知的最佳指南。
  7. 保持认证不变性:Jupiter REST端点需要
    x-api-key
    (Perps/Lock等仅链上流程除外)。

Operational References

操作参考