web3-ethereum-defi 1.0.2
Integrate Web3 and DeFi protocols to Python applications
License: MIT
Requires Python: <4,>=3.10
Keywords: uniswap, aave, gmx, gnosis, ethereum, erc-20, web3, blockchain, arbitrum, chainlink, hyperliquid, ccxt, freqtrade

[![PyPI version](https://badge.fury.io/py/web3-ethereum-defi.svg)](https://badge.fury.io/py/web3-ethereum-defi)

[![Automated test suite](https://github.com/tradingstrategy-ai/web3-ethereum-defi/actions/workflows/test.yml/badge.svg)](https://github.com/tradingstrategy-ai/web3-ethereum-defi/actions/workflows/test.yml)

[![GMX Tests](https://github.com/tradingstrategy-ai/web3-ethereum-defi/actions/workflows/test-gmx.yml/badge.svg)](https://github.com/tradingstrategy-ai/web3-ethereum-defi/actions/workflows/test-gmx.yml)


# Web3-Ethereum-Defi

Web-Ethereum-DeFi (`eth_defi`) allows you to integrate [EVM-compatible](https://tradingstrategy.ai/glossary/evm-compatible) Web3 and DeFi protocols into your Python application.

- [Use cases](#use-cases)
- [Supported protocols, chains and integrations](#supported-protocols-chains-and-integrations)
- [Prerequisites](#prerequisites)
- [Install](#install)
- [Example code](#example-code)
   * [Uniswap swap example](#uniswap-swap-example)
- [How to use the library in your Python project](#how-to-use-the-library-in-your-python-project)
- [Documentation](#documentation)
- [Development and contributing](#development-and-contributing)
- [Version history](#version-history)
- [Support ](#support)
- [Social media](#social-media)
- [License ](#license)

# Use cases

Use cases for this package include

- Trading and bots
- Data research, extraction, transformation and loading
- Portfolio management and accounting
- System integrations and backends
- AI agent interaction for EVM chains

# Supported protocols, chains and integrations

![Supported protocols include Uniswap, Aave, others](https://github.com/tradingstrategy-ai/web3-ethereum-defi/blob/master/docs/source/_static/logo-wall-white.png)

| Protocol         | Actions                                                       | Tutorial and API links                                                                                                                                                          |
|:-----------------|:--------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Uniswap          | Token swaps, data research                                    | [Tutorial](https://web3-ethereum-defi.tradingstrategy.ai/tutorials/make-uniswap-v3-swap-in-python.html)                                                                             |
| Gnosis Safe      | Safe deployment customisation and modules                     | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/safe/index.html)                                                                                                            |
| Circle USDC      | USDC interactions                                             | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/usdc/index.html)                                                                                                            |
| ChainLink        | Read oracle prices, set up oracles                            | [Tutorial](https://web3-ethereum-defi.tradingstrategy.ai/tutorials/chainlink-native-token.html)                                                                                     |
| CoW Swap         | Swaps, vault integration                                      | [Tutorial](https://web3-ethereum-defi.tradingstrategy.ai/tutorials/lagoon-cowswap.html)                                                                                             |
| PancakeSwap      | Token swaps, data research                                    | [Tutorial](https://web3-ethereum-defi.tradingstrategy.ai/tutorials/pancakeswap-live-minimal.html)                                                                                   |
| GMX              | Leveraged trading, spot trading                               | [Tutorial](https://web3-ethereum-defi.tradingstrategy.ai/tutorials/gmx-swap.html) [Freqtrade](https://github.com/tradingstrategy-ai/gmx-ccxt-freqtrade)                            |
| Derive           | Perpetuals, options trading                                   | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/derive/index.html)                                                                                                          |
| gTrade           | Leveraged trading, vaults                                     | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/gains/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/gains-network) |
| Ostium           | Leveraged trading, vaults                                     | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/gains/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/gains-network) |
| LFG              | Token swaps, data research                                    | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/uniswap_v2/index.html)                                                                                                      |
| Aave             | Credit, borrow, read rates                                    | [Tutorial](https://web3-ethereum-defi.tradingstrategy.ai/tutorials/aave-v3-interest-analysis.html)                                                                                  |
| BENQI            | Credit, borrow, read rates                                    | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/aave_v2/index.html)                                                                                                         |
| Lendle           | Credit, borrow, read rates                                    | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/aave_v2/index.html)                                                                                                         |
| Sky (MakerDAO)   | Savings vaults                                                | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/sky/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/sky) |
| Enzyme           | Deposit to vaults, deploy, read vault data                    | [Tutorial](https://web3-ethereum-defi.tradingstrategy.ai/tutorials/enzyme-read-vaults.html)                                                                                         |
| Lagoon           | Deposit to vaults, deploy, read vault data                    | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/lagoon/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/lagoon-finance) |
| Velvet           | Deposit to vaults, deploy, read vault data                    | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/velvet/index.html)                                                                                                          |
| Morpho           | Read vault data                                               | [Tutorial](https://web3-ethereum-defi.tradingstrategy.ai/tutorials/erc-4626-scan-prices.html)                                                                                       |
| Euler            | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/euler/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/euler) |
| Ethena           | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/ethena/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/ethena) |
| IPOR             | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/ipor/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/ipor) |
| 1delta           | Open/close leveraged long/short positions                     | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/one_delta/index.html)                                                                                                       |
| Yearn            | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/yearn/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/yearn) |
| NashPoint        | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/nashpoint/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/nashpoint) |
| Untangle Finance | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/untangle/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/untangle-finance) |
| Plutus           | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/plutus/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/plutus) |
| D2 Finance       | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/d2_finance/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/d2-finance) |
| Umami Finance    | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/umami/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/umami) |
| Harvest Finance  | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/harvest/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/harvest-finance) |
| USDAi            | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/usdai/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/usdai) |
| AUTO Finance     | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/auto_finance/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/auto-finance) |
| Goat Protocol    | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/goat/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/goat-protocol) |
| Cap              | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/cap/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/cap) |
| Centrifuge       | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/centrifuge/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/centrifuge) |
| C-Sigma          | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/csigma/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/csigma-finance) |
| Deltr            | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/deltr/index.html)                                                                                                        |
| Foxify           | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/foxify/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/foxify) |
| Liquidity Royalty| Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/liquidity_royalty/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/liquidity-royalty-tranching) |
| LLamma           | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/llamma/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/llamma) |
| Maple            | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/maple/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/maple) |
| Silo             | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/silo/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/silo-finance) |
| Spark            | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/spark/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/spark) |
| Summer           | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/summer/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/summer-fi) |
| Superform        | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/superform/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/superform) |
| Teller           | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/teller/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/teller) |
| Term Finance     | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/term_finance/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/term-finance) |
| TrueFi           | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/truefi/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/truefi) |
| Upshift          | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/upshift/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/upshift) |
| USDD             | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/usdd/index.html)                                                                                                         |
| Aarna            | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/aarna/index.html)                                                                                                        |
| Accountable      | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/accountable/index.html)                                                                                                  |
| Altura           | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/altura/index.html)                                                                                                       |
| Avant            | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/avant/index.html)                                                                                                        |
| Brink            | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/brink/index.html)                                                                                                        |
| Curvance         | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/curvance/index.html)                                                                                                     |
| Dolomite         | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/dolomite/index.html)                                                                                                     |
| Eth Strategy     | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/eth_strategy/index.html)                                                                                                 |
| Fluid            | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/fluid/index.html)                                                                                                        |
| Frax             | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/frax/index.html)                                                                                                         |
| Gearbox          | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/gearbox/index.html)                                                                                                      |
| Hyperlend        | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/hyperlend/index.html)                                                                                                    |
| HypurrFi         | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/hypurrfi/index.html)                                                                                                     |
| InfiniFi         | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/infinifi/index.html)                                                                                                     |
| Mainstreet       | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/mainstreet/index.html)                                                                                                   |
| Renalta          | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/renalta/index.html)                                                                                                      |
| Resolv           | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/resolv/index.html)                                                                                                       |
| Royco            | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/royco/index.html)                                                                                                        |
| Sentiment        | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/sentiment/index.html)                                                                                                    |
| Singularity      | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/singularity/index.html)                                                                                                  |
| Spectra          | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/spectra/index.html)                                                                                                      |
| USDx Money       | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/usdx_money/index.html)                                                                                                   |
| YieldFi          | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/yieldfi/index.html)                                                                                                      |
| YieldNest        | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/yieldnest/index.html)                                                                                                    |
| YO               | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/yo/index.html)                                                                                                           |
| Yuzu Money       | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/yuzu_money/index.html)                                                                                                   |
| ZeroLend         | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/zerolend/index.html)                                                                                                     |
| BaseVol          | Read vault data                                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/vaults/basevol/index.html) [Listing](https://tradingstrategy.ai/trading-view/vaults/protocols/basevol) |
| Hypersync        | Read historical data fast                                     | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/hypersync/index.html)                                                                                                       |
| Token Risk       | Glider Token Risk API by Hexens                               | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/token_analysis/_autosummary_token_analysis/eth_defi.token_analysis.tokenrisk.html#module-eth_defi.token_analysis.tokenrisk) |
| TokenSniffer     | Read token risk core and metricws                             | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/token_analysis/_autosummary_token_analysis/eth_defi.token_analysis.tokensniffer.html)                                       |
| Foundry          | Compile, deploy and verify smart contracts                    | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/foundry/_autosummary_forge/eth_defi.foundry.forge.html)                                                                     |
| Etherscan        | Deploy and verify smart contracts                             | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/etherscan/index.html)                                                                                                       |
| MEVBlocker       | Frontrun protection                                           | [Tutorial](https://web3-ethereum-defi.tradingstrategy.ai/tutorials/mev-blocker.html)                                                                                                |
| Ethereum mainnet | Frontrun protection, token mapping                            | [Tutorial](https://web3-ethereum-defi.tradingstrategy.ai/tutorials/mev-blocker.html)                                                                                                |                                                                                                                                                                                                                                                        |
| Base             | Frontrun protection, token mapping                            | [Tutorial](https://web3-ethereum-defi.tradingstrategy.ai/tutorials/mev-blocker.html)                                                                                                |
| Arbitrum         | Frontrun protection, token mapping                            | [Tutorial](https://web3-ethereum-defi.tradingstrategy.ai/tutorials/mev-blocker.html)                                                                                                |
| Avalanche        | Token mapping                                                 | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/core/_autosummary/eth_defi.token.html#module-eth_defi.token)                                                                |                                                                                                                                                                        |
| BNB chain        | Token mapping                                                 | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/core/_autosummary/eth_defi.token.html#module-eth_defi.token)                                                                |
| Polygon          | Token mapping                                                 | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/core/_autosummary/eth_defi.token.html#module-eth_defi.token)                                                                |
| BNB Chain        | Token mapping                                                 | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/core/_autosummary/eth_defi.token.html#module-eth_defi.token)                                                                |                                                                                                                                                                           |
| Berachain        | Token mapping                                                 | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/core/_autosummary/eth_defi.token.html#module-eth_defi.token)                                                                |
| Avalanche        | Token mapping                                                 | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/core/_autosummary/eth_defi.token.html#module-eth_defi.token)                                                                |
| Hyperliquid      | Token mapping                                                 | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/core/_autosummary/eth_defi.token.html#module-eth_defi.token)                                                                |
| Mode             | Token mapping                                                 | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/core/_autosummary/eth_defi.token.html#module-eth_defi.token)                                                                |
| Unichain         | Token mapping                                                 | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/core/_autosummary/eth_defi.token.html#module-eth_defi.token)                                                                |
| ZKSync           | Token mapping                                                 | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/core/_autosummary/eth_defi.token.html#module-eth_defi.token)                                                                |
| Soneium          | Token mapping                                                 | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/core/_autosummary/eth_defi.token.html#module-eth_defi.token)                                                                |
| Google GCloud    | Support hardware security module wallets                      | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/core/_autosummary/eth_defi.gcloud_hsm_wallet.html)                                                                          |
| Hot wallet       | Secure hot wallet handling                                    | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/core/_autosummary/eth_defi.hotwallet.html)                                                                                  |
| Multicall3       | Chunked and historical data reading                           | [Tutorial](https://web3-ethereum-defi.tradingstrategy.ai/tutorials/multicall3-with-python.html)                                                                                     |
| Gas              | Ethereum gas management                                       | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/core/_autosummary/eth_defi.gas.html)                                                                                        |
| EIP-4626         | Vault analysis                                                | [Tutorial](https://web3-ethereum-defi.tradingstrategy.ai/tutorials/erc-4626-best-vaults.html)                                                                                       |
| EIP-726          | Message signing and decoding                                  | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/core/_autosummary/eth_defi.eip_712.html#module-eth_defi.eip_712)                                                            |
| ERC-20           | High performance reading, data mappings                       | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/core/_autosummary/eth_defi.token.html)                                                                                      |
| ABI              | High performance smart contract ABI management                | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/core/_autosummary/eth_defi.abi.html)                                                                                        |
| Transactions     | Stack traces and symbolic revert reasons                      | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/core/_autosummary/eth_defi.gas.html)                                                                                        |
| Anvil            | Mainnet works and local unit testing                          | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/provider/_autosummary_provider/eth_defi.provider.anvil.html)                                                                |
| LlamaNodes       | Special RPC support                                           | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/provider/_autosummary_provider/eth_defi.provider.llamanodes.html#module-eth_defi.provider.llamanodes)                       |
| Ankr             | Special RPC support                                           | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/provider/_autosummary_provider/eth_defi.provider.ankr.html)                                                                 |
| dRPC             | Special RPC support                                           | [API](https://web3-ethereum-defi.tradingstrategy.ai/api/event_reader/_autosummary_enzyne/eth_defi.event_reader.fast_json_rpc.get_last_headers.html?highlight=get_last_headers)      |


👉 [Read the full API documentation](https://web3-ethereum-defi.tradingstrategy.ai/).

This is a MIT-licensed open source project. Those who sponsor and contribute get integrations.

# Prerequisites

To use this package you need to

* Have Python 3.12 or older (Python 3.13+ is not yet supported because [Hypersync does not publish wheels for newer versions](https://github.com/tradingstrategy-ai/web3-ethereum-defi/pull/715))
* macOS, Linux or Windows Subsystem for Linux (WSL) needed, Microsoft Windows is not officially supported
  * For WSL, [make sure you have gcc and other tools installed](https://stackoverflow.com/questions/62215963/how-to-install-gcc-and-gdb-for-wslwindows-subsytem-for-linux/63548362#63548362)
* [Be proficient in Python programming](https://wiki.python.org/moin/BeginnersGuide)
* [Understand of Web3.py library](https://web3py.readthedocs.io/en/stable/) 
* [Understand Pytest basics](https://docs.pytest.org/)
 

# Install

With `uv`:

```shell
uv pip install "web3-ethereum-defi" --all-extras
```

With `pip`:

```shell
pip install "web3-ethereum-defi[data,test,docs,hypersync,ccxt,cloudflare_r2,duckdb]"
```

With `poetry`:

```shell
poetry add --extras "data test docs hypersync ccxt cloudflare_r2 duckdb" web3-ethereum-defi
```

From master Git branch:

```shell
git clone git@github.com:tradingstrategy-ai/web3-ethereum-defi.git
cd web3-ethereum-defi
poetry shell
poetry install --all-extras
```

# Example code

See [the tutorials section in the documentation](https://web3-ethereum-defi.tradingstrategy.ai/tutorials/index.html)
for full code examples.

## Uniswap swap example

- This example shows how to make a trade on Uniswap v3.
- The example is for Polygon, but works on other chains.
- See [tutorials](https://web3-ethereum-defi.tradingstrategy.ai/tutorials/index.html) for more Uniswap and other DEX examples

```python

import datetime
import decimal
import os
import sys
from decimal import Decimal

from eth_account import Account
from eth_account.signers.local import LocalAccount
from eth_defi.compat import construct_sign_and_send_raw_middleware

from eth_defi.provider.multi_provider import create_multi_provider_web3
from eth_defi.revert_reason import fetch_transaction_revert_reason
from eth_defi.token import fetch_erc20_details
from eth_defi.confirmation import wait_transactions_to_complete
from eth_defi.uniswap_v3.constants import UNISWAP_V3_DEPLOYMENTS
from eth_defi.uniswap_v3.deployment import fetch_deployment
from eth_defi.uniswap_v3.swap import swap_with_slippage_protection

# The address of a token we are going to swap out
#
# Use https://tradingstrategy.ai/search to find your token
#
# For quote terminology see https://tradingstrategy.ai/glossary/quote-token
#
QUOTE_TOKEN_ADDRESS = "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359"  # USDC (native)

# The address of a token we are going to receive
#
# Use https://tradingstrategy.ai/search to find your token
#
# For base terminology see https://tradingstrategy.ai/glossary/base-token
BASE_TOKEN_ADDRESS = "0x7ceb23fd6bc0add59e62ac25578270cff1b9f619"  # WETH


# Connect to JSON-RPC node
rpc_env_var_name = "JSON_RPC_POLYGON"
json_rpc_url = os.environ.get(rpc_env_var_name)
assert json_rpc_url, f"You need to give {rpc_env_var_name} node URL. Check ethereumnodes.com for options"

# Create a Web3 provider with ability to retry failed requests
# and supporting fallback JSON-RPC nodes. RPC connections
# are extremely flaky and for production grade usage you need to use multiple
# JSON-RPC nodes.
# create_multi_provider_web3() will also take care of any chain-specific
# RPC setup.
web3 = create_multi_provider_web3(json_rpc_url)

print(f"Connected to blockchain, chain id is {web3.eth.chain_id}. the latest block is {web3.eth.block_number:,}")

# Grab Uniswap v3 smart contract addreses for Polygon.
#
deployment_data = UNISWAP_V3_DEPLOYMENTS["polygon"]
uniswap_v3 = fetch_deployment(
    web3,
    factory_address=deployment_data["factory"],
    router_address=deployment_data["router"],
    position_manager_address=deployment_data["position_manager"],
    quoter_address=deployment_data["quoter"],
)

print(f"Using Uniwap v3 compatible router at {uniswap_v3.swap_router.address}")

# Read and setup a local private key
private_key = os.environ.get("PRIVATE_KEY")
assert private_key is not None, "You must set PRIVATE_KEY environment variable"
assert private_key.startswith("0x"), "Private key must start with 0x hex prefix"
account: LocalAccount = Account.from_key(private_key)
my_address = account.address

# Enable eth_sendTransaction using this private key
web3.middleware_onion.add(construct_sign_and_send_raw_middleware(account))

# Read on-chain ERC-20 token data (name, symbol, etc.)
base = fetch_erc20_details(web3, BASE_TOKEN_ADDRESS)
quote = fetch_erc20_details(web3, QUOTE_TOKEN_ADDRESS)

# Native token balance
# See https://tradingstrategy.ai/glossary/native-token
gas_balance = web3.eth.get_balance(account.address)

print(f"Your address is {my_address}")
print(f"Your have {base.fetch_balance_of(my_address)} {base.symbol}")
print(f"Your have {quote.fetch_balance_of(my_address)} {quote.symbol}")
print(f"Your have {gas_balance / (10 ** 18)} for gas fees")

assert quote.fetch_balance_of(my_address) > 0, f"Cannot perform swap, as you have zero {quote.symbol} needed to swap"

# Ask for transfer details
decimal_amount = input(f"How many {quote.symbol} tokens you wish to swap to {base.symbol}? ")

# Some input validation
try:
    decimal_amount = Decimal(decimal_amount)
except (ValueError, decimal.InvalidOperation) as e:
    raise AssertionError(f"Not a good decimal amount: {decimal_amount}") from e

# Fat-fingering check
print(f"Confirm swap amount {decimal_amount} {quote.symbol} to {base.symbol}")
confirm = input("Ok [y/n]?")
if not confirm.lower().startswith("y"):
    print("Aborted")
    sys.exit(1)

# Convert a human-readable number to fixed decimal with 18 decimal places
raw_amount = quote.convert_to_raw(decimal_amount)

# Each DEX trade is two transactions
# - ERC-20.approve()
# - swap (various functions)
# This is due to bad design of ERC-20 tokens,
# more here https://twitter.com/moo9000/status/1619319039230197760

# Uniswap router must be allowed to spent our quote token
# and we do this by calling ERC20.approve() from our account
# to the token contract.
approve = quote.contract.functions.approve(uniswap_v3.swap_router.address, raw_amount)
tx_1 = approve.build_transaction(
    {
        # approve() may take more than 500,000 gas on Arbitrum One
        "gas": 850_000,
        "from": my_address,
    }
)

#
# Uniswap v3 may have multiple pools per
# trading pair differetiated by the fee tier. For example
# WETH-USDC has pools of 0.05%, 0.30% and 1%
# fees. Check for different options
# in https://tradingstrategy.ai/search
#
# Here we use 5 BPS fee pool (5/10,000).
#
#
# Build a swap transaction with slippage protection
#
# Slippage protection is very important, or you
# get instantly overrun by MEV bots with
# sandwitch attacks
#
# https://tradingstrategy.ai/glossary/mev
#
#
bound_solidity_func = swap_with_slippage_protection(
    uniswap_v3,
    base_token=base,
    quote_token=quote,
    max_slippage=20,  # Allow 20 BPS slippage before tx reverts
    amount_in=raw_amount,
    recipient_address=my_address,
    pool_fees=[500],   # 5 BPS pool WETH-USDC
)

tx_2 = bound_solidity_func.build_transaction(
    {
        # Uniswap swap should not take more than 1M gas units.
        # We do not use automatic gas estimation, as it is unreliable
        # and the number here is the maximum value only.
        # Only way to know this number is by trial and error
        # and experience.
        "gas": 1_000_000,
        "from": my_address,
    }
)

# Sign and broadcast the transaction using our private key
tx_hash_1 = web3.eth.send_transaction(tx_1)
tx_hash_2 = web3.eth.send_transaction(tx_2)

# This will raise an exception if we do not confirm within the timeout.
# If the timeout occurs the script abort and you need to
# manually check the transaction hash in a blockchain explorer
# whether the transaction completed or not.
tx_wait_minutes = 2.5
print(f"Broadcasted transactions {tx_hash_1.hex()}, {tx_hash_2.hex()}, now waiting {tx_wait_minutes} minutes for it to be incl