starchild-ai-agent/@554/jupiter

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