uniswap.v3 package

Submodules

uniswap.v3.base module

class uniswap.v3.base.BaseContract(w3: Web3, address: ChecksumAddress, abi_path: str)

Bases: object

property contract: Contract

Returns contract instance

property functions: ContractFunctions

Quick access to self.contract.functions

get_functions() → list

List all smart contract available functions

init_contract(address: ChecksumAddress, path: str) → Contract

uniswap.v3.factory module

class uniswap.v3.factory.Factory(w3: Web3, address: ChecksumAddress, abi_path: str = '../utils/abis/factory.abi.json')

Bases: BaseContract

uniswap.v3.main module

class uniswap.v3.main.UniswapV3(client: EtherClient)

Bases: object

Main class to interact with Uniswap v3 smart contracts.

Parameters:

client (EtherClient) – EtherClient Client

Return type:

UniswapV3

property factory: Factory

retrieve the Factory contract.

Return type:

Factory

Type:

Factory

get_pool(token0: ChecksumAddress, token1: ChecksumAddress, fee: int) → Pool

Return the Pool contract wrapper.

Please refer official documentation: https://docs.uniswap.org/contracts/v3/reference/core/UniswapV3Pool

Parameters:

• token0 (ChecksumAddress) – Token0 contract address

• token1 (ChecksumAddress) – Token1 contract address

• fee (int) – Fee of the pool

Return type:

Pool

static is_fee_valid(fee: int) → bool

Return the Pool contract wrapper. Please refer official documentation:

Parameters:

fee (int) – Fee

Return type:

bool

property multicall2: Multicall2

Helper for Multicall2 smart contract.

property nft_position_manager: NonfungiblePositionManager

Helper to Non-fungible position manager smart contract.

property quoter: Quoter

Quoter smart contract.

Type:

Quoter

property swap_router: SwapRouter

Helper to SwapRouter smart contract.

property swap_router_02: SwapRouter02

Helper to SwapRouter02 smart contract.

uniswap.v3.math module

Notes

Below implementation based on the great article of Atis Elsts.

[1] (1,2,3,4)

Atis Elsts “LIQUIDITY MATH IN UNISWAP V3”, https://atiselsts.github.io/pdfs/uniswap-v3-liquidity-math.pdf, 2022

Implementation utilize description of liquidity based on book of Ivan Kuznetsov and all https://github.com/Jeiwan/uniswapv3-book contributors.

[2] (1,2,3)

Source: https://uniswapv3book.com/docs/milestone_1/calculating-liquidity/

uniswap.v3.math.from_sqrtPriceX96(sqrtPriceX96: int) → float

Return price by sqrtPriceX96

uniswap.v3.math.get_amount0(tick_current: int, sqrt_price_x_96: int, tick_lower: int, tick_upper: int, liquidity: int) → int

uniswap.v3.math.get_amount0_delta(sqrt_ratio_ax_96, sqrt_ratio_bx_96, liquidity)

uniswap.v3.math.get_amount0_from_price_range(p: float, pa: float, pb: float, amount1)

Get amount1 from price range and amount0.

Formula (1) [1]

Parameters:

• p (float) – current Price

• pa (float) – price of a lowerTick (i.e.: from_sqrtPriceX96(get_sqrt_ratio_at_tick(lower_tick)))

• pb (float) – price of a a upperTick (i.e.: from_sqrtPriceX96(get_sqrt_ratio_at_tick(upper_tick)))

• amount0 (float) – Amount of the first asset (not in Wei)

Returns:

Amount of the first asset

Return type:

float

uniswap.v3.math.get_amount0_from_tick_range(p: int, pa: int, pb: int, amount1: int) → int

Get amount1 from a tick range and amount0.

Formula (1) [1]

Parameters:

• p (int) – sqrtRatioX96 of current Price

• pa (int) – sqrtRatioX96 from a lowerTick (sqrtRatioAX96)

• pb (int) – sqrtRatioX96 from a upperTick (sqrtRatioAX96)

