jupiter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Jupiter — Solana DEX Aggregator

Jupiter — Solana DEX聚合器

Jupiter routes swaps across all Solana DEXes (Raydium, Orca, Phoenix…) for best price.

Jupiter会在所有Solana DEX（Raydium、Orca、Phoenix等）间路由兑换订单，以获取最优价格。

⛽ Gas & Cost — Read This First

⛽ Gas与成本 — 请先阅读

Gas is always paid from wallet SOL balance. No gas sponsorship on Solana.
```
wallet_sol_transfer
```
does NOT work for Jupiter — it's for send-SOL only.
Swaps cost ~0.0002–0.001 SOL in fees (priority fee + rent deposit for new token accounts).
Limit orders cost ~0.002 SOL to create (on-chain account rent).
Always call
```
wallet_sol_balance()
```
before operating to confirm SOL > 0.01.

Gas费用始终从钱包的SOL余额中扣除。Solana不提供Gas赞助服务。
```
wallet_sol_transfer
```
不适用于Jupiter — 该功能仅用于发送SOL。
兑换手续费约为0.0002–0.001 SOL（优先费用 + 新代币账户的租金押金）。
创建限价订单需花费约0.002 SOL（链上账户租金）。
操作前务必调用
```
wallet_sol_balance()
```
确认SOL余额 > 0.01。

⛔ HARD RULES

⛔ 硬性规则

ALWAYS use
ultra/v1/order
— NOT
```
swap/v1/quote
```
+
```
swap/v1/swap
```
(deprecated)
Pass wallet pubkey to
jupiter_swap
only when intending to execute — omitting it returns a quote-only result (no transaction), which is correct for price checks
NEVER pass numeric
makingAmount
/
takingAmount
— must be strings or API returns ZodError 400
NEVER use
/ultra/v1/execute
for limit orders — limit orders MUST go through
```
jupiter_broadcast_tx()
```
(Solana RPC)
NEVER omit user confirmation before executing a swap or limit order
ALWAYS call
wallet_sol_balance()
after swap to verify balances changed
NEVER mention DCA — lite-api does not support it

必须使用
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不支持该功能

Prerequisites — Wallet Policy

前置条件 — 钱包策略

