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.

属性：

名称	类型	描述
`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.

属性：

名称	类型	描述
`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.

属性：

名称	类型	描述
`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: StrEnum

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.

参数：

名称	类型	描述	默认
`config`	`TraderJoeV2Config`	Adapter configuration	必需
`token_resolver`	`TokenResolver \| None`	Optional TokenResolver instance. If None, uses singleton.	`None`

引发：

类型	描述
`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.

参数：

名称	类型	描述	默认
`token`	`str`	Token symbol (e.g., "WAVAX") or address	必需

返回：

类型	描述
`str`	Checksummed token address

引发：

类型	描述
`TokenResolutionError`	If token cannot be resolved

get_token_decimals ¶

get_token_decimals(token: str) -> int

Get decimals for a token using TokenResolver.

参数：

名称	类型	描述	默认
`token`	`str`	Token symbol or address	必需

返回：

类型	描述
`int`	Token decimals

引发：

类型	描述
`TokenResolutionError`	If decimals cannot be determined

to_wei ¶

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

Convert token amount to wei (smallest unit).

参数：

名称	类型	描述	默认
`amount`	`Decimal`	Amount in token units	必需
`token`	`str`	Token symbol or address	必需

返回：

类型	描述
`int`	Amount in wei

from_wei ¶

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

Convert wei to token amount.

参数：

名称	类型	描述	默认
`amount`	`int`	Amount in wei	必需
`token`	`str`	Token symbol or address	必需

返回：

类型	描述
`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.

参数：

名称	类型	描述	默认
`token_in`	`str`	Input token symbol or address	必需
`token_out`	`str`	Output token symbol or address	必需
`amount_in`	`Decimal`	Amount of input token	必需
`bin_step`	`int`	Bin step for the pair (default 20 = 0.2%)	`20`

返回：

类型	描述
`SwapQuote`	SwapQuote with expected output and price info

引发：

类型	描述
`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.

参数：

名称	类型	描述	默认
`token_in`	`str`	Input token symbol or address	必需
`token_out`	`str`	Output token symbol or address	必需
`amount_in`	`Decimal`	Amount of input token	必需
`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`

返回：

类型	描述
`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().

参数：

名称	类型	描述	默认
`token_in`	`str`	Input token symbol or address	必需
`token_out`	`str`	Output token symbol or address	必需
`amount_in`	`Decimal`	Exact amount of input token	必需
`bin_step`	`int`	Bin step for the pair	`20`
`slippage_bps`	`int \| None`	Slippage tolerance in basis points	`None`

返回：

类型	描述
`SwapResult`	SwapResult with execution details

引发：

类型	描述
`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.

参数：

名称	类型	描述	默认
`token_x`	`str`	Token X symbol or address	必需
`token_y`	`str`	Token Y symbol or address	必需
`bin_step`	`int`	Bin step of the pool	`20`
`wallet`	`str \| None`	Wallet address (default: configured wallet)	`None`

返回：

类型	描述
`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.

参数：

名称	类型	描述	默认
`token_x`	`str`	Token X symbol or address	必需
`token_y`	`str`	Token Y symbol or address	必需
`amount_x`	`Decimal`	Amount of token X to add	必需
`amount_y`	`Decimal`	Amount of token Y to add	必需
`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`

返回：

类型	描述
`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,
    position: LiquidityPosition | None = None,
) -> TransactionData | None

Build a remove liquidity transaction for all positions.

参数：

名称	类型	描述	默认
`token_x`	`str`	Token X symbol or address	必需
`token_y`	`str`	Token Y symbol or address	必需
`bin_step`	`int`	Bin step of the pool	`20`
`slippage_bps`	`int \| None`	Slippage tolerance in basis points	`None`
`position`	`LiquidityPosition \| None`	Optional pre-fetched position. If provided, skips the get_position() call (avoids redundant RPC round trips when the caller already holds the position data).	`None`

返回：

类型	描述
`TransactionData \| None`	TransactionData if position exists, None otherwise

get_pending_fees ¶

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

Query pending fees for an LP position.

参数：

名称	类型	描述	默认
`token_x`	`str`	Token X symbol or address	必需
`token_y`	`str`	Token Y symbol or address	必需
`bin_step`	`int`	Bin step of the pool	`20`
`wallet`	`str \| None`	Wallet address (default: configured wallet)	`None`

返回：