• amount1 (int) – Amount of the second asset in Wei

Returns:

Amount of the first asset in Wei

Return type:

int

uniswap.v3.math.get_amount1(tick_current: int, sqrt_price_x_96: int, tick_lower: int, tick_upper: int, liquidity: int) → int

uniswap.v3.math.get_amount1_delta(sqrt_ratio_ax_96, sqrt_ratio_bx_96, liquidity)

uniswap.v3.math.get_amount1_from_price_range(p: float, pa: float, pb: float, amount0: float)

Get amount1 from price range and amount1.

3.2.1 Example 1: Amount of assets from a range [1]

Parameters:

• p (float) – current Price

• pa (float) – price of a lowerTick (i.e.: from_sqrtPriceX96(get_sqrt_ratio_at_tick(lower_tick)))

• pb (float) – price of a a upperTick (i.e.: from_sqrtPriceX96(get_sqrt_ratio_at_tick(upper_tick)))

• amount0 (float) – Amount of the first asset (not in Wei)

Returns:

Amount of the second asset

Return type:

float

uniswap.v3.math.get_amount1_from_tick_range(p: int, pa: int, pb: int, amount0: int) → int

Get amount1 from tick range and amount1.

3.2.1 Example 1: Amount of assets from a range [1]

Parameters:

• p (int) – sqrtRatioX96 of current Price

• pa (int) – sqrtRatioX96 from a lowerTick (sqrtRatioAX96)

• pb (int) – sqrtRatioX96 from a upperTick (sqrtRatioAX96)

• amount0 (int) – Amount of the first asset in Wei

Returns:

Amount of the second asset in Wei

Return type:

int

uniswap.v3.math.get_liquidity(sqrt_price_x_96: int, sqrt_price_x_96_tick_lower: int, sqrt_price_x_96_tick_upper: int, amount0: int, amount1: int) → int

Get liquidity of the position by a sqrt of a current price, a lower and upper and amounts of assets. Implementation based on the article [2]

Parameters:

• sqrt_price_x_96 (int) – current sqrtPriceX96

• sqrt_price_x_96_tick_lower (int) – sqrtPriceX96 at tick_lower

• sqrt_price_x_96_tick_upper (int) – sqrtPriceX96 at tick_upper

• amount0 (int) – Amount of the first asset

• amount1 (int) – Amount of the second asset

Returns:

Liquidity

Return type:

float

uniswap.v3.math.get_liquidity0(amount: int, pa: int, pb: int) → int

Get a liquidity by sqrt price range and an amount of the first asset. Implementation based on the article [2]

Notes

uniswap.v3.math.get_liquidity1(amount: int, pa: int, pb: int) → int

Get a liquidity by a range of sqrt prices and an amount of the second asset. Implementation based on the article [2]

uniswap.v3.math.get_sqrt_ratio_at_tick(tick: int) → int

Get sqrtRatioX96 from a tick. Original code: https://github.com/Uniswap/v3-core/blob/main/contracts/libraries/TickMath.sol#L23

Parameters:

tick (int) – Value of the Tick

Returns:

sqrtRatioX96 of a Price for a provided tick

Return type:

int

Notes

A Python equivalent don’t give the same precision of the result. Its Python equivalent is:

def get_sqrt_ratio_at_tick(tick):
    return int(sqrt(1.0001**tick) * Q96)

uniswap.v3.math.get_tick_from_price(price: float) → int

Return tick by provided price

Parameters:

price (float) – price

Returns:

Tick

Return type:

int

uniswap.v3.math.mul_shift(val, mul_by)

uniswap.v3.math.to_sqrtPriceX96(price: float) → int

Return sqrtPriceX96 by the price

uniswap.v3.models module

class uniswap.v3.models.Multicall2Call(func_call: ContractFunction, name: str = '', returns: list[tuple] | None = None, outputs: list[dict] | None = None, block_number: int = 0)

Bases: object

This is a helper dataclass for the Multicall2.

block_number: int = 0

func_call: ContractFunction

