docs: add v4 narrative guide and fill examples page with v2/v3 snippets

- docs/v4.rst: new page covering PoolKey concept, connecting Uniswap4, spot price, quoting (exact-in/out, single-hop and multi-hop), price impact estimation, making swaps, pool discovery, and full liquidity lifecycle (create pool, mint, read, collect, decrease, burn) - docs/examples.rst: was empty ('No examples here yet!'); now has v2 and v3 examples for prices, swaps, multi-hop, and liquidity management - docs/index.rst: add v4 to the toctree
uniswap-python · ErikBjare · Jul 28, 2026 · Jul 28, 2026 · Jul 28, 2026 · Jul 28, 2026
commit 910fce3e57a5587863c649a19164021b54afe564
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -1,6 +1,193 @@
 Examples
 ========
 
-No examples here yet! Why don't you contribute some?
+This page shows common usage patterns for Uniswap v2 and v3. For v4 examples,
+see the dedicated :doc:`v4` guide.
 
-In the meantime, see the :ref:`Getting started` guide.
+The code snippets here mirror the `test suite
+<https://github.com/uniswap-python/uniswap-python/tree/master/tests>`_, which
+runs every example against a live mainnet fork using
+`Anvil <https://book.getfoundry.sh/anvil/>`_.
+
+.. contents:: Table of contents
+    :local:
+    :depth: 2
+
+Uniswap v2
+----------
+
+Initialization
+``````````````
+
+.. code:: python
+
+    from uniswap import Uniswap
+
+    ETH = "0x0000000000000000000000000000000000000000"
+    USDC = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
+    DAI  = "0x6B175474E89094C44Da98b954EedeAC495271d0F"
+
+    uni = Uniswap(
+        address="0xYOUR_ADDRESS",
+        private_key="0xYOUR_PRIVATE_KEY",  # or None for read-only
+        version=2,
+        provider="https://mainnet.infura.io/v3/YOUR_PROJECT_ID",
+    )
+
+Getting prices
+``````````````
+
+.. code:: python
+
+    ONE_ETH = 10**18
+
+    # How much USDC do I get for 1 ETH?
+    usdc_out = uni.get_price_input(ETH, USDC, ONE_ETH)
+    print(f"1 ETH → {usdc_out / 10**6:.2f} USDC")
+
+    # How much ETH do I need to buy exactly 1000 USDC?
+    eth_needed = uni.get_price_output(ETH, USDC, 1000 * 10**6)
+    print(f"ETH needed for 1000 USDC: {eth_needed / ONE_ETH:.4f}")
+
+Making swaps
+````````````
+
+.. code:: python
+
+    # Sell 0.1 ETH, receive USDC (exact input)
+    tx = uni.make_trade(ETH, USDC, ONE_ETH // 10)
+
+    # Buy exactly 100 USDC, pay in ETH (exact output)
+    tx = uni.make_trade_output(ETH, USDC, 100 * 10**6)
+
+    # Sell ETH → DAI with a custom recipient
+    tx = uni.make_trade(ETH, DAI, ONE_ETH // 10, recipient="0xSOME_OTHER_ADDRESS")
+
+Multi-hop swaps
+```````````````
+
+For pairs without a direct v2 pool, route through an intermediate token:
+
+.. code:: python
+
+    WBTC = "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599"
+
+    # ETH → USDC → WBTC (v2 multi-hop)
+    # Provide the full path as an address list
+    wbtc_out = uni.get_price_input(ETH, WBTC, ONE_ETH // 10)
+    tx = uni.make_trade(ETH, WBTC, ONE_ETH // 10)
+
+Uniswap v3
+----------
+
+v3 adds concentrated liquidity pools at multiple fee tiers. Always specify
+``fee`` to select the pool — the right tier depends on the pair's volatility.
+
+Initialization
+``````````````
+
+.. code:: python
+
+    from uniswap import Uniswap
+
+    ETH = "0x0000000000000000000000000000000000000000"
+    USDC = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
+    WBTC = "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599"
+    DAI  = "0x6B175474E89094C44Da98b954EedeAC495271d0F"
+
+    uni = Uniswap(
+        address="0xYOUR_ADDRESS",
+        private_key="0xYOUR_PRIVATE_KEY",
+        version=3,
+        provider="https://mainnet.infura.io/v3/YOUR_PROJECT_ID",
+    )
+
+Fee tiers
+`````````
+
+Common v3 fee tiers:
+
+- ``500`` — 0.05% (stablecoin pairs, e.g. USDC/USDT)
+- ``3000`` — 0.30% (most pairs, e.g. ETH/USDC)
+- ``10000`` — 1.00% (exotic/volatile pairs)
+
+Getting prices
+``````````````
+
+.. code:: python
+
+    ONE_ETH = 10**18
+
+    # Quote using the 0.30% ETH/USDC pool
+    usdc_out = uni.get_price_input(ETH, USDC, ONE_ETH, fee=3000)
+    print(f"1 ETH → {usdc_out / 10**6:.2f} USDC (0.30% pool)")
+
+    # Compare with the 0.05% pool (better rate for large trades)
+    usdc_out_low = uni.get_price_input(ETH, USDC, ONE_ETH, fee=500)
+    print(f"1 ETH → {usdc_out_low / 10**6:.2f} USDC (0.05% pool)")
+
+    # Exact output quote
+    eth_needed = uni.get_price_output(ETH, USDC, 1000 * 10**6, fee=500)
+
+Making swaps
+````````````
+
+.. code:: python
+
+    # Sell 0.1 ETH for USDC via the 0.05% pool
+    tx = uni.make_trade(ETH, USDC, ONE_ETH // 10, fee=500)
+
+    # Buy exactly 100 USDC, paying in ETH
+    tx = uni.make_trade_output(ETH, USDC, 100 * 10**6, fee=500)
+
+Multi-hop swaps
+```````````````
+
+For pairs without a direct pool, route through an intermediate token using
+the ``route`` parameter:
+
+.. code:: python
+
+    # ETH → USDC → DAI (two 0.05% hops)
+    tx = uni.make_trade(
+        ETH,
+        DAI,
+        ONE_ETH // 10,
+        route=[ETH, USDC, DAI],
+        fee=500,
+    )
+
+Liquidity management (v3)
+`````````````````````````
+
+.. code:: python
+
+    from uniswap.util import default_tick_range
+
+    ETH = "0x0000000000000000000000000000000000000000"
+    USDC = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
+    ONE_ETH = 10**18
+
+    # Get the pool contract instance
+    pool = uni.get_pool_instance(ETH, USDC, fee=500)
+
+    # Sensible full-range tick bounds for this fee tier
+    tick_lower, tick_upper = default_tick_range(fee=500)
+
+    # Mint a liquidity position (returns TxReceipt)
+    receipt = uni.mint_liquidity(
+        pool,
+        amount0=ONE_ETH // 10,
+        amount1=340 * 10**6,
+        tick_lower=tick_lower,
+        tick_upper=tick_upper,
+        deadline=2**64,
+    )
+    assert receipt["status"]
+
+    # Get your token IDs (ERC-721 NFTs representing positions)
+    positions = uni.get_liquidity_positions()
+    token_id = positions[0]
+
+    # Close the position (collects fees + withdraws liquidity in one call)
+    receipt = uni.close_position(token_id, deadline=2**64)
diff --git a/docs/index.rst b/docs/index.rst
@@ -28,8 +28,9 @@ A good place to start is the :doc:`getting-started` guide.
    :caption: Contents:
 
    getting-started
+   v4
    api
-   cli 
+   cli
    examples
    supported-deployments