uniswap_viewer

  1"""
  2A lightweight Python library for accessing Uniswap V3 on-chain data.
  3
  4`uniswap-viewer` provides a clean and efficient interface for reading price and 
  5tick information directly from Uniswap V3 smart contracts using `web3.py`. It 
  6supports both synchronous and asynchronous workflows and is ideal for 
  7developers, analysts, and algorithmic traders.
  8
  9## Features
 10
 11- Supports both sync and async Web3 clients  
 12- Fetches token prices using `sqrtPriceX96` and token decimals  
 13- Retrieves detailed tick data via ABI-decoded contract calls  
 14- Computes tick index, tick spacing, and tick slot  
 15- Includes block streaming generator to track new blocks in real time  
 16- Built-in utilities for loading ABIs and checking Ethereum addresses  
 17
 18## Modules
 19
 20- `viewer_sync.py` – synchronous Uniswap V3 viewer using `web3.Web3`
 21- `viewer_async.py` – asynchronous Uniswap V3 viewer using `web3.AsyncWeb3`
 22- `utils.py` – helper functions (ABI loading, tick keys, address filters)
 23
 24## Usage
 25
 26### Sync example
 27
 28```python
 29from uniswap_viewer import ViewerSync
 30from web3 import Web3
 31
 32w3 = Web3(Web3.HTTPProvider("<your_provider_url>"))
 33
 34viewer = ViewerSync(w3, "usdt", "weth", fee=3000)
 35viewer.init()
 36
 37price = viewer.get_price()
 38
 39tick = viewer.calc_tick(price, normalize=True)
 40tick_data = viewer.get_tick_data(tick)
 41liquidity = tick_data['liquidityGross']
 42```
 43
 44### Async example
 45
 46```python
 47from uniswap_viewer import ViewerAsync
 48from web3 import AsyncWeb3
 49
 50w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider("<your_provider_url>"))
 51
 52viewer = ViewerAsync(w3, "usdt", "weth", fee=3000)
 53await viewer.init()
 54
 55price = await viewer.get_price()
 56
 57tick = viewer.calc_tick(price, normalize=True)
 58tick_data = await viewer.get_tick_data(tick)
 59liquidity = tick_data['liquidityGross']
 60```
 61
 62### Stream example
 63
 64```python
 65from uniswap_viewer.viewer_async import Viewer as ViewerAsync, stream_new_blocks
 66from web3 import AsyncWeb3
 67
 68w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider("<your_provider_url>"))
 69
 70viewer = ViewerAsync(w3, "usdt", "weth", fee=3000)
 71await viewer.init()
 72
 73async for block_num in stream_new_blocks(w3, timeout=3):
 74    price = await viewer.get_price(block_num=block_num)
 75    
 76    tick = viewer.calc_tick(price, normalize=True)
 77    tick_data = await viewer.get_tick_data(tick, block_num=block_num)
 78    liquidity = tick_data['liquidityGross']
 79
 80    print(price, liquidity)
 81```
 82
 83## Requirements
 84
 85- Python 3.8+
 86- `web3` library (sync or async)
 87
 88## Motivation
 89
 90This library is designed for:
 91
 92- Developers integrating Uniswap data directly from the blockchain
 93- Quants and analysts building custom tooling
 94- Avoiding reliance on third-party APIs like The Graph
 95
 96## License
 97
 98MIT
 99"""
100
101from .utils import *
102from .viewer_sync import Viewer as ViewerSync
103from .viewer_async import Viewer as ViewerAsync