name: str = ''

outputs: list[dict] = None

returns: list[tuple] = None

class uniswap.v3.models.NftPosition(token_id: int, raw: uniswap.v3.models.NftPositionRaw, pool: uniswap.v3.models.PoolData, amount0: int = 0, amount1: int = 0, amount0HR: float = 0.0, amount1HR: float = 0.0, unclaimedfeesamount0: int = 0, unclaimedfeesamount1: int = 0, unclaimedfeesamount0HR: float = 0.0, unclaimedfeesamount1HR: float = 0.0, lower_price: float = 0.0, upper_price: float = 0.0, lower_price_inverse: float = 0.0, upper_price_inverse: float = 0.0, token0: uniswap.v3.models.Token = None, token1: uniswap.v3.models.Token = None, fee: float = 0.0)

Bases: object

amount0: int = 0

amount0HR: float = 0.0

amount1: int = 0

amount1HR: float = 0.0

fee: float = 0.0

lower_price: float = 0.0

lower_price_inverse: float = 0.0

pool: PoolData

raw: NftPositionRaw

token0: Token = None

token1: Token = None

token_id: int

unclaimedfeesamount0: int = 0

unclaimedfeesamount0HR: float = 0.0

unclaimedfeesamount1: int = 0

unclaimedfeesamount1HR: float = 0.0

upper_price: float = 0.0

upper_price_inverse: float = 0.0

class uniswap.v3.models.NftPositionRaw(token_id: int, nonce: int, operator: eth_typing.evm.ChecksumAddress, token0: eth_typing.evm.ChecksumAddress, token1: eth_typing.evm.ChecksumAddress, fee: int, tickLower: int, tickUpper: int, liquidity: int, feeGrowthInside0LastX128: int, feeGrowthInside1LastX128: int, tokensOwed0: int, tokensOwed1: int, token_URI_data: None)

Bases: object

fee: int

feeGrowthInside0LastX128: int

feeGrowthInside1LastX128: int

liquidity: int

nonce: int

operator: ChecksumAddress

tickLower: int

tickUpper: int

token0: ChecksumAddress

token1: ChecksumAddress

token_URI_data: None

token_id: int

tokensOwed0: int

tokensOwed1: int

class uniswap.v3.models.NftPositionUriData(name: str, description: str, image: str)

Bases: object

description: str

image: str

name: str

class uniswap.v3.models.PoolData(immutables: PoolImmutablesRaw, state: PoolStateRaw, token0: Token, token1: Token, address: ChecksumAddress, token0Price: float, token1Price: float)

Bases: object

Human-readable pool data

address: ChecksumAddress

immutables: PoolImmutablesRaw

state: PoolStateRaw

token0: Token

token0Price: float

token1: Token

token1Price: float

class uniswap.v3.models.PoolImmutablesRaw(factory: ChecksumAddress, token0: ChecksumAddress, token1: ChecksumAddress, fee: int, tickSpacing: int, maxLiquidityPerTick: int)

Bases: object

Immutable Pool’s data

factory: ChecksumAddress

fee: int

maxLiquidityPerTick: int

tickSpacing: int

token0: ChecksumAddress

token1: ChecksumAddress

class uniswap.v3.models.PoolStateRaw(liquidity: int, sqrtPriceX96: int, tick: int, observationIndex: int, observationCardinality: int, observationCardinalityNext: int, feeProtocol: int, unlocked: bool)

Bases: object

Mutable Pool’s data

feeProtocol: int

liquidity: int

observationCardinality: int

observationCardinalityNext: int

observationIndex: int

sqrtPriceX96: int

tick: int

unlocked: bool

class uniswap.v3.models.Token(chainId: int, decimals: int, symbol: str, name: str, isNative: bool, isToken: bool, address: eth_typing.evm.ChecksumAddress)

Bases: object

address: ChecksumAddress

chainId: int

decimals: int

isNative: bool

isToken: bool

name: str

symbol: str

class uniswap.v3.models.UncheckedNftPosition(raw: uniswap.v3.models.UncheckedNftPositionRaw, lower_price: float = 0.0, upper_price: float = 0.0, amount0: int = 0, amount1: int = 0, amount0HR: float = 0.0, amount1HR: float = 0.0, token0: uniswap.v3.models.Token = None, token1: uniswap.v3.models.Token = None, fee: float = 0.0, adj_amount0: int = 0, adj_amount1: int = 0, adj_amount0HR: float = 0.0, adj_amount1HR: float = 0.0, adj_lower_price: float = 0.0, adj_upper_price: float = 0.0)

Bases: object

adj_amount0: int = 0

adj_amount0HR: float = 0.0

adj_amount1: int = 0

adj_amount1HR: float = 0.0

adj_lower_price: float = 0.0

adj_upper_price: float = 0.0

amount0: int = 0

amount0HR: float = 0.0

amount1: int = 0

amount1HR: float = 0.0

fee: float = 0.0

lower_price: float = 0.0

raw: UncheckedNftPositionRaw

token0: Token = None

token1: Token = None

upper_price: float = 0.0

class uniswap.v3.models.UncheckedNftPositionRaw(pool: uniswap.v3.models.PoolData, current_tick: int, current_price_x96: int, lower_tick: int, upper_tick: int, amount0: int, amount1: int)

Bases: object

amount0: int

amount1: int

current_price_x96: int

current_tick: int

lower_tick: int

pool: PoolData

upper_tick: int

class uniswap.v3.models.UncheckedTrade(raw: uniswap.v3.models.UncheckedTradeRaw, route: list[uniswap.v3.models.Token], fee: float, inputAmount: float, outputAmount: float, tradeType: 1)

Bases: object

fee: float

inputAmount: float

outputAmount: float

raw: UncheckedTradeRaw

route: list[uniswap.v3.models.Token]

tradeType: 1

class uniswap.v3.models.UncheckedTradeRaw(route: list[eth_typing.evm.ChecksumAddress], fee: int, inputAmount: int, outputAmount: int, tradeType: 1)

Bases: object

fee: int

inputAmount: int

outputAmount: int

route: list[eth_typing.evm.ChecksumAddress]

tradeType: 1

uniswap.v3.multicall2 module

class uniswap.v3.multicall2.Multicall2(client: EtherClient, address: ChecksumAddress, abi_path: str = '../utils/abis/multicall2.abi.json')

Bases: BaseContract

Multicall2 smart contract wrapper. It is using for pack several read or write smart contract call in a one single call.

Please refer official documentation (no real documentation): https://docs.uniswap.org/contracts/v3/reference/deployments

Refer to source code: https://etherscan.io/address/0x5ba1e12693dc8f9c48aad8770482f4739beed696#code

Parameters:

• client (EtherClient) – EtherClient Client

• address (ChecksumAddress) – Address of the Multicall2 smart contract

• abi_path (str, optional, default = "../utils/abis/multicall2.abi.json") – Path to the ABI of the Multicall2 start contract.

client

Type:

EtherClient

aggregate_and_call(functions: list[web3.contract.contract.ContractFunction]) → list[uniswap.v3.models.Multicall2Call]

Run multiple smart contract call at once

Parameters:

functions (list[ContractFunction]) – A list of contract call with input params.

Returns:

calls – A list of contract call with returns.

Return type:

list[Multicall2Call]

uniswap.v3.nft_position_manager module

class uniswap.v3.nft_position_manager.NonfungiblePositionManager(client: EtherClient, w3: Web3, address: ChecksumAddress, abi_path: str = '../utils/abis/nft_position_manager.abi.json')

Bases: BaseContract

NonfungiblePositionManager contract helper class.

Original source code: https://github.com/Uniswap/v3-periphery/blob/v1.0.0/contracts/NonfungiblePositionManager.sol

Deployment address: https://docs.uniswap.org/protocol/reference/deployments

Parameters:

• client (EtherClient) – Ethereum client

• address (eth_typing.ChecksumAddress) – Address of NonfungiblePositionManager

• abi_path (str, optional, default="../utils/abis/nft_position_manager.abi.json") – Path to json with ABI of the contract.

Return type:

NonfungiblePositionManager

collect(token_id: int, recipient: ChecksumAddress | None = None, wait: bool = False) → HexBytes

Collect fees and all results of single decrease_liquidity.

Parameters:

• token_id (int) – ID of the existing position to be top up with a liquidity

• recipient (ChecksumAddress) – Address of the recipient’s wallet. By default same wallet.

• wait (bool) – If True execution blocked until transaction will be confirmed. By default, False we don’t wait transaction confirmation.

Returns:

tx_hash of the resulting transaction

Return type:

HexBytes

create_position(pool_data: PoolData, current_price: float, lower_price: float, upper_price: float, amount0: float | None = None, amount1: float | None = None) → UncheckedNftPosition

Create an unChecked liquidity position. One of a amount0 or amount1 must be provided.

Parameters:

• pool (uniswap.v3.models.PoolData) – current state of the liquidity pool

• current_price (float) – Current price in the liquidity pool

• lower_price (float) – Lower price to be provided in the liquidity pool

• upper_price (float) – Upper price to be provided in the liquidity pool

• amount0 (float) – [Optional] Desired amount token0 to be provided

• amount1 (float) – [Optional] Desired amount token1 to be provided

Returns:

Position to be submitted via self.mint method

Return type:

uniswap.v3.models.UncheckedNftPosition

property data

Get human readable information from pool

decode_multicall(payload)

decrease_collect(token_id: int, pool: Pool, percent: float, recipient: ChecksumAddress | None = None, deadline: int = 18446744073709551616, wait: bool = False, nft_position: NftPosition | None = None) → HexBytes

Collect fees and all results of single decrease_liquidity.

Parameters:

• token_id (int) – ID of the existing position to be top up with a liquidity

• pool (Pool) – Current poll of the position

• percent (float) – percent of liquidity will be withdrawn. 0.5 = 50%

• recipient (ChecksumAddress) – [Optional] Address of the recipient’s wallet. By default same wallet.

• deadline (epoch) – [Optional] deadline for minting transaction. By default 2 ** 64

• wait (bool) – [Optional] If True execution blocked until transaction will be confirmed. By default, False we don’t wait transaction confirmation.

• nft_position (NftPosition) – [Optional] Current NftPosition

Returns:

tx_hash of the resulting transaction

Return type:

HexBytes

decrease_liquidity(token_id: int, pool: Pool, percent: float, deadline: int = 18446744073709551616, wait: bool = False, nft_position: NftPosition | None = None) → HexBytes

!!! Please use decrease_collect, if you want the same behavior as on app.uniswap.org Decrease liquidity for the existing position for Humans. Please provide result of self.create_position.

Parameters:

• token_id (int) – ID of the existing position to be top up with a liquidity

• pool (Pool) – Current poll of the position

• percent (float) – percent of liquidity will be withdrawn. 0.5 = 50%

• deadline (epoch) – deadline for minting transaction. By default 2 ** 64

• wait (bool) – If True execution blocked until transaction will be confirmed. By default, False we don’t wait transaction confirmation.

• nft_position (NftPosition) – [Optional] Current NftPosition

Returns:

tx_hash of the resulting transaction

Return type:

HexBytes

increase_liquidity(token_id: int, unchecked_nft_position: UncheckedNftPosition, deadline: int = 18446744073709551616, wait: bool = False) → HexBytes

Increase liquidity for the existing position for Humans. Please provide result of self.create_position.

Parameters:

• token_id (int) – ID of the existing position to be top up with a liquidity

• unchecked_nft_position (UncheckedNftPosition) – prepared data for minting of a new position

• deadline (epoch) – deadline for minting transaction. By default 2 ** 64

• wait (bool) – If True execution blocked until transaction will be confirmed. By default, False we don’t wait transaction confirmation.

Returns:

tx_hash of the resulting transaction

Return type:

HexBytes

mint(unchecked_nft_position: UncheckedNftPosition, recipient: ChecksumAddress | None = None, deadline: int = 18446744073709551616, wait: bool = False) → HexBytes

Mint position for Humans. Please provide result of self.create_position.

Parameters:

• unchecked_nft_position (UncheckedNftPosition) – prepared data for minting of a new position

• recipient (ChecksumAddress) – Address of the recipient’s wallet. By default same wallet.

• deadline (epoch) – deadline for minting transaction. By default 2 ** 64

• wait (bool) – If True execution blocked until transaction will be confirmed. By default, False we don’t wait transaction confirmation.

Returns:

tx_hash of the resulting transaction

Return type:

HexBytes

send_tx(signed_transaction, wait: bool = False) → HexBytes | TxReceipt

sign_tx(transaction)

uniswap.v3.pool module

class uniswap.v3.pool.Pool(client, address: ChecksumAddress, abi_path: str = '../utils/abis/pool.abi.json')

Bases: BaseContract

Pool contract wrapper. Please refer official documentation: https://docs.uniswap.org/contracts/v3/reference/core/UniswapV3Pool

property data: PoolData

Get human readable information from pool

from_tokenPrice(price, token0: Token, token1: Token)

Get human readable price of token

property immutables: PoolImmutablesRaw

Get immutables

property state: PoolStateRaw

Get mutable parameters of a Pool

token0Price() → float

Get human readable price of token0

token1Price() → float

Get human readable price of token1

uniswap.v3.quoter module

class uniswap.v3.quoter.Quoter(w3: Web3, address: ChecksumAddress, abi_path: str = '../utils/abis/quoter.abi.json')

Bases: BaseContract

amount_from_wei(token: Token, amount)

amount_to_wei(token: Token, amount)

property data

Get human readable information from pool

get_trade(token0: Token, token1: Token, fee, amount_in) → UncheckedTrade

uniswap.v3.swap_router module

class uniswap.v3.swap_router.SwapRouter(w3: Web3, address: ChecksumAddress, abi_path: str = '../utils/abis/swap_router.abi.json')

Bases: BaseContract

property data

Get human readable information from pool

uniswap.v3.swap_router_02 module

class uniswap.v3.swap_router_02.SwapRouter02(client: EtherClient, address: ChecksumAddress, abi_path: str = '../utils/abis/swap_router_02.abi.json')

Bases: BaseContract

SwapRouter02 contract wrapper. Please refer official documentation: https://docs.uniswap.org/contracts/v2/reference/smart-contracts/router-02

Parameters:

• client (EtherClient) – EtherClient Client

• address (ChecksumAddress) – Address of the ERC20 token smart contract

• abi_path (str) – Path to json file with ABI of the contract. By default is ../utils/abis/swap_router_02.abi.json

property data

NotImplementedError

decode_multicall(payload: HexStr) → list

Decode provided payload with multicall data for the array of inputs.

Parameters:

payload (HexStr) – Encoded smart contract call.

Return type:

list of tuples of function objects and decoded input parameters

swapExactTokensForTokens(unchecked_trade: UncheckedTrade, to, slippage: float = 0.01, wait=False) → HexBytes | TxReceipt

Run swapExactTokensForTokens from Uniswap router 2. It will sell Token0 for Token1. Please refer official documentation: https://docs.uniswap.org/contracts/v2/reference/smart-contracts/router-02#swapexacttokensfortokens

Parameters:

• unchecked_trade (UncheckedTrade) – UnChecked trade from uni.quoter.get_trade.

• to (ChecksumAddress) – Address of recipient wallet.

• slippage (float) – [Optional]. By default 1%. Slippage in absolute value. i.e. 50% == 0.5, 0.1% = 0.001, 5% == 0.05

• wait (bool) – [Optional]. If true, execution will be locked until transaction not been verified by blockchain. By default is False.

Return type:

HexBytes | TxReceipt