Jupiter¶

Connector for Jupiter DEX aggregator on Solana.

almanak.framework.connectors.jupiter ¶

Jupiter DEX Aggregator Protocol Connector.

Jupiter is the primary DEX aggregator on Solana, routing across Raydium, Orca, Meteora, and other Solana AMMs.

This connector provides: - JupiterClient: HTTP client for the Jupiter API v6 - JupiterAdapter: Adapter for converting SwapIntents to Solana transactions - JupiterReceiptParser: Balance-delta parser for extracting swap results

Example

from almanak.framework.connectors.jupiter import JupiterClient, JupiterAdapter, JupiterConfig

config = JupiterConfig(wallet_address="your-solana-pubkey") client = JupiterClient(config)

Get a swap quote¶

quote = client.get_quote( input_mint="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", # USDC output_mint="So11111111111111111111111111111111111111112", # WSOL amount=1000000000, slippage_bps=50, )

JupiterAdapter ¶

JupiterAdapter(
    config: JupiterConfig,
    price_provider: dict[str, Decimal] | None = None,
    allow_placeholder_prices: bool = False,
    token_resolver: TokenResolver | None = None,
    rpc_url: str | None = None,
)

Adapter for Jupiter protocol integration with the Intent system.

Converts SwapIntents into ActionBundles containing serialized Solana VersionedTransactions from Jupiter's API.

Unlike EVM adapters: - No approval transactions needed - Transactions contain base64-encoded VersionedTransactions - Route freshness is managed via get_fresh_swap_transaction()

Example

config = JupiterConfig(wallet_address="your-solana-pubkey") adapter = JupiterAdapter(config)

intent = SwapIntent(from_token="USDC", to_token="SOL", amount=Decimal("100")) bundle = adapter.compile_swap_intent(intent)

Initialize the Jupiter adapter.

Parameters:

Name	Type	Description	Default
`config`	`JupiterConfig`	Jupiter client configuration	required
`price_provider`	`dict[str, Decimal] \| None`	Price oracle dict (token symbol -> USD price)	`None`
`allow_placeholder_prices`	`bool`	If True, allows running without prices (testing only)	`False`
`token_resolver`	`TokenResolver \| None`	Optional TokenResolver instance	`None`
`rpc_url`	`str \| None`	Solana RPC URL for balance queries (resolving amount='all'). Falls back to SOLANA_RPC_URL env var or public mainnet.	`None`

resolve_token_address ¶

resolve_token_address(token: str) -> str

Resolve token symbol or address to Solana mint address.

Parameters:

Name	Type	Description	Default
`token`	`str`	Token symbol (e.g., "USDC") or Solana mint address	required

Returns:

Type	Description
`str`	Solana mint address (Base58)

Raises:

Type	Description
`TokenResolutionError`	If the token cannot be resolved

get_token_decimals ¶

get_token_decimals(token: str) -> int

Get token decimals using TokenResolver.

Parameters:

Name	Type	Description	Default
`token`	`str`	Token symbol or Solana mint address	required

Returns:

Type	Description
`int`	Token decimals

Raises:

Type	Description
`TokenResolutionError`	If decimals cannot be determined

compile_swap_intent ¶

compile_swap_intent(
    intent: SwapIntent,
    price_oracle: dict[str, Decimal] | None = None,
) -> ActionBundle

Compile a SwapIntent to an ActionBundle using Jupiter.

Parameters:

Name	Type	Description	Default
`intent`	`SwapIntent`	The SwapIntent to compile	required
`price_oracle`	`dict[str, Decimal] \| None`	Optional price oracle for USD conversions	`None`

Returns:

Type	Description
`ActionBundle`	ActionBundle containing a serialized Solana transaction

get_fresh_swap_transaction ¶

get_fresh_swap_transaction(
    metadata: dict[str, Any],
) -> dict[str, Any]

Fetch fresh swap transaction data immediately before execution.

Jupiter routes expire quickly. This method fetches a fresh quote and transaction right before signing.

Parameters:

Name	Type	Description	Default
`metadata`	`dict[str, Any]`	The metadata from a compiled ActionBundle containing route_params	required

Returns:

Type	Description
`dict[str, Any]`	Fresh transaction data dict

Raises:

Type	Description
`ValueError`	If metadata doesn't contain route_params

JupiterClient ¶

JupiterClient(config: JupiterConfig)

Client for interacting with the Jupiter Swap API v1.

This client provides methods for: - Getting swap quotes across Solana DEXs - Building swap transactions (serialized VersionedTransactions)

An API key is required (free keys at https://portal.jup.ag).

Example

config = JupiterConfig( wallet_address="your-solana-wallet-pubkey", api_key="your-jupiter-api-key", ) client = JupiterClient(config)

quote = client.get_quote( input_mint="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", output_mint="So11111111111111111111111111111111111111112", amount=1000000000, slippage_bps=50, )

Initialize the Jupiter client.

Parameters:

Name	Type	Description	Default
`config`	`JupiterConfig`	Jupiter client configuration	required

wallet_address `property` ¶

wallet_address: str

Get the configured wallet address.

get_quote ¶

get_quote(
    input_mint: str,
    output_mint: str,
    amount: int,
    slippage_bps: int = 50,
    max_price_impact_pct: float | None = None,
) -> JupiterQuote

Get a swap quote from Jupiter.

Parameters:

Name	Type	Description	Default
`input_mint`	`str`	Input token mint address (Base58)	required
`output_mint`	`str`	Output token mint address (Base58)	required
`amount`	`int`	Input amount in smallest units (e.g., lamports for SOL)	required
`slippage_bps`	`int`	Slippage tolerance in basis points (default 50 = 0.5%)	`50`
`max_price_impact_pct`	`float \| None`	Maximum allowed price impact percentage	`None`

Returns:

Type	Description
`JupiterQuote`	JupiterQuote with route and expected output

Raises:

Type	Description
`JupiterAPIError`	If the API request fails
`JupiterPriceImpactError`	If price impact exceeds threshold

get_swap_transaction ¶

get_swap_transaction(
    quote: JupiterQuote,
    user_public_key: str | None = None,
    priority_fee_level: str | None = None,
    priority_fee_max_lamports: int | None = None,
) -> JupiterSwapTransaction

Get a serialized swap transaction from Jupiter.

The returned transaction is a base64-encoded VersionedTransaction ready for signing and submission.

Parameters:

Name	Type	Description	Default
`quote`	`JupiterQuote`	Quote from get_quote()	required
`user_public_key`	`str \| None`	Solana wallet public key (defaults to config wallet)	`None`
`priority_fee_level`	`str \| None`	Priority fee level ("low", "medium", "high", "veryHigh"). Defaults to "veryHigh".	`None`
`priority_fee_max_lamports`	`int \| None`	Maximum priority fee in lamports. Defaults to 1_000_000 (0.001 SOL).	`None`

Returns:

Type	Description
`JupiterSwapTransaction`	JupiterSwapTransaction with base64-encoded transaction

Raises:

Type	Description
`JupiterAPIError`	If the API request fails

JupiterConfig `dataclass` ¶

JupiterConfig(
    wallet_address: str,
    api_key: str | None = None,
    base_url: str = "",
    timeout: int = 30,
    max_accounts: int | None = None,
)

Configuration for Jupiter client.

Attributes:

Name	Type	Description
`wallet_address`	`str`	Solana wallet public key (Base58)
`api_key`	`str \| None`	Jupiter API key (from https://portal.jup.ag). Falls back to JUPITER_API_KEY env var.
`base_url`	`str`	Jupiter API base URL
`timeout`	`int`	Request timeout in seconds
`max_accounts`	`int \| None`	Max intermediate accounts for routing (None = no limit)

__post_init__ ¶

__post_init__() -> None

Validate configuration.

JupiterAPIError ¶

JupiterAPIError(
    message: str,
    status_code: int,
    endpoint: str | None = None,
    error_data: dict | None = None,
)

Bases: JupiterError

Exception raised for errors in the Jupiter API response.

Attributes:

Name	Type	Description
`message`		Error message
`status_code`		HTTP status code of the response
`endpoint`		The API endpoint that was called
`error_data`		Parsed error data from the response, if available

JupiterConfigError ¶

JupiterConfigError(
    message: str, parameter: str | None = None
)

Bases: JupiterError

Exception raised for configuration errors.

Attributes:

Name	Type	Description
`message`		Error message
`parameter`		Name of the configuration parameter that caused the error

JupiterError ¶

Bases: Exception

Base exception class for all Jupiter connector errors.

JupiterPriceImpactError ¶

JupiterPriceImpactError(
    message: str,
    price_impact_pct: float | None = None,
    threshold_pct: float | None = None,
)

Bases: JupiterError

Raised when swap price impact exceeds maximum threshold.

Attributes:

Name	Type	Description
`message`		Error message
`price_impact_pct`		Actual price impact as percentage
`threshold_pct`		Maximum allowed price impact as percentage

JupiterValidationError ¶

JupiterValidationError(
    message: str,
    field: str | None = None,
    value: Any | None = None,
)

Bases: JupiterError

Exception raised for validation errors.

Attributes:

Name	Type	Description
`message`		Error message
`field`		Name of the field that failed validation
`value`		The invalid value

JupiterQuote `dataclass` ¶

JupiterQuote(
    input_mint: str,
    output_mint: str,
    in_amount: str,
    out_amount: str,
    other_amount_threshold: str = "0",
    price_impact_pct: str = "0",
    route_plan: list[JupiterRoutePlan] = list(),
    slippage_bps: int = 50,
    raw_response: dict[str, Any] = dict(),
)

Quote response from Jupiter Swap API v1.

Attributes:

Name	Type	Description
`input_mint`	`str`	Input token mint address
`output_mint`	`str`	Output token mint address
`in_amount`	`str`	Input amount in smallest units
`out_amount`	`str`	Expected output amount in smallest units
`other_amount_threshold`	`str`	Minimum output amount (after slippage)
`price_impact_pct`	`str`	Price impact as a percentage string (e.g., "0.12")
`route_plan`	`list[JupiterRoutePlan]`	List of route steps
`slippage_bps`	`int`	Slippage tolerance in basis points
`raw_response`	`dict[str, Any]`	Full API response for debugging

from_api_response `classmethod` ¶

from_api_response(data: dict[str, Any]) -> JupiterQuote

Create JupiterQuote from API response.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	Jupiter /quote API response dict	required

Returns:

Type	Description
`JupiterQuote`	Parsed JupiterQuote

get_price_impact_float ¶

get_price_impact_float() -> float

Get price impact as a float.

Returns:

Type	Description
`float`	Price impact percentage (e.g., 0.12 for 0.12%)

get_out_amount_int ¶

get_out_amount_int() -> int

Get output amount as integer.

get_in_amount_int ¶

get_in_amount_int() -> int

Get input amount as integer.

JupiterRoutePlan `dataclass` ¶

JupiterRoutePlan(
    amm_key: str = "",
    label: str = "",
    input_mint: str = "",
    output_mint: str = "",
    in_amount: str = "0",
    out_amount: str = "0",
    fee_amount: str = "0",
    fee_mint: str = "",
    percent: float = 100.0,
)

A single step in a Jupiter swap route.

Attributes:

Name	Type	Description
`amm_key`	`str`	Address of the AMM pool used
`label`	`str`	Human-readable AMM name (e.g., "Raydium", "Orca")
`input_mint`	`str`	Input token mint address
`output_mint`	`str`	Output token mint address
`in_amount`	`str`	Input amount for this hop (in smallest units)
`out_amount`	`str`	Output amount for this hop (in smallest units)
`fee_amount`	`str`	Fee amount for this hop
`fee_mint`	`str`	Mint of the fee token
`percent`	`float`	Percentage of the total swap routed through this hop

from_api_response `classmethod` ¶

from_api_response(data: dict[str, Any]) -> JupiterRoutePlan

Create from Jupiter API route plan entry.

JupiterSwapTransaction `dataclass` ¶

JupiterSwapTransaction(
    swap_transaction: str,
    last_valid_block_height: int = 0,
    priority_fee_lamports: int = 0,
    quote: JupiterQuote | None = None,
)

Swap transaction response from Jupiter Swap API v1.

The Jupiter /swap endpoint returns a serialized VersionedTransaction in base64 format, ready for signing and submission.

Attributes:

Name	Type	Description
`swap_transaction`	`str`	Base64-encoded serialized VersionedTransaction
`last_valid_block_height`	`int`	Last blockhash validity slot
`priority_fee_lamports`	`int`	Priority fee included in the transaction
`quote`	`JupiterQuote \| None`	The quote used to generate this transaction

from_api_response `classmethod` ¶

from_api_response(
    data: dict[str, Any], quote: JupiterQuote | None = None
) -> JupiterSwapTransaction

Create JupiterSwapTransaction from API response.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	Jupiter /swap API response dict	required
`quote`	`JupiterQuote \| None`	The quote that produced this transaction	`None`

Returns:

Type	Description
`JupiterSwapTransaction`	Parsed JupiterSwapTransaction

JupiterReceiptParser ¶

JupiterReceiptParser(**kwargs: Any)

Parser for Jupiter swap transaction receipts on Solana.

Uses balance-delta extraction from pre/post token balances rather than event log parsing (as on EVM chains).

Example

parser = JupiterReceiptParser(wallet_address="your-wallet-pubkey") receipt = { "signature": "...", "success": True, "pre_token_balances": [...], "post_token_balances": [...], } amounts = parser.extract_swap_amounts(receipt) if amounts: print(f"Swapped {amounts.amount_in_decimal} -> {amounts.amount_out_decimal}")

Initialize JupiterReceiptParser.

Parameters:

Name	Type	Description	Default
`**kwargs`	`Any`	Keyword arguments passed by the receipt_registry. wallet_address: Wallet public key for balance filtering. chain: Chain name (always "solana" for Jupiter).	`{}`

extract_swap_amounts ¶

extract_swap_amounts(
    receipt: dict[str, Any],
) -> SwapAmounts | None

Extract swap amounts from a Jupiter transaction receipt.

Uses balance-delta approach: 1. Index pre_token_balances by (owner, mint) -> amount 2. Index post_token_balances by (owner, mint) -> amount 3. For wallet owner: find mint where balance decreased (token_in) and increased (token_out)

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Solana transaction receipt dict with: - pre_token_balances: list of token balance entries - post_token_balances: list of token balance entries - success: bool indicating transaction success - fee_payer or wallet_address: the wallet to track	required

Returns:

Type	Description
`SwapAmounts \| None`	SwapAmounts if swap transfers found, None otherwise

parse_receipt ¶

parse_receipt(receipt: dict[str, Any]) -> dict[str, Any]

Parse a receipt for ReceiptParser protocol compatibility.

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict	required

Returns:

Type	Description
`dict[str, Any]`	Dict with parsed data

Jupiter¶

almanak.framework.connectors.jupiter ¶

Get a swap quote¶

JupiterAdapter ¶

resolve_token_address ¶

get_token_decimals ¶

compile_swap_intent ¶

get_fresh_swap_transaction ¶

JupiterClient ¶

wallet_address property ¶

get_quote ¶

get_swap_transaction ¶

JupiterConfig dataclass ¶

__post_init__ ¶

JupiterAPIError ¶

JupiterConfigError ¶

JupiterError ¶

JupiterPriceImpactError ¶

JupiterValidationError ¶

JupiterQuote dataclass ¶

from_api_response classmethod ¶

get_price_impact_float ¶

get_out_amount_int ¶

get_in_amount_int ¶

JupiterRoutePlan dataclass ¶

from_api_response classmethod ¶

JupiterSwapTransaction dataclass ¶

from_api_response classmethod ¶

JupiterReceiptParser ¶

extract_swap_amounts ¶

parse_receipt ¶

wallet_address `property` ¶

JupiterConfig `dataclass` ¶

JupiterQuote `dataclass` ¶

from_api_response `classmethod` ¶

JupiterRoutePlan `dataclass` ¶

from_api_response `classmethod` ¶

JupiterSwapTransaction `dataclass` ¶

from_api_response `classmethod` ¶