Jupiter Swap (Buy/Sell) Tool

Jupiter Swap Tool (jupiter_swap_tool)

Executes an on-chain token swap on the Solana network using the Jupiter aggregator. This tool allows for trading one SPL token (or SOL) for another. This involves real fund movements and market risks like slippage.

Inputs: Requires wallet details, input/output tokens, amount, and optional slippage

class JupiterSwapInput(BaseModel):
    agent_public: str      # Swapper's public key
    agent_private: str     # Swapper's ENCRYPTED private key
    input_mint: str      # Mint address of token to sell (e.g., SOL or USDC mint)
    output_mint: str     # Mint address of token to buy
    amount: float          # Amount of input token to swap
    slippage: float = 10.0 # Slippage tolerance % (e.g., 0.5 for 0.5%)

Key Functionality:

  • Securely decrypts the swapper's private key.

  • Fetches optimal swap routes and quotes from the Jupiter API.

  • Validates balances and constructs a transaction based on the quote and specified slippage.

  • Signs and sends the transaction to the Solana network to perform the swap.

  • Handles SOL as a native asset (using its mint address So1111...1112).


Sample Usage Queries (How an AI might use it): (These imply the agent has access to or will securely prompt for necessary wallet details, and can use a token identification tool to get mint addresses if names like "USDC" or "LUMO" are given.)

  • "Swap 1 SOL for USDC using Jupiter with 0.5% slippage."

  • "Trade 100 USDC for BONK, max 1% slippage."

  • "I want to convert my AmountX of InputTokenName/Mint to OutputTokenName/Mint using Jupiter."

  • "Sell 50 LUMO, allow up to 2% slippage."

  • "Help me swap some GOAT tokens for SOL on Jupiter." (Agent would then gather all parameters)

  • "Swap N units of MintAddr1 for MintAddr2 with default slippage on Jupiter."


Quick Code Glance:

class JupiterSwapTool(BaseTool):
    name: ClassVar[str] = "jupiter_swap_tool"
    description: ClassVar[str] = "Swap tokens on Solana using Jupiter. Provide the input token, output token, amount, and slippage..."
    args_schema: ClassVar[Type[BaseModel]] = JupiterSwapInput

⚠️ CRITICAL INFORMATION / WARNINGS:

  • Real Transactions & Market Risk: This tool executes actual token swaps. Prices can change rapidly (slippage), and the final received amount may differ from the quote. Transactions are irreversible.

  • Encrypted Private Key: Requires the agent's encrypted private key. Secure handling is paramount.

  • Correct Mint Addresses: Ensure accurate SPL token mint addresses for input_mint and output_mint. Using "SOL" for mints will be auto-corrected to the native SOL address.

  • Slippage Setting: Understand and set the slippage tolerance carefully to protect against unfavorable price changes during execution. The default in this tool is 10%, which is very high and should likely be adjusted for most swaps.

  • Network & API Dependent: Relies on Solana RPC and the Jupiter API.

  • Asynchronous: Primarily designed for asynchronous execution (_arun).

Last updated