类型	描述
`CollectFeesResult \| None`	CollectFeesResult with pending fee info, or None if no position

build_collect_fees_transaction ¶

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

Build a transaction to collect fees from an LP position without closing it.

Calls LBPair.collectFees(account, binIds) which harvests accumulated fees while keeping the liquidity position intact.

参数：

名称	类型	描述	默认
`token_x`	`str`	Token X symbol or address	必需
`token_y`	`str`	Token Y symbol or address	必需
`bin_step`	`int`	Bin step of the pool	`20`

返回：

类型	描述
`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.

参数：

名称	类型	描述	默认
`chain`	`str`	Chain name (must be "avalanche")	必需
`wallet_address`	`str`	Address of the wallet executing transactions	必需
`rpc_url`	`str`	RPC endpoint URL	必需
`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.

属性：

名称	类型	描述
`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.

参数：

名称	类型	描述	默认
`**kwargs`	`Any`	Additional arguments (ignored for compatibility)	`{}`

parse_receipt ¶

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

Parse a transaction receipt.

参数：

名称	类型	描述	默认
`receipt`	`dict[str, Any]`	Web3 transaction receipt dict	必需

返回：

类型	描述
`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.

参数：

名称	类型	描述	默认
`receipt`	`dict[str, Any]`	Web3 transaction receipt dict	必需

返回：

类型	描述
`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.

参数：

名称	类型	描述	默认
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	必需

返回：

类型	描述
`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.

参数：

名称	类型	描述	默认
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	必需

返回：

类型	描述
`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.

参数：

名称	类型	描述	默认
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	必需

返回：

类型	描述
`int \| None`	None (liquidity amount extraction not implemented for TraderJoe V2)

extract_collected_fees ¶

extract_collected_fees(
    receipt: dict[str, Any],
) -> ParsedFeeCollectionResult | None

Extract collected fees data from a fee collection transaction receipt.

Looks for ClaimedFees events and Transfer events to determine fee amounts. Returns None if ClaimedFees is not found (older LBPair versions without this event).

参数：

名称	类型	描述	默认
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	必需

返回：

类型	描述
`ParsedFeeCollectionResult \| None`	ParsedFeeCollectionResult if fee collection found, None otherwise

extract_fees0 ¶

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

Extract fee amount for token X from fee collection receipt.

参数：

名称	类型	描述	默认
`receipt`	`dict[str, Any]`	Transaction receipt dict	必需

返回：

类型	描述
`int \| None`	Fee amount in wei for token X, or None

extract_fees1 ¶

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

Extract fee amount for token Y from fee collection receipt.

参数：

名称	类型	描述	默认
`receipt`	`dict[str, Any]`	Transaction receipt dict	必需

返回：

类型	描述
`int \| None`	Fee amount in wei for token Y, or None

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.

参数：

名称	类型	描述	默认
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	必需

返回：

类型	描述
`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

参数：

名称	类型	描述	默认
`chain`	`str`	Chain name (e.g., "avalanche")	必需
`rpc_url`	`str`	RPC endpoint URL	必需
`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.

Results are cached in-process: the LBFactory pair address is immutable and does not change after pool creation.

参数：

名称	类型	描述	默认
`token_x`	`str`	Address of token X	必需
`token_y`	`str`	Address of token Y	必需
`bin_step`	`int`	Bin step of the pair (e.g., 20 for 0.2%)	必需

返回：

类型	描述
`str`	Address of the LBPair contract

引发：

类型	描述
`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)

参数：

名称	类型	描述	默认
`pool_address`	`str`	Address of the LBPair contract	必需

返回：

类型	描述
`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)

参数：

名称	类型	描述	默认
`bin_id`	`int`	The bin ID	必需
`bin_step`	`int`	The bin step for the pair	必需
`decimals_x`	`int`	Decimals of tokenX (default 18)	`18`
`decimals_y`	`int`	Decimals of tokenY (default 18)	`18`

返回：

类型	描述
`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

参数：

名称	类型	描述	默认
`price`	`float`	Target price (tokenY per tokenX)	必需
`bin_step`	`int`	The bin step for the pair	必需
`decimals_x`	`int`	Decimals of tokenX (default 18)	`18`
`decimals_y`	`int`	Decimals of tokenY (default 18)	`18`

返回：

