API Reference

This section details the primary classes, methods, and configurations available in uniswap-python.

Uniswap Class

The central orchestrator. It holds Web3 state, contract configurations, and handles cryptographic signing.

from uniswap import Uniswap

Constructor

Uniswap(
    address: Union[AddressLike, str, None],
    private_key: Optional[str],
    provider: Optional[str] = None,
    web3: Optional[Web3] = None,
    version: int = 1,
    default_slippage: float = 0.01,
    use_estimate_gas: bool = True,
    factory_contract_addr: Optional[str] = None,
    router_contract_addr: Optional[str] = None,
    enable_caching: bool = False,
)
Parameters:

  • address: Your wallet address. Can be None for read-only features.
  • private_key: Your private key. Can be None for read-only features.
  • provider: The HTTP RPC URL (e.g., Infura). Defaults to reading the PROVIDER env variable.
  • web3: Optional injected Web3 instance for advanced users.
  • version: Protocol version (1, 2, or 3). Defaults to 1.
  • default_slippage: Default slippage for trades (0.01 = 1%).
  • use_estimate_gas: If True, simulates transactions to calculate exact gas limits rather than hardcoding. Essential for L2 networks.
  • factory_contract_addr / router_contract_addr: Override base addresses to connect to network forks (e.g., Sushiswap).
  • enable_caching: Enables lru caching for basic RPC calls like chain ID checks.

Pricing Methods

get_price_input(token0, token1, qty, fee=None, route=None)

Returns the maximum output amount of token1 received by spending qty of token0.

  • Returns: int (in target token's smallest unit).
  • Notes: Requires fee on V3. Custom route currently only fully supported on V2.

get_price_output(token0, token1, qty, fee=None, route=None)

Returns the minimum input amount of token0 required to purchase exactly qty of token1.

  • Returns: int.

get_raw_price(token_in, token_out, fee=None)

Returns the mathematical spot price based on current pool reserves/state, regardless of swap size.

  • Returns: float.

estimate_price_impact(token_in, token_out, amount_in, fee, route=None)

Estimates slippage impact for a theoretical trade, deducting protocol fees.

  • Returns: float (Percentage, e.g., 0.05 = 5%).

Trading Methods

All trading methods automatically check ERC20 allowances and submit an approve transaction if necessary.

make_trade(input_token, output_token, qty, recipient=None, fee=None, slippage=None, fee_on_transfer=False)

Swaps an exact qty of input_token for output_token.

  • recipient: Override destination address (defaults to self).
  • slippage: Override global slippage tolerance.
  • fee_on_transfer: (V2 Only) Set to True for deflationary tokenomics.
  • Returns: HexBytes (Transaction Hash).

make_trade_output(input_token, output_token, qty, recipient=None, fee=None, slippage=None)

Swaps to acquire an exact qty of output_token by spending a dynamic amount of input_token.

Liquidity Methods (V3)

get_pool_instance(token_0, token_1, fee=3000)

Fetches the specific V3 Pool Contract instance for a pair.

  • Returns: web3.contract.Contract.

mint_liquidity(pool, amount_0, amount_1, tick_lower, tick_upper, deadline)

Deposits assets into a specific V3 pool range and mints an NFT.

get_liquidity_positions()

Queries the NonFungiblePositionManager to find all active LP NFTs owned by the configured address.

  • Returns: List[int] (Token IDs).

close_position(tokenId, amount0Min=0, amount1Min=0, deadline=None)

Removes 100% of liquidity from a position, collects accrued fees, and burns the NFT token.

Utility & Data Types

FeeTier (Enum)

Standardized V3 fee levels. 

class FeeTier(enum.IntEnum):
    TIER_100 = 100      # 0.01%
    TIER_500 = 500      # 0.05%
    TIER_3000 = 3000    # 0.30%
    TIER_10000 = 10000  # 1.00%

ERC20Token (Dataclass)

Data model containing on-chain metadata. 

@dataclass
class ERC20Token(BaseToken):
    symbol: str
    address: AddressLike
    name: str
    decimals: int

Exceptions

  • InvalidToken: Triggered when providing a non-existent or malformed contract address.
  • InsufficientBalance: Pre-transaction check failure indicating your wallet lacks the funds (or requires more funds than your slippage allows) to execute the trade.
  • InvalidFeeTier: Triggered when interacting with V3 without providing a fee, or providing an unrecognized integer.