TraderJoe V2¶

Connector for TraderJoe V2 Liquidity Book DEX.

almanak.framework.connectors.traderjoe_v2 ¶

TraderJoe Liquidity Book V2 Connector.

This module provides the TraderJoe V2 adapter for executing swaps and managing liquidity positions on TraderJoe V2's Liquidity Book on Avalanche.

TraderJoe V2 Architecture: - LBRouter: Main entry point for swaps and liquidity operations - LBFactory: Creates and manages LBPair pools - LBPair: Liquidity pool with discrete bins (not continuous ticks)

Key Concepts: - Bin: Discrete price point (unlike Uniswap V3's continuous ticks) - BinStep: Fee tier in basis points between bins (e.g., 20 = 0.2%) - Fungible LP Tokens: ERC1155-like tokens for each bin (no NFTs)

Supported chains: - Avalanche (Chain ID: 43114)

Example

from almanak.framework.connectors.traderjoe_v2 import TraderJoeV2Adapter, TraderJoeV2Config

config = TraderJoeV2Config( chain="avalanche", wallet_address="0x...", rpc_url="https://api.avax.network/ext/bc/C/rpc", ) adapter = TraderJoeV2Adapter(config)

Get a swap quote¶

quote = adapter.get_swap_quote( token_in="WAVAX", token_out="USDC", amount_in=Decimal("1.0"), bin_step=20, )

Use SDK for lower-level operations¶

from almanak.framework.connectors.traderjoe_v2 import TraderJoeV2SDK

sdk = TraderJoeV2SDK(chain="avalanche", rpc_url="https://api.avax.network/ext/bc/C/rpc") pool = sdk.get_pool_address(wavax_addr, usdc_addr, bin_step=20)

LiquidityPosition `dataclass` ¶

LiquidityPosition(
    pool_address: str,
    token_x: str,
    token_y: str,
    bin_step: int,
    bin_ids: list[int],
    balances: dict[int, int],
    amount_x: int,
    amount_y: int,
    active_bin: int,
)

Represents a liquidity position in TraderJoe V2.

Attributes:

Name	Type	Description
`pool_address`	`str`	Address of the LBPair pool
`token_x`	`str`	Address of token X
`token_y`	`str`	Address of token Y
`bin_step`	`int`	Bin step of the pool
`bin_ids`	`list[int]`	List of bin IDs where position has liquidity
`balances`	`dict[int, int]`	Dict mapping bin ID to LB token balance
`amount_x`	`int`	Total amount of token X in position
`amount_y`	`int`	Total amount of token Y in position
`active_bin`	`int`	Current active bin ID of the pool

SwapQuote `dataclass` ¶

SwapQuote(
    token_in: str,
    token_out: str,
    amount_in: Decimal,
    amount_out: Decimal,
    bin_step: int,
    price: Decimal,
    price_impact: Decimal,
    path: list[str],
    gas_estimate: int = DEFAULT_GAS_ESTIMATES["swap"],
)

Quote for a swap operation.

Attributes:

Name	Type	Description
`token_in`	`str`	Input token symbol or address
`token_out`	`str`	Output token symbol or address
`amount_in`	`Decimal`	Amount of input token (in token units)
`amount_out`	`Decimal`	Expected amount of output token (in token units)
`bin_step`	`int`	Bin step used for the swap
`price`	`Decimal`	Execution price (amount_out / amount_in)
`price_impact`	`Decimal`	Estimated price impact as percentage
`path`	`list[str]`	Token path for the swap
`gas_estimate`	`int`	Estimated gas for the transaction

SwapResult `dataclass` ¶

SwapResult(
    success: bool,
    tx_hash: str | None = None,
    token_in: str | None = None,
    token_out: str | None = None,
    amount_in: Decimal | None = None,
    amount_out: Decimal | None = None,
    gas_used: int | None = None,
    block_number: int | None = None,
    timestamp: datetime | None = None,
    error: str | None = None,
)

Result of an executed swap.

Attributes:

Name	Type	Description
`success`	`bool`	Whether the swap succeeded
`tx_hash`	`str \| None`	Transaction hash
`token_in`	`str \| None`	Input token
`token_out`	`str \| None`	Output token
`amount_in`	`Decimal \| None`	Amount of input token used
`amount_out`	`Decimal \| None`	Amount of output token received
`gas_used`	`int \| None`	Actual gas used
`block_number`	`int \| None`	Block number of the transaction
`timestamp`	`datetime \| None`	Timestamp of the transaction
`error`	`str \| None`	Error message if failed

SwapType ¶

Bases: str, Enum

Type of swap to execute.

TraderJoeV2Adapter ¶

TraderJoeV2Adapter(
    config: TraderJoeV2Config,
    token_resolver: TokenResolver | None = None,
)

Adapter for TraderJoe Liquidity Book V2 protocol.

Provides high-level methods for: - Token swaps (exact input) - Liquidity management (add/remove) - Position queries - Quote generation

The adapter handles token resolution, slippage calculations, and transaction building internally.

Example

config = TraderJoeV2Config( chain="avalanche", wallet_address="0x...", rpc_url="https://api.avax.network/ext/bc/C/rpc", ) adapter = TraderJoeV2Adapter(config)

Get quote¶

quote = adapter.get_swap_quote("WAVAX", "USDC", Decimal("1.0"), bin_step=20)

Execute swap¶

result = adapter.swap_exact_input("WAVAX", "USDC", Decimal("1.0"), bin_step=20)

Initialize the adapter.

Parameters:

Name	Type	Description	Default
`config`	`TraderJoeV2Config`	Adapter configuration	required
`token_resolver`	`TokenResolver \| None`	Optional TokenResolver instance. If None, uses singleton.	`None`

Raises:

Type	Description
`TraderJoeV2SDKError`	If chain is not supported or connection fails

resolve_token_address ¶

resolve_token_address(token: str) -> str

Resolve a token symbol or address to a checksummed address using TokenResolver.

Parameters:

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

Returns:

Type	Description
`str`	Checksummed token address

Raises:

Type	Description
`TokenResolutionError`	If token cannot be resolved

get_token_decimals ¶

get_token_decimals(token: str) -> int

Get decimals for a token using TokenResolver.

Parameters:

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

Returns:

Type	Description
`int`	Token decimals

Raises:

Type	Description
`TokenResolutionError`	If decimals cannot be determined

to_wei ¶

to_wei(amount: Decimal, token: str) -> int

Convert token amount to wei (smallest unit).

Parameters:

Name	Type	Description	Default
`amount`	`Decimal`	Amount in token units	required
`token`	`str`	Token symbol or address	required

Returns:

Type	Description
`int`	Amount in wei

from_wei ¶

from_wei(amount: int, token: str) -> Decimal

Convert wei to token amount.

Parameters:

Name	Type	Description	Default
`amount`	`int`	Amount in wei	required
`token`	`str`	Token symbol or address	required

Returns:

Type	Description
`Decimal`	Amount in token units

get_swap_quote ¶

get_swap_quote(
    token_in: str,
    token_out: str,
    amount_in: Decimal,
    bin_step: int = 20,
) -> SwapQuote

Get a quote for a swap.

Parameters:

Name	Type	Description	Default
`token_in`	`str`	Input token symbol or address	required
`token_out`	`str`	Output token symbol or address	required
`amount_in`	`Decimal`	Amount of input token	required
`bin_step`	`int`	Bin step for the pair (default 20 = 0.2%)	`20`

Returns:

Type	Description
`SwapQuote`	SwapQuote with expected output and price info

Raises:

Type	Description
`PoolNotFoundError`	If pool doesn't exist

build_swap_transaction ¶

build_swap_transaction(
    token_in: str,
    token_out: str,
    amount_in: Decimal,
    bin_step: int = 20,
    slippage_bps: int | None = None,
    recipient: str | None = None,
) -> TransactionData

Build a swap transaction without executing it.

Parameters:

Name	Type	Description	Default
`token_in`	`str`	Input token symbol or address	required
`token_out`	`str`	Output token symbol or address	required
`amount_in`	`Decimal`	Amount of input token	required
`bin_step`	`int`	Bin step for the pair	`20`
`slippage_bps`	`int \| None`	Slippage tolerance in basis points	`None`
`recipient`	`str \| None`	Recipient address (default: wallet_address)	`None`

Returns:

Type	Description
`TransactionData`	TransactionData ready for signing and execution

swap_exact_input ¶

swap_exact_input(
    token_in: str,
    token_out: str,
    amount_in: Decimal,
    bin_step: int = 20,
    slippage_bps: int | None = None,
) -> SwapResult

Execute a swap with exact input amount.

Note: This method requires a private key to be configured. For building unsigned transactions, use build_swap_transaction().

Parameters:

Name	Type	Description	Default
`token_in`	`str`	Input token symbol or address	required
`token_out`	`str`	Output token symbol or address	required
`amount_in`	`Decimal`	Exact amount of input token	required
`bin_step`	`int`	Bin step for the pair	`20`
`slippage_bps`	`int \| None`	Slippage tolerance in basis points	`None`

Returns:

Type	Description
`SwapResult`	SwapResult with execution details

Raises:

Type	Description
`TraderJoeV2SDKError`	If execution fails

get_position ¶

get_position(
    token_x: str,
    token_y: str,
    bin_step: int = 20,
    wallet: str | None = None,
) -> LiquidityPosition | None

Get liquidity position for a wallet in a pool.

Parameters:

Name	Type	Description	Default
`token_x`	`str`	Token X symbol or address	required
`token_y`	`str`	Token Y symbol or address	required
`bin_step`	`int`	Bin step of the pool	`20`
`wallet`	`str \| None`	Wallet address (default: configured wallet)	`None`

Returns:

Type	Description
`LiquidityPosition \| None`	LiquidityPosition if found, None if no position

build_add_liquidity_transaction ¶

build_add_liquidity_transaction(
    token_x: str,
    token_y: str,
    amount_x: Decimal,
    amount_y: Decimal,
    bin_step: int = 20,
    bin_range: int = 10,
    slippage_bps: int | None = None,
) -> TransactionData

Build an add liquidity transaction.

Creates a uniform distribution across bins around the active bin.

Parameters:

Name	Type	Description	Default
`token_x`	`str`	Token X symbol or address	required
`token_y`	`str`	Token Y symbol or address	required
`amount_x`	`Decimal`	Amount of token X to add	required
`amount_y`	`Decimal`	Amount of token Y to add	required
`bin_step`	`int`	Bin step of the pool	`20`
`bin_range`	`int`	Number of bins on each side of active bin	`10`
`slippage_bps`	`int \| None`	Slippage tolerance in basis points	`None`

Returns:

Type	Description
`TransactionData`	TransactionData ready for signing and execution

build_remove_liquidity_transaction ¶

build_remove_liquidity_transaction(
    token_x: str,
    token_y: str,
    bin_step: int = 20,
    slippage_bps: int | None = None,
) -> TransactionData | None

Build a remove liquidity transaction for all positions.

Parameters:

Name	Type	Description	Default
`token_x`	`str`	Token X symbol or address	required
`token_y`	`str`	Token Y symbol or address	required
`bin_step`	`int`	Bin step of the pool	`20`
`slippage_bps`	`int \| None`	Slippage tolerance in basis points	`None`

Returns:

Type	Description
`TransactionData \| None`	TransactionData if position exists, None otherwise

TraderJoeV2Config `dataclass` ¶

TraderJoeV2Config(
    chain: str,
    wallet_address: str,
    rpc_url: str,
    private_key: str | None = None,
    default_slippage_bps: int = 50,
    default_deadline_seconds: int = 300,
)

Configuration for TraderJoe V2 adapter.

Parameters:

Name	Type	Description	Default
`chain`	`str`	Chain name (must be "avalanche")	required
`wallet_address`	`str`	Address of the wallet executing transactions	required
`rpc_url`	`str`	RPC endpoint URL	required
`private_key`	`str \| None`	Private key for signing (optional, for non-simulation)	`None`
`default_slippage_bps`	`int`	Default slippage in basis points (default: 50 = 0.5%)	`50`
`default_deadline_seconds`	`int`	Default transaction deadline (default: 300 = 5 min)	`300`

TransactionData `dataclass` ¶

TransactionData(
    to: str,
    data: str,
    value: int,
    gas: int,
    chain_id: int = 43114,
)

Transaction data ready for execution.

Attributes:

Name	Type	Description
`to`	`str`	Target contract address
`data`	`str`	Encoded calldata
`value`	`int`	ETH/AVAX value to send
`gas`	`int`	Gas limit
`chain_id`	`int`	Chain ID

LiquidityEventData `dataclass` ¶

LiquidityEventData(
    pool_address: str,
    sender: str,
    to: str,
    bin_ids: list[int],
    amounts_x: list[int] = list(),
    amounts_y: list[int] = list(),
    total_amount_x: int = 0,
    total_amount_y: int = 0,
)

Parsed data from add/remove liquidity events.

ParsedLiquidityResult `dataclass` ¶

ParsedLiquidityResult(
    success: bool,
    is_add: bool = True,
    pool_address: str | None = None,
    bin_ids: list[int] = list(),
    amount_x: int = 0,
    amount_y: int = 0,
    gas_used: int | None = None,
    block_number: int | None = None,
)

Result of parsing a liquidity transaction.

ParsedSwapResult `dataclass` ¶

ParsedSwapResult(
    success: bool,
    token_in: str | None = None,
    token_out: str | None = None,
    amount_in: int | None = None,
    amount_out: int | None = None,
    price: Decimal | None = None,
    gas_used: int | None = None,
    block_number: int | None = None,
    timestamp: datetime | None = None,
)

Result of parsing a swap transaction.

ParseResult `dataclass` ¶

ParseResult(
    success: bool,
    transaction_hash: str,
    block_number: int,
    gas_used: int,
    events: list[TraderJoeV2Event] = list(),
    swap_result: ParsedSwapResult | None = None,
    liquidity_result: ParsedLiquidityResult | None = None,
    error: str | None = None,
)

Result of parsing a transaction receipt.

SwapEventData `dataclass` ¶

SwapEventData(
    token_in: str,
    token_out: str,
    amount_in: int,
    amount_out: int,
    sender: str,
    recipient: str,
)

Parsed data from a swap (Transfer events).

TraderJoeV2Event `dataclass` ¶

TraderJoeV2Event(
    event_type: TraderJoeV2EventType,
    event_name: str,
    log_index: int,
    transaction_hash: str,
    block_number: int,
    contract_address: str,
    data: dict[str, Any],
    raw_topics: list[str] = list(),
    raw_data: str = "",
    timestamp: datetime | None = None,
)

Parsed TraderJoe V2 event.

TraderJoeV2EventType ¶

Bases: Enum

TraderJoe V2 event types.

TraderJoeV2ReceiptParser ¶

TraderJoeV2ReceiptParser(**kwargs: Any)

Parser for TraderJoe V2 transaction receipts.

Refactored to use base infrastructure utilities for hex decoding and event registry management. Now properly parses dynamic arrays in DepositedToBins and WithdrawnFromBins events.

Initialize the parser.

Parameters:

Name	Type	Description	Default
`**kwargs`	`Any`	Additional arguments (ignored for compatibility)	`{}`

parse_receipt ¶

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

Parse a transaction receipt.

Parameters:

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

Returns:

Type	Description
`ParseResult`	ParseResult with extracted data

parse_swap_events ¶

parse_swap_events(
    receipt: dict[str, Any],
) -> list[SwapEventData]

Parse swap events from a receipt.

Convenient method to extract all swap-related data.

Parameters:

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

Returns:

Type	Description
`list[SwapEventData]`	List of SwapEventData objects

extract_swap_amounts ¶

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

Extract swap amounts from a transaction receipt.

Note: Decimal conversions assume 18 decimals. TraderJoe pools often include tokens with different decimals (e.g., USDC with 6, WBTC with 8). The raw amount_in/amount_out fields are always accurate; use those with your own decimal scaling for precise calculations.

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	required

Returns:

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

extract_bin_ids ¶

extract_bin_ids(
    receipt: dict[str, Any],
) -> list[int] | None

Extract bin IDs from LP transaction receipt.

TraderJoe V2 uses bins for liquidity. This extracts the bin IDs from DepositedToBins or WithdrawnFromBins events.

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	required

Returns:

Type	Description
`list[int] \| None`	List of bin IDs if found, None otherwise

extract_liquidity ¶

extract_liquidity(receipt: dict[str, Any]) -> int | None

Extract total liquidity from LP transaction receipt.

Note: TraderJoe V2 uses ERC-1155 tokens for LP positions (not ERC-20). Liquidity amounts are encoded in DepositedToBins/WithdrawnFromBins events as bytes32 arrays requiring complex decoding. This method returns None as the exact liquidity amount extraction is not yet implemented.

For LP operation detection, use parse_receipt().liquidity_result instead.

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	required

Returns:

Type	Description
`int \| None`	None (liquidity amount extraction not implemented for TraderJoe V2)

extract_lp_close_data ¶

extract_lp_close_data(
    receipt: dict[str, Any],
) -> LPCloseData | None

Extract LP close data from transaction receipt.

Looks for WithdrawnFromBins events and Transfer events.

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	required

Returns:

Type	Description
`LPCloseData \| None`	LPCloseData dataclass if withdrawal found, None otherwise

TransferEventData `dataclass` ¶

TransferEventData(
    token: str,
    from_address: str,
    to_address: str,
    amount: int,
)

Parsed data from Transfer event.

InvalidBinStepError ¶

InvalidBinStepError(bin_step: int)

Bases: TraderJoeV2SDKError

Invalid bin step provided.

PoolInfo `dataclass` ¶

PoolInfo(
    address: str,
    token_x: str,
    token_y: str,
    bin_step: int,
    active_id: int,
    reserve_x: int,
    reserve_y: int,
)

Information about a TraderJoe V2 LBPair pool.

PoolNotFoundError ¶

PoolNotFoundError(
    token_x: str, token_y: str, bin_step: int
)

Bases: TraderJoeV2SDKError

Pool does not exist.

TraderJoeV2SDK ¶

TraderJoeV2SDK(
    chain: str,
    rpc_url: str,
    wallet_address: str | None = None,
)

TraderJoe Liquidity Book V2 SDK.

Provides methods for: - Token swaps (exact input) - Add/remove liquidity - Pool queries - Bin math utilities

Parameters:

Name	Type	Description	Default
`chain`	`str`	Chain name (e.g., "avalanche")	required
`rpc_url`	`str`	RPC endpoint URL	required
`wallet_address`	`str \| None`	Optional wallet address for transactions	`None`

Example

sdk = TraderJoeV2SDK( chain="avalanche", rpc_url="https://api.avax.network/ext/bc/C/rpc", )

Get pool info¶

pool = sdk.get_pool_address(wavax, usdc, bin_step=20)

Build swap transaction¶

tx, gas = sdk.build_swap_exact_tokens_for_tokens( amount_in=10**18, amount_out_min=0, path=[wavax, usdc], bin_steps=[20], recipient="0x...", )

get_token_contract ¶

get_token_contract(token_address: str) -> Contract

Get or create a token contract instance.

get_balance ¶

get_balance(token_address: str, account: str) -> int

Get the token balance of an account.

get_allowance ¶

get_allowance(
    token_address: str, owner: str, spender: str
) -> int

Get the allowance of a spender for a token owner.

get_pool_address ¶

get_pool_address(
    token_x: str, token_y: str, bin_step: int
) -> str

Get the LBPair (pool) address for a given token pair and binStep.

Parameters:

Name	Type	Description	Default
`token_x`	`str`	Address of token X	required
`token_y`	`str`	Address of token Y	required
`bin_step`	`int`	Bin step of the pair (e.g., 20 for 0.2%)	required

Returns:

Type	Description
`str`	Address of the LBPair contract

Raises:

Type	Description
`PoolNotFoundError`	If no pool exists for the pair/binStep

get_pair_contract ¶

get_pair_contract(pool_address: str) -> Contract

Get or create a pair contract instance.

get_pool_info ¶

get_pool_info(pool_address: str) -> PoolInfo

Get information about a pool.

get_pool_spot_rate ¶

get_pool_spot_rate(pool_address: str) -> float

Get the current spot price from a TraderJoe V2 LBPair pool.

Price is calculated from the active bin ID using the formula: price = (1 + binStep/10000)^(activeId - 8388608) * 10^(decimalsX - decimalsY)

Parameters:

Name	Type	Description	Default
`pool_address`	`str`	Address of the LBPair contract	required

Returns:

Type	Description
`float`	Current spot price (tokenY per tokenX)

bin_id_to_price `staticmethod` ¶

bin_id_to_price(
    bin_id: int,
    bin_step: int,
    decimals_x: int = 18,
    decimals_y: int = 18,
) -> float

Convert a bin ID to price using TraderJoe V2 formula.

Formula: price = (1 + binStep/10000)^(binId - 8388608) * 10^(decimalsX - decimalsY)

Parameters:

Name	Type	Description	Default
`bin_id`	`int`	The bin ID	required
`bin_step`	`int`	The bin step for the pair	required
`decimals_x`	`int`	Decimals of tokenX (default 18)	`18`
`decimals_y`	`int`	Decimals of tokenY (default 18)	`18`

Returns:

Type	Description
`float`	Price (tokenY per tokenX), adjusted for decimals

price_to_bin_id `staticmethod` ¶

price_to_bin_id(
    price: float,
    bin_step: int,
    decimals_x: int = 18,
    decimals_y: int = 18,
) -> int

Convert a price to the nearest bin ID using TraderJoe V2 formula.

Inverse formula: binId = (log(price) - (decimalsX - decimalsY) * log(10)) / log(1 + binStep/10000) + 8388608

Parameters:

Name	Type	Description	Default
`price`	`float`	Target price (tokenY per tokenX)	required
`bin_step`	`int`	The bin step for the pair	required
`decimals_x`	`int`	Decimals of tokenX (default 18)	`18`
`decimals_y`	`int`	Decimals of tokenY (default 18)	`18`

Returns:

Type	Description
`int`	Nearest bin ID

build_approve_transaction ¶

build_approve_transaction(
    token_address: str,
    spender_address: str,
    amount: int,
    from_address: str,
) -> tuple[dict[str, Any], int]

Build an approve transaction for a token.

Parameters:

Name	Type	Description	Default
`token_address`	`str`	Address of the token to approve	required
`spender_address`	`str`	Address of the spender (usually router)	required
`amount`	`int`	Amount to approve (in wei)	required
`from_address`	`str`	Address of the token owner	required

Returns:

Type	Description
`tuple[dict[str, Any], int]`	Tuple of (transaction dict, estimated gas)

build_approve_for_all_transaction ¶

build_approve_for_all_transaction(
    pool_address: str,
    spender_address: str,
    from_address: str,
    approved: bool = True,
) -> tuple[dict[str, Any], int]

Build approveForAll transaction for LB token (ERC1155-like).

LB tokens require approveForAll before the router can remove liquidity.

Parameters:

Name	Type	Description	Default
`pool_address`	`str`	Address of the LBPair contract	required
`spender_address`	`str`	Address of the spender (usually router)	required
`from_address`	`str`	Address of the token owner	required
`approved`	`bool`	Whether to approve or revoke	`True`

Returns:

Type	Description
`tuple[dict[str, Any], int]`	Tuple of (transaction dict, estimated gas)

build_swap_exact_tokens_for_tokens ¶

build_swap_exact_tokens_for_tokens(
    amount_in: int,
    amount_out_min: int,
    path: list[str],
    bin_steps: list[int],
    recipient: str,
    deadline: int | None = None,
) -> tuple[dict[str, Any], int]

Build transaction for swapping exact tokens for tokens.

Parameters:

Name	Type	Description	Default
`amount_in`	`int`	Amount of input token (in wei)	required
`amount_out_min`	`int`	Minimum amount of output token (in wei)	required
`path`	`list[str]`	List of token addresses [tokenIn, tokenOut] or multi-hop	required
`bin_steps`	`list[int]`	List of binSteps for each pair in the path	required
`recipient`	`str`	Address to receive output tokens	required
`deadline`	`int \| None`	Transaction deadline (default: current time + 100 days)	`None`

Returns:

Type	Description
`tuple[dict[str, Any], int]`	Tuple of (transaction dict, estimated gas)

build_add_liquidity ¶

build_add_liquidity(
    token_x: str,
    token_y: str,
    bin_step: int,
    amount_x: int,
    amount_y: int,
    amount_x_min: int,
    amount_y_min: int,
    active_id_desired: int,
    id_slippage: int,
    delta_ids: list[int],
    distribution_x: list[int],
    distribution_y: list[int],
    to: str,
    refund_to: str,
    deadline: int | None = None,
) -> tuple[dict[str, Any], int]

Build transaction for adding liquidity to a TraderJoe V2 pair.

Parameters:

Name	Type	Description	Default
`token_x`	`str`	Address of token X	required
`token_y`	`str`	Address of token Y	required
`bin_step`	`int`	Bin step of the pair	required
`amount_x`	`int`	Amount of token X to add	required
`amount_y`	`int`	Amount of token Y to add	required
`amount_x_min`	`int`	Minimum amount of token X (slippage protection)	required
`amount_y_min`	`int`	Minimum amount of token Y (slippage protection)	required
`active_id_desired`	`int`	Desired active bin ID	required
`id_slippage`	`int`	Allowed slippage on active bin ID	required
`delta_ids`	`list[int]`	Delta IDs for liquidity distribution (relative to active)	required
`distribution_x`	`list[int]`	Distribution of token X across bins (sum to 10^18)	required
`distribution_y`	`list[int]`	Distribution of token Y across bins (sum to 10^18)	required
`to`	`str`	Address to mint LB tokens to	required
`refund_to`	`str`	Address to refund excess tokens to	required
`deadline`	`int \| None`	Transaction deadline	`None`

Returns:

Type	Description
`tuple[dict[str, Any], int]`	Tuple of (transaction dict, estimated gas)

build_remove_liquidity ¶

build_remove_liquidity(
    token_x: str,
    token_y: str,
    bin_step: int,
    amount_x_min: int,
    amount_y_min: int,
    ids: list[int],
    amounts: list[int],
    to: str,
    deadline: int | None = None,
) -> tuple[dict[str, Any], int]

Build transaction for removing liquidity from a TraderJoe V2 pair.

Parameters:

Name	Type	Description	Default
`token_x`	`str`	Address of token X	required
`token_y`	`str`	Address of token Y	required
`bin_step`	`int`	Bin step of the pair	required
`amount_x_min`	`int`	Minimum amount of token X to receive	required
`amount_y_min`	`int`	Minimum amount of token Y to receive	required
`ids`	`list[int]`	Array of bin IDs to remove liquidity from	required
`amounts`	`list[int]`	Array of amounts of LB tokens to burn for each bin	required
`to`	`str`	Address to receive tokens	required
`deadline`	`int \| None`	Transaction deadline	`None`

Returns:

Type	Description
`tuple[dict[str, Any], int]`	Tuple of (transaction dict, estimated gas)

get_position_balances ¶

get_position_balances(
    pool_address: str,
    wallet_address: str,
    bin_range: int = 50,
) -> dict[int, int]

Get LB token balances for a wallet across bins.

Parameters:

Name	Type	Description	Default
`pool_address`	`str`	Address of the LBPair contract	required
`wallet_address`	`str`	Address to query balances for	required
`bin_range`	`int`	Number of bins to check on each side of active bin	`50`

Returns:

Type	Description
`dict[int, int]`	Dict mapping bin ID to balance

get_total_position_value ¶

get_total_position_value(
    pool_address: str, wallet_address: str
) -> tuple[int, int]

Get total token amounts for a wallet's position in a pool.

Parameters:

Name	Type	Description	Default
`pool_address`	`str`	Address of the LBPair contract	required
`wallet_address`	`str`	Address to query	required

Returns:

Type	Description
`tuple[int, int]`	Tuple of (amount_x, amount_y) the wallet would receive if removing all liquidity

TraderJoeV2SDKError ¶

Bases: Exception

Base exception for TraderJoe V2 SDK errors.

SDKSwapQuote `dataclass` ¶

SDKSwapQuote(
    amount_in: int,
    amount_out: int,
    path: list[str],
    bin_steps: list[int],
    price_impact: Decimal,
    fee: int,
)

Quote for a swap operation.

TraderJoe V2¶

almanak.framework.connectors.traderjoe_v2 ¶

Get a swap quote¶

Use SDK for lower-level operations¶

LiquidityPosition dataclass ¶

SwapQuote dataclass ¶

SwapResult dataclass ¶

SwapType ¶

TraderJoeV2Adapter ¶

Get quote¶

Execute swap¶

resolve_token_address ¶

get_token_decimals ¶

to_wei ¶

from_wei ¶

get_swap_quote ¶

build_swap_transaction ¶

swap_exact_input ¶

get_position ¶

build_add_liquidity_transaction ¶

build_remove_liquidity_transaction ¶

TraderJoeV2Config dataclass ¶

TransactionData dataclass ¶

LiquidityEventData dataclass ¶

ParsedLiquidityResult dataclass ¶

ParsedSwapResult dataclass ¶

ParseResult dataclass ¶

SwapEventData dataclass ¶

TraderJoeV2Event dataclass ¶

TraderJoeV2EventType ¶

TraderJoeV2ReceiptParser ¶

parse_receipt ¶

parse_swap_events ¶

extract_swap_amounts ¶

extract_bin_ids ¶

extract_liquidity ¶

extract_lp_close_data ¶

TransferEventData dataclass ¶

InvalidBinStepError ¶

PoolInfo dataclass ¶

PoolNotFoundError ¶

TraderJoeV2SDK ¶

Get pool info¶

Build swap transaction¶

get_token_contract ¶

get_balance ¶

get_allowance ¶

get_pool_address ¶

get_pair_contract ¶

get_pool_info ¶

get_pool_spot_rate ¶

bin_id_to_price staticmethod ¶

price_to_bin_id staticmethod ¶

build_approve_transaction ¶

build_approve_for_all_transaction ¶

build_swap_exact_tokens_for_tokens ¶

build_add_liquidity ¶

build_remove_liquidity ¶

get_position_balances ¶

get_total_position_value ¶

TraderJoeV2SDKError ¶

SDKSwapQuote dataclass ¶

LiquidityPosition `dataclass` ¶

SwapQuote `dataclass` ¶

SwapResult `dataclass` ¶

TraderJoeV2Config `dataclass` ¶

TransactionData `dataclass` ¶

LiquidityEventData `dataclass` ¶

ParsedLiquidityResult `dataclass` ¶

ParsedSwapResult `dataclass` ¶

ParseResult `dataclass` ¶

SwapEventData `dataclass` ¶

TraderJoeV2Event `dataclass` ¶

TransferEventData `dataclass` ¶

PoolInfo `dataclass` ¶

bin_id_to_price `staticmethod` ¶

price_to_bin_id `staticmethod` ¶

SDKSwapQuote `dataclass` ¶