Before any on-chain operation, load the wallet skill and propose the standard wildcard Solana policy (deny key export + allow

进行任何链上操作前，加载wallet技能并启用标准Solana通配符策略（禁止密钥导出 + 允许

权限）。

Key Token Addresses (Solana)

Solana核心代币地址

Token	Mint Address	Decimals
SOL	`So11111111111111111111111111111111111111112`	9
USDC	`EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`	6
USDT	`Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB`	6
JUP	`JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN`	6
BONK	`DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263`	5
WIF	`EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm`	6
JTO	`jtojtomepa8beP8AuQc6eXt5FriJwfFMwQx2v2f9mCL`	6 (NOT 9)

For unlisted tokens: ask user for mint address directly — token search API is deprecated.

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

对于未列出的代币：直接向用户索要铸币地址 — 代币搜索API已废弃。

Available Tools (from exports.py)

可用工具（来自exports.py）

Tool	What it does
`jupiter_price(token)`	USD price of any token
`jupiter_swap(in, out, amount, wallet?)`	Quote only (no wallet) or quote + tx (wallet provided)
`jupiter_execute_swap(signed_tx, request_id, in_mint?, out_mint?)`	Broadcast swap via `/ultra/v1/execute` ← swap only
`jupiter_broadcast_tx(signed_tx)`	Broadcast via Solana RPC ← limit orders + cancel
`jupiter_limit_create(in, out, making, taking, maker)`	Create limit order
`jupiter_limit_orders(wallet, history=False)`	List open or historical orders
`jupiter_limit_cancel(order_pubkey, maker)`	Cancel an open order

工具	功能说明
`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)`	取消未成交订单

Swap Workflow (End-to-End)

完整兑换流程

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

Key facts:

```
jupiter_execute_swap
```
→ POST
```
/ultra/v1/execute
```
— only for Ultra swaps
```
transaction
```
is
```
null
```
if wallet pubkey is missing/invalid — retry step 1 with a valid wallet
Swap is atomic: if it fails, nothing is deducted (except gas fee)

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

2. 向用户展示：出入金数量、USD价值、价格影响百分比 — 等待用户确认

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

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

5. wallet_sol_balance()  ← 验证余额变化

关键说明:

```
jupiter_execute_swap
```
→ 调用POST
```
/ultra/v1/execute
```
— 仅适用于Ultra兑换
如果钱包公钥缺失/无效，
```
transaction
```
会返回
```
null
```
— 重新执行步骤1并传入有效钱包
兑换是原子操作：若失败，除Gas费外无任何资金扣除

Limit Order Workflow (End-to-End)

完整限价订单流程

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

Key facts:

Min order size: ~$5 USD — smaller returns

{"error": "Order size must be at least 5 USD"}

Keepers may fill the order instantly if your implied price is favorable (≤ market)
```
orderKey
```
field in API response is the order pubkey (not
```
publicKey
```
)
```
makingAmount
```
/
```
takingAmount
```
in openOrders are already human-readable (e.g. "0.06"), not raw lamports
```
expiredAt
```
and
```
feeBps
```
must be omitted entirely if not used (don't pass null or 0)

1. order = jupiter_limit_create(
       input_token="SOL",    # 卖出代币
       output_token="USDC",  # 买入代币
       making_amount=0.06,   # 卖出0.06 SOL
       taking_amount=3.0,    # 至少获得3 USDC（设定目标价格）
       maker=wallet_pubkey
   )
   └─ 返回结果: order_pubkey, transaction, implied_price, next_step

2. 向用户展示：隐含价格、交易数量 — 等待用户确认

3. signed = wallet_sol_sign_transaction(order["transaction"])
   ⚠️  需在约90秒内完成签名并广播 — 区块哈希会过期。

4. result = jupiter_broadcast_tx(signed["signed_transaction"])
   └─ 返回结果: {"success": True, "signature": "..."} 或 {"success": False, "error": "..."}
   ⚠️  使用jupiter_broadcast_tx，而非jupiter_execute_swap — 两者调用不同的端点！

5. jupiter_limit_orders(wallet_pubkey)  ← 确认order_pubkey已存在
   注意：若隐含价格低于等于市场价，订单可能立即成交，请查看orderHistory

关键说明:

最小订单规模：约5美元 — 小于该金额会返回
```
{"error": "Order size must be at least 5 USD"}
```
若隐含价格具有优势（≤市场价），做市商可能立即成交订单
API响应中的
```
orderKey
```
字段是订单公钥（不是
```
publicKey
```
）
openOrders中的
```
makingAmount
```
/
```
takingAmount
```
已转换为人类可读格式（例如"0.06"），而非原始lamports
若不使用
```
expiredAt
```
和
```
feeBps
```
，需完全省略这两个字段（不要传入null或0）

Cancel Order Workflow

取消订单流程

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"])

1. orders = jupiter_limit_orders(wallet_pubkey)
2. 从orders["orders"][n]["order_pubkey"]中选择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"])

Tool Routing — IF/THEN

工具路由规则 — 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

如果用户询问"价格" / "X值多少钱"             → 调用jupiter_price(token)
如果用户询问"报价" / "我能换到多少"        → 调用jupiter_swap(in, out, amount)  [省略钱包=仅返回报价，无交易]
如果用户提及"兑换" / "交易" / "转换"       → 调用jupiter_swap(in, out, amount, wallet) → 确认用户意愿 → 签名 → 调用jupiter_execute_swap(in_mint, out_mint)
如果用户提及"限价订单" / "价格到了再买" → 调用jupiter_limit_create → 签名 → 调用jupiter_broadcast_tx
如果用户询问"我的订单" / "未成交订单"           → 调用jupiter_limit_orders(wallet)
如果用户提及"取消订单"                        → 调用jupiter_limit_orders → 调用jupiter_limit_cancel → 签名 → 调用jupiter_broadcast_tx
如果代币不在KNOWN_TOKENS列表中             → 向用户索要铸币地址

Few-Shot Examples

示例演示

JUP-01 — "SOL price?"

python

jupiter_price("SOL")

JUP-01 — "SOL价格是多少？"

python

jupiter_price("SOL")

-> {"price_usd": 84.2, ...}


**JUP-01b — "How much USDC would I get for 0.5 SOL?" (quote only, no trade)**
```python
jupiter_swap("SOL", "USDC", 0.5)   # wallet_pubkey omitted


**JUP-01b — "0.5 SOL能换多少USDC？"（仅报价，不交易）**
```python
jupiter_swap("SOL", "USDC", 0.5)   # 省略wallet_pubkey

-> {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 — "Swap 0.01 SOL to USDC"**
```python
quote  = jupiter_swap("SOL", "USDC", 0.01, wallet_pubkey)


**JUP-02 — "把0.01 SOL换成USDC"**
```python
quote  = jupiter_swap("SOL", "USDC", 0.01, wallet_pubkey)

→ show: 0.01 SOL → ~0.84 USDC, impact <0.01%

→ 展示：0.01 SOL → ~0.84 USDC，价格影响<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 — "Set limit: sell 0.06 SOL when USDC price hits $50/SOL"**
```python

wallet_sol_balance()


**JUP-03 — "设置限价：当USDC价格达到50美元/SOL时卖出0.06 SOL"**
```python

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)

→ implied_price: "1 USDC = 0.0200 SOL"（即50美元/SOL）

signed = wallet_sol_sign_transaction(order["transaction"]) # do this immediately! result = jupiter_broadcast_tx(signed["signed_transaction"])

signed = wallet_sol_sign_transaction(order["transaction"]) # 立即执行此步骤！ result = jupiter_broadcast_tx(signed["signed_transaction"])

→ {"success": True, "signature": "53bp..."}

jupiter_limit_orders(wallet_pubkey) # or check history if filled instantly


**JUP-04 — "My open orders"**
```python
jupiter_limit_orders(wallet_pubkey)

jupiter_limit_orders(wallet_pubkey) # 若订单立即成交则查看历史记录


**JUP-04 — "我的未成交订单"**
```python
jupiter_limit_orders(wallet_pubkey)

→ {"count": 1, "orders": [{"order_pubkey": "...", "making_amount": "0.06", ...}]}


**JUP-05 — "Cancel my order"**
```python
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"])


**JUP-05 — "取消我的订单"**
```python
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"])