类型	描述
`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.

参数：

名称	类型	描述	默认
`token_address`	`str`	Address of the token to approve	必需
`spender_address`	`str`	Address of the spender (usually router)	必需
`amount`	`int`	Amount to approve (in wei)	必需
`from_address`	`str`	Address of the token owner	必需

返回：

类型	描述
`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.

参数：

名称	类型	描述	默认
`pool_address`	`str`	Address of the LBPair contract	必需
`spender_address`	`str`	Address of the spender (usually router)	必需
`from_address`	`str`	Address of the token owner	必需
`approved`	`bool`	Whether to approve or revoke	`True`

返回：

类型	描述
`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.

参数：

名称	类型	描述	默认
`amount_in`	`int`	Amount of input token (in wei)	必需
`amount_out_min`	`int`	Minimum amount of output token (in wei)	必需
`path`	`list[str]`	List of token addresses [tokenIn, tokenOut] or multi-hop	必需
`bin_steps`	`list[int]`	List of binSteps for each pair in the path	必需
`recipient`	`str`	Address to receive output tokens	必需
`deadline`	`int \| None`	Transaction deadline (default: current time + 100 days)	`None`

返回：

类型	描述
`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.

参数：

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

返回：

类型	描述
`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.

参数：

名称	类型	描述	默认
`token_x`	`str`	Address of token X	必需
`token_y`	`str`	Address of token Y	必需
`bin_step`	`int`	Bin step of the pair	必需
`amount_x_min`	`int`	Minimum amount of token X to receive	必需
`amount_y_min`	`int`	Minimum amount of token Y to receive	必需
`ids`	`list[int]`	Array of bin IDs to remove liquidity from	必需
`amounts`	`list[int]`	Array of amounts of LB tokens to burn for each bin	必需
`to`	`str`	Address to receive tokens	必需
`deadline`	`int \| None`	Transaction deadline	`None`

返回：

类型	描述
`tuple[dict[str, Any], int]`	Tuple of (transaction dict, estimated gas)

build_collect_fees ¶

build_collect_fees(
    pool_address: str, account: str, ids: list[int]
) -> tuple[dict[str, Any], int]

Build transaction for collecting accumulated fees from an LP position.

Calls LBPair.collectFees(account, ids) which collects fees without removing any liquidity. This is a V2.1 feature of TraderJoe's Liquidity Book.

The returned bytes32[] encodes fee amounts where each bytes32 has amountX in the upper 128 bits and amountY in the lower 128 bits.

参数：

名称	类型	描述	默认
`pool_address`	`str`	Address of the LBPair contract	必需
`account`	`str`	Address of the account to collect fees for	必需
`ids`	`list[int]`	Array of bin IDs to collect fees from	必需

返回：

类型	描述
`tuple[dict[str, Any], int]`	Tuple of (transaction dict, estimated gas)

引发：

类型	描述
`TraderJoeV2SDKError`	If no bin IDs provided

get_pending_fees ¶

get_pending_fees(
    pool_address: str, account: str, ids: list[int]
) -> tuple[int, int]

Query pending (uncollected) fees for a position.

参数：

名称	类型	描述	默认
`pool_address`	`str`	Address of the LBPair contract	必需
`account`	`str`	Address of the account to query	必需
`ids`	`list[int]`	Array of bin IDs to query fees for	必需

返回：

类型	描述
`tuple[int, int]`	Tuple of (total_fees_x, total_fees_y) in wei

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.

参数：

名称	类型	描述	默认
`pool_address`	`str`	Address of the LBPair contract	必需
`wallet_address`	`str`	Address to query balances for	必需
`bin_range`	`int`	Number of bins to check on each side of active bin	`50`

返回：

类型	描述
`dict[int, int]`	Dict mapping bin ID to balance

get_total_position_value ¶

get_total_position_value(
    pool_address: str,
    wallet_address: str,
    precomputed_balances: dict[int, int] | None = None,
) -> tuple[int, int]

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

参数：

名称	类型	描述	默认
`pool_address`	`str`	Address of the LBPair contract	必需
`wallet_address`	`str`	Address to query	必需
`precomputed_balances`	`dict[int, int] \| None`	Optional pre-fetched bin balances to avoid a redundant get_position_balances() call (pass the result from a prior call to get_position_balances).	`None`

返回：

类型	描述
`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 ¶

get_pending_fees ¶

build_collect_fees_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_collected_fees ¶

extract_fees0 ¶

extract_fees1 ¶

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 ¶

build_collect_fees ¶

get_pending_fees ¶

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` ¶