jupiter

Jupiter — Solana DEX 聚合器

Jupiter 会在所有 Solana DEX（Raydium、Orca、Phoenix……）之间路由兑换，以获取最佳价格。

⛽ Gas 和成本 — 请先阅读

• Gas 始终从钱包 SOL 余额中支付。 Solana 不提供 Gas 赞助。
• wallet_sol_transfer 不适用于 Jupiter — 它仅用于发送 SOL。
• 兑换的费用约为 0.0002–0.001 SOL（优先费 + 新代币账户的租金押金）。
• 创建限价订单的费用约为 0.002 SOL（链上账户租金）。
• 操作前始终调用 wallet_sol_balance()，确认 SOL > 0.01。

⛔ 硬性规则

• 始终使用 ultra/v1/order — 不要使用 swap/v1/quote + swap/v1/swap（已弃用）
• 仅在准备执行时才向 jupiter_swap 传入钱包公钥 — 不传入公钥会返回仅报价结果（不含交易），适用于查询价格
• 绝不要传入数值类型的 makingAmount/takingAmount — 必须使用字符串，否则 API 会返回 ZodError 400
• 绝不要将 /ultra/v1/execute 用于限价订单 — 限价订单必须通过 jupiter_broadcast_tx()（Solana RPC）处理
• 执行兑换或限价订单前，绝不要省略用户确认
• 兑换后始终调用 wallet_sol_balance()，以验证余额是否发生变化
• 绝不要提及 DCA — lite-api 不支持该功能

前置条件 — 钱包策略

执行任何链上操作前，加载 wallet 技能，并建议使用标准 Solana 通配符策略（禁止导出密钥 + 允许 *）。

重要代币地址（Solana）

代币	Mint 地址	小数位数
SOL	So11111111111111111111111111111111111111112	9
USDC	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v	6
USDT	Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB	6
JUP	JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN	6
BONK	DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263	5
WIF	EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm	6
JTO	jtojtomepa8beP8AuQc6eXt5FriJwfFMwQx2v2f9mCL	6（不是 9）

对于未列出的代币：直接向用户询问 mint 地址 — 代币搜索 API 已弃用。

可用工具（来自 exports.py）

工具	功能
jupiter_price(token)	任意代币的 USD 价格
jupiter_swap(in, out, amount, wallet?)	仅报价（不提供钱包）或报价 + 交易（提供钱包）
jupiter_execute_swap(signed_tx, request_id, in_mint?, out_mint?)	通过 /ultra/v1/execute 广播兑换 ← 仅用于兑换
jupiter_broadcast_tx(signed_tx)	通过 Solana RPC 广播 ← 限价订单 + 取消订单
jupiter_limit_create(in, out, making, taking, maker)	创建限价订单
jupiter_limit_orders(wallet, history=False)	列出未完成订单或历史订单
jupiter_limit_cancel(order_pubkey, maker)	取消未完成订单

兑换工作流（端到端）

1. quote = jupiter_swap("SOL", "USDC", 0.01, wallet_pubkey)
   └─ returns: in_amount, out_amount, in_usd, out_usd, transaction, request_id

2. Show user: amount in/out, USD values, price_impact_pct — wait for confirm

3. signed = wallet_sol_sign_transaction(quote["transaction"])

4. result = jupiter_execute_swap(signed["signed_transaction"], quote["request_id"])
   └─ returns: status ("Success"), signature, in_amount, out_amount

5. wallet_sol_balance()  ← verify balances changed

要点：

• jupiter_execute_swap → POST /ultra/v1/execute — 仅用于 Ultra 兑换
• 如果缺少或钱包公钥无效，transaction 会为 null — 使用有效钱包重试步骤 1
• 兑换是原子操作：如果失败，不会扣除任何款项（Gas 费除外）

限价订单工作流（端到端）

1. order = jupiter_limit_create(
       input_token="SOL",    # selling
       output_token="USDC",  # buying
       making_amount=0.06,   # 0.06 SOL to sell
       taking_amount=3.0,    # want at least 3 USDC (sets target price)
       maker=wallet_pubkey
   )
   └─ returns: order_pubkey, transaction, implied_price, next_step

2. Show user: implied price, amounts — wait for confirm

3. signed = wallet_sol_sign_transaction(order["transaction"])
   ⚠️  Sign and broadcast within ~90 seconds — blockhash expires.

4. result = jupiter_broadcast_tx(signed["signed_transaction"])
   └─ returns: {"success": True, "signature": "..."} or {"success": False, "error": "..."}
   ⚠️  Use jupiter_broadcast_tx, NOT jupiter_execute_swap — different endpoints!

5. jupiter_limit_orders(wallet_pubkey)  ← confirm order_pubkey appears
   Note: if order fills instantly (implied price ≤ market), check orderHistory instead

要点：

• 最低订单金额：约 5 USD — 金额更小会返回 {"error": "Order size must be at least 5 USD"}
• 如果你的隐含价格有利（≤ 市场价格），Keeper 可能会立即成交
• API 响应中的 orderKey 字段是订单公钥（不是 publicKey）
• openOrders 中的 makingAmount / takingAmount 已是人类可读格式（例如 "0.06"），不是原始 lamports
• 如果不使用 expiredAt 和 feeBps，必须完全省略这两个字段（不要传入 null 或 0）

取消订单工作流

1. orders = jupiter_limit_orders(wallet_pubkey)
2. Pick order_pubkey from orders["orders"][n]["order_pubkey"]
3. cancel = jupiter_limit_cancel(order_pubkey, wallet_pubkey)
4. signed = wallet_sol_sign_transaction(cancel["transaction"])
5. jupiter_broadcast_tx(signed["signed_transaction"])

工具路由 — IF/THEN

IF "price" / "how much is X"             → jupiter_price(token)
IF "quote" / "how much can I get"        → jupiter_swap(in, out, amount)  [wallet omitted = quote-only, no tx]
IF "swap" / "exchange" / "convert"       → jupiter_swap(in, out, amount, wallet) → confirm → sign → jupiter_execute_swap(in_mint, out_mint)
IF "limit order" / "buy when price hits" → jupiter_limit_create → sign → jupiter_broadcast_tx
IF "my orders" / "open orders"           → jupiter_limit_orders(wallet)
IF "cancel order"                        → jupiter_limit_orders → jupiter_limit_cancel → sign → jupiter_broadcast_tx
IF token not in KNOWN_TOKENS             → ask user for mint address

Few-Shot 示例

JUP-01 —“SOL 的价格是多少？”

jupiter_price("SOL")
# -> {"price_usd": 84.2, ...}

JUP-01b —“0.5 SOL 可以兑换多少 USDC？”（仅报价，不交易）

jupiter_swap("SOL", "USDC", 0.5)   # wallet_pubkey omitted
# -> {quote_only: True, in_amount: "0.50", out_amount: "42.10",
#     in_usd: "42.1", transaction: None}
# Stop here — show user the rate, no signing needed.

JUP-02 —“将 0.01 SOL 兑换为 USDC”

quote  = jupiter_swap("SOL", "USDC", 0.01, wallet_pubkey)
# → show: 0.01 SOL → ~0.84 USDC, impact <0.01%
signed = wallet_sol_sign_transaction(quote["transaction"])
result = jupiter_execute_swap(
    signed["signed_transaction"],
    quote["request_id"],
    in_mint=quote["in_mint"],
    out_mint=quote["out_mint"],
)
# → {"status": "Success", "signature": "yUKn...", "in_amount_fmt": "0.01", "out_amount_fmt": "0.84"}
wallet_sol_balance()

JUP-03 —“设置限价：当 USDC 价格达到 $50/SOL 时卖出 0.06 SOL”

# makingAmount=0.06 SOL, takingAmount=3 USDC (= 0.06 * 50)
order  = jupiter_limit_create("SOL", "USDC", 0.06, 3.0, wallet_pubkey)
# → implied_price: "1 USDC = 0.0200 SOL" (i.e. $50/SOL)
signed = wallet_sol_sign_transaction(order["transaction"])  # do this immediately!
result = jupiter_broadcast_tx(signed["signed_transaction"])
# → {"success": True, "signature": "53bp..."}
jupiter_limit_orders(wallet_pubkey)  # or check history if filled instantly

JUP-04 —“我的未完成订单”

jupiter_limit_orders(wallet_pubkey)
# → {"count": 1, "orders": [{"order_pubkey": "...", "making_amount": "0.06", ...}]}

JUP-05 —“取消我的订单”

orders = jupiter_limit_orders(wallet_pubkey)
pubkey = orders["orders"][0]["order_pubkey"]
cancel = jupiter_limit_cancel(pubkey, wallet_pubkey)
signed = wallet_sol_sign_transaction(cancel["transaction"])
jupiter_broadcast_tx(signed["signed_transaction"])