Jupiter — Solana DEX Aggregator

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

⛽ Gas & Cost — Read This First

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.

⛔ 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

Prerequisites — Wallet Policy

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

Key Token Addresses (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.

Available Tools (from 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

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)

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)

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

Tool Routing — 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 Examples

JUP-01 — "SOL price?"

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

JUP-01b — "How much USDC would I get for 0.5 SOL?" (quote only, no trade)

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 — "Swap 0.01 SOL to 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 — "Set limit: sell 0.06 SOL when USDC price hits $50/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 — "My open orders"

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

JUP-05 — "Cancel my order"

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

@554/jupiter