Getting Started

This guide will walk you through initializing the Uniswap client, formatting token addresses correctly, and performing your very first price quotes and trades on the blockchain.

Initializing the Client

The Uniswap class is your primary interface. It can be instantiated in two modes: Read-Only and Read/Write.

Read-Only Mode

If your goal is building a data scraper, a price dashboard, or an arbitrage scanner, you do not need to expose a private key. You can initialize the client by passing None for the address and private key.

from uniswap import Uniswap

# Read-only initialization
uniswap = Uniswap(
    address=None, 
    private_key=None, 
    version=3,  # Target Uniswap V3
    provider="https://mainnet.infura.io/v3/YOUR_PROJECT_ID"
)

Read/Write Mode (Trading)

To execute trades or add liquidity, you must provide your wallet address and your private key. The library will use these to sign transactions locally before broadcasting them.

Security Best Practice: Never hardcode your private key in your source code. Always load it securely using environment variables or a secret management system.

import os
from uniswap import Uniswap

wallet_address = os.environ.get("WALLET_ADDRESS")
private_key = os.environ.get("PRIVATE_KEY")
rpc_endpoint = os.environ.get("PROVIDER")

# Trading initialization
uniswap = Uniswap(
    address=wallet_address, 
    private_key=private_key, 
    version=3, 
    provider=rpc_endpoint,
    default_slippage=0.01,  # Sets a global 1% slippage tolerance
    use_estimate_gas=True   # Vital for Layer 2s like Arbitrum
)

Configuration Options Explained

  • version: Can be 1, 2, or 3. It determines which set of smart contracts and ABIs the library invokes.
  • default_slippage: A float representing percentage. 0.01 means 1%. This protects you from price changes between the time you send a transaction and when it is mined.
  • use_estimate_gas: If True, calls eth_estimateGas before submitting a transaction, adding a 20% buffer. If False, it hardcodes 250,000 gas. Set this to True on networks like Arbitrum or Optimism.
  • enable_caching: If True, injects Web3 middleware to cache eth_chainId RPC calls, slightly speeding up execution.

Handling Token Addresses

Smart contracts on Ethereum are identified by hexadecimal addresses. uniswap-python requires these to be Checksummed Addresses (as defined in EIP-55). If you pass a lowercase address, the library may throw an error.

You should use Web3.py to ensure addresses are properly formatted:

from web3 import Web3

# The native asset (ETH) is represented by the zero address in this library
ETH = "0x0000000000000000000000000000000000000000"

# Format ERC20 contract addresses
WETH = Web3.to_checksum_address("0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2")
DAI = Web3.to_checksum_address("0x6B175474E89094C44Da98b954EedeAC495271d0F")

Your First Price Quote

Let's calculate how much DAI we can get for 1 ETH on Uniswap V3. Note that V3 features fragmented liquidity across different Fee Tiers. You must specify the fee tier you want to query.

from uniswap.fee import FeeTier

# Tokens use precise integers. 1 ETH is 10^18 Wei.
eth_qty = 1 * 10**18  

# Quote the 0.3% fee pool
dai_received = uniswap.get_price_input(ETH, DAI, eth_qty, fee=FeeTier.TIER_3000)

# Convert back from Wei for human readability
print(f"1 ETH yields {dai_received / 10**18} DAI")

Your First Trade

Let's execute a swap, selling 0.1 ETH for DAI.

The library automatically handles the process of wrapping your ETH into WETH under the hood, determining the minimum acceptable output based on your slippage tolerance, and sending the transaction.

qty_to_sell = int(0.1 * 10**18)

try:
    tx_hash = uniswap.make_trade(
        input_token=ETH, 
        output_token=DAI, 
        qty=qty_to_sell, 
        fee=FeeTier.TIER_3000,
        slippage=0.01  # Accept no less than 99% of the quoted price
    )
    print(f"Success! Transaction Hash: {tx_hash.hex()}")

except Exception as e:
    print(f"Trade failed: {e}")

For a deeper dive into routing, decimal handling, and exact-output trading, proceed to the Usage Guide: Quoting Prices and Usage Guide: Executing Trades.