[](https://badge.fury.io/py/web3-ethereum-defi)
[](https://github.com/tradingstrategy-ai/web3-ethereum-defi/actions/workflows/test.yml)
[](https://web3-ethereum-defi.readthedocs.io/)
# Web3-Ethereum-Defi
Web-Ethereum-DeFi (`eth_defi`) Python package provides high level modules for smart
contracts, with prepackaged ABI files for DeFi protocol integration,
wallet management, JSON-RPC providers and automated test suites. The
package aims for robustness, high quality of the code and documentation.
* [Use cases](#use-cases)
* [Prerequisites](#prerequisites)
* [Install](#install)
* [Code examples](#code-examples)
* [Deploy and transfer ERC-20 token between wallets](#deploy-and-transfer-erc-20-token-between-wallets)
* [Uniswap v2 trade example](#uniswap-v2-trade-example)
* [Uniswap v2 price estimation example](#uniswap-v2-price-estimation-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)
* [History](#history)
* [License](#license)
- Supported [blockchains](https://tradingstrategy.ai/glossary) include
Ethereum, BNB Chain, Polygon, Avalanche C-chain, Arbitrum and many
other [EVM-compatible
blockchains](https://tradingstrategy.ai/glossary/evm-compatible).
- Supported
[DeFi](https://tradingstrategy.ai/glossary/decentralised-finance)
[protocols](https://tradingstrategy.ai/glossary/protocol) include
[Uniswap](https://tradingstrategy.ai/glossary/uniswap) with its
[clones](https://tradingstrategy.ai/glossary/fork),
[Aave](https://tradingstrategy.ai/glossary/aave),
[USDC](https://tradingstrategy.ai/glossary/usdc), other Circle
[stablecoin tokens](https://tradingstrategy.ai/glossary/stablecoin),
[Enzyme](https://tradingstrategy.ai/glossary/enzyme-protocol),
Chainlink and many others.
# 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
# Features
Features include e.g.
* [High-quality API documentation](https://web3-ethereum-defi.readthedocs.io/)
* [Fully type hinted](https://web3-ethereum-defi.readthedocs.io/) for good developer experience
* [MEV protection](https://web3-ethereum-defi.readthedocs.io/api/provider/_autosummary_provider/eth_defi.provider.mev_blocker.html#module-eth_defi.provider.mev_blocker)
* [Mainnet forking with Anvil](https://web3-ethereum-defi.readthedocs.io/api/_autosummary/eth_defi.anvil.html#module-eth_defi.anvil)
* [Revert reasons and stack traces for Solidity errors](https://web3-ethereum-defi.readthedocs.io/api/_autosummary/eth_defi.trace.html)
* [Swap, slippage and price impact estimation](https://web3-ethereum-defi.readthedocs.io/api/index.html)
* [ERC-20 token issuance and transfers](https://web3-ethereum-defi.readthedocs.io/en/latest/_autosummary/eth_defi.token.html#module-eth_defi.token)
* [EIP-712, EIP-3009 support](https://web3-ethereum-defi.readthedocs.io/api/core/_autosummary/eth_defi.eip_712.html#module-eth_defi.eip_712)
Web3-Ethereum-Defi supports
* Uniswap (both v2 and v3)
* Sushi
* Aave
* Enzyme Protocol
* dHEDGE Protocol
* More integrations to come
* Built-in integration for over 600 smart contracts with precompiled Solidity ABI files
[Read the full API documentation](https://web3-ethereum-defi.readthedocs.io/)).
For code examples please see below.
# Prerequisites
To use this package you need to
* Have Python 3.10, Python 3.11, or Python 3.12 (no other versions tested)
* macOS, Linux or Windows Subsystem for Linux (WSL) needed, Microsoft Windows is not officially supported
* [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 `pip`:
```shell
pip install "web3-ethereum-defi[data]"
```
With `poetry`:
```shell
# Poetry version
poetry add -E data web3-ethereum-defi
```
With `poetry` - 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.readthedocs.io/tutorials/index.html)
for full code examples.
## PancakeSwap swap example
- This example shows how to read the live trades of PancakeSwap,
and other [Uniswap v2 compatible forks](https://tradingstrategy.ai/glossary/fork) on BNB Smart Chain
- [See the instructions and full example source code in Tutorials](https://web3-ethereum-defi.readthedocs.io/tutorials/pancakeswap-live-minimal.html)
```python
import os
import time
from functools import lru_cache
from web3 import HTTPProvider, Web3
from eth_defi.abi import get_contract
from eth_defi.chain import install_chain_middleware
from eth_defi.event_reader.filter import Filter
from eth_defi.event_reader.logresult import decode_log
from eth_defi.event_reader.reader import read_events, LogResult
from eth_defi.uniswap_v2.pair import fetch_pair_details, PairDetails
QUOTE_TOKENS = ["BUSD", "USDC", "USDT"]
@lru_cache(maxsize=100)
def fetch_pair_details_cached(web3: Web3, pair_address: str) -> PairDetails:
return fetch_pair_details(web3, pair_address)
def main():
json_rpc_url = os.environ.get("JSON_RPC_BINANCE", "https://bsc-dataseed.binance.org/")
web3 = Web3(HTTPProvider(json_rpc_url))
web3.middleware_onion.clear()
install_chain_middleware(web3)
# Read the prepackaged ABI files and set up event filter
# for any Uniswap v2 like pool on BNB Smart Chain (not just PancakeSwap).
#
# We use ABI files distributed by SushiSwap project.
#
Pair = get_contract(web3, "sushi/UniswapV2Pair.json")
filter = Filter.create_filter(address=None, event_types=[Pair.events.Swap])
latest_block = web3.eth.block_number
# Keep reading events as they land
while True:
start = latest_block
end = web3.eth.block_number
evt: LogResult
for evt in read_events(
web3,
start_block=start,
end_block=end,
filter=filter,
):
decoded = decode_log(evt)
# Swap() events are generated by UniswapV2Pool contracts
pair = fetch_pair_details_cached(web3, decoded["address"])
token0 = pair.token0
token1 = pair.token1
block_number = evt["blockNumber"]
# Determine the human-readable order of token tickers
if token0.symbol in QUOTE_TOKENS:
base = token1 # token
quote = token0 # stablecoin/BNB
base_amount = decoded["args"]["amount1Out"] - decoded["args"]["amount1In"]
quote_amount = decoded["args"]["amount0Out"] - decoded["args"]["amount0In"]
else:
base = token0 # stablecoin/BNB
quote = token1 # token
base_amount = decoded["args"]["amount0Out"] - decoded["args"]["amount0Out"]
quote_amount = decoded["args"]["amount1Out"] - decoded["args"]["amount1Out"]
# Calculate the price in Python Decimal class
if base_amount and quote_amount:
human_base_amount = base.convert_to_decimals(base_amount)
human_quote_amount = quote.convert_to_decimals(quote_amount)
price = human_quote_amount / human_base_amount
if human_quote_amount > 0:
# We define selling when the stablecoin amount increases
# in the swap
direction = "sell"
else:
direction = "buy"
price = abs(price)
print(f"Swap block:{block_number:,} tx:{evt['transactionHash']} {direction} price:{price:,.8f} {base.symbol}/{quote.symbol}")
else:
# Swap() event from DEX that is not Uniswap v2 compatible
# print(f"Swap block:{block_number:,} tx:{evt['transactionHash']} could not decode")
pass
else:
# No event detected between these blocks
print(".")
latest_block = end
time.sleep(1)
if __name__ == "__main__":
main()
```
# How to use the library in your Python project
Add `web3-ethereum-defi` as a development dependency:
Using [Poetry](https://python-poetry.org/):
```shell
# Data optional dependencies include pandas and gql, needed to fetch Uniswap v3 data
poetry add -D "web3-ethereum-defi[data]"
```
# Documentation
- [Browse API documentation](https://web3-ethereum-defi.readthedocs.io/).
- [Browse tutorials](https://web3-ethereum-defi.readthedocs.io/tutorials/index.html).
# Development and contributing
- [Read development instructions](https://web3-ethereum-defi.readthedocs.io/development.html).
# Version history
- [Read changelog](https://github.com/tradingstrategy-ai/web3-ethereum-defi/blob/master/CHANGELOG.md).
- [See releases](https://pypi.org/project/web3-ethereum-defi/#history).
# Support
- [Join Discord for any questions](https://tradingstrategy.ai/community).
# Social media
- [Watch tutorials on YouTube](https://www.youtube.com/@tradingstrategyprotocol)
- [Follow on Twitter](https://twitter.com/TradingProtocol)
- [Follow on Telegram](https://t.me/trading_protocol)
- [Follow on LinkedIn](https://www.linkedin.com/company/trading-strategy/)
# License
MIT.
[Created by Trading Strategy](https://tradingstrategy.ai).
Raw data
{
"_id": null,
"home_page": "https://web3-ethereum-defi.readthedocs.io/",
"name": "web3-ethereum-defi",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.10",
"maintainer_email": null,
"keywords": "ethereum, cryptocurrency, uniswap, erc-20, pancakeswap, bnb smart chain, polygon, web3, blockchain, avalanche, arbitrum, chainlink",
"author": "Mikko Ohtamaa",
"author_email": "mikko@tradingstrategy.ai",
"download_url": "https://files.pythonhosted.org/packages/dc/2b/73d63c17737f250d3d633abf5357702ec07125c1af601bbb2541f43ab5b3/web3_ethereum_defi-0.26.1.tar.gz",
"platform": null,
"description": "[](https://badge.fury.io/py/web3-ethereum-defi)\n\n[](https://github.com/tradingstrategy-ai/web3-ethereum-defi/actions/workflows/test.yml)\n\n[](https://web3-ethereum-defi.readthedocs.io/)\n\n# Web3-Ethereum-Defi\n\nWeb-Ethereum-DeFi (`eth_defi`) Python package provides high level modules for smart\ncontracts, with prepackaged ABI files for DeFi protocol integration,\nwallet management, JSON-RPC providers and automated test suites. The\npackage aims for robustness, high quality of the code and documentation.\n\n* [Use cases](#use-cases)\n* [Prerequisites](#prerequisites)\n* [Install](#install)\n* [Code examples](#code-examples)\n * [Deploy and transfer ERC-20 token between wallets](#deploy-and-transfer-erc-20-token-between-wallets)\n * [Uniswap v2 trade example](#uniswap-v2-trade-example)\n * [Uniswap v2 price estimation example](#uniswap-v2-price-estimation-example)\n* [How to use the library in your Python project](#how-to-use-the-library-in-your-python-project)\n* [Documentation](#documentation)\n * [Development and contributing](#development-and-contributing)\n* [Version history](#version-history)\n* [Support](#support)\n* [Social media](#social-media)\n* [History](#history)\n* [License](#license)\n\n\n\n- Supported [blockchains](https://tradingstrategy.ai/glossary) include\n Ethereum, BNB Chain, Polygon, Avalanche C-chain, Arbitrum and many\n other [EVM-compatible\n blockchains](https://tradingstrategy.ai/glossary/evm-compatible).\n- Supported\n [DeFi](https://tradingstrategy.ai/glossary/decentralised-finance)\n [protocols](https://tradingstrategy.ai/glossary/protocol) include\n [Uniswap](https://tradingstrategy.ai/glossary/uniswap) with its\n [clones](https://tradingstrategy.ai/glossary/fork),\n [Aave](https://tradingstrategy.ai/glossary/aave),\n [USDC](https://tradingstrategy.ai/glossary/usdc), other Circle\n [stablecoin tokens](https://tradingstrategy.ai/glossary/stablecoin),\n [Enzyme](https://tradingstrategy.ai/glossary/enzyme-protocol),\n Chainlink and many others.\n\n# Use cases\n\nUse cases for this package include\n\n- Trading and bots\n- Data research, extraction, transformation and loading\n- Portfolio management and accounting\n- System integrations and backends\n \n# Features\n\nFeatures include e.g.\n\n* [High-quality API documentation](https://web3-ethereum-defi.readthedocs.io/)\n* [Fully type hinted](https://web3-ethereum-defi.readthedocs.io/) for good developer experience\n* [MEV protection](https://web3-ethereum-defi.readthedocs.io/api/provider/_autosummary_provider/eth_defi.provider.mev_blocker.html#module-eth_defi.provider.mev_blocker)\n* [Mainnet forking with Anvil](https://web3-ethereum-defi.readthedocs.io/api/_autosummary/eth_defi.anvil.html#module-eth_defi.anvil)\n* [Revert reasons and stack traces for Solidity errors](https://web3-ethereum-defi.readthedocs.io/api/_autosummary/eth_defi.trace.html)\n* [Swap, slippage and price impact estimation](https://web3-ethereum-defi.readthedocs.io/api/index.html)\n* [ERC-20 token issuance and transfers](https://web3-ethereum-defi.readthedocs.io/en/latest/_autosummary/eth_defi.token.html#module-eth_defi.token)\n* [EIP-712, EIP-3009 support](https://web3-ethereum-defi.readthedocs.io/api/core/_autosummary/eth_defi.eip_712.html#module-eth_defi.eip_712)\n\nWeb3-Ethereum-Defi supports \n\n* Uniswap (both v2 and v3)\n* Sushi\n* Aave \n* Enzyme Protocol\n* dHEDGE Protocol\n* More integrations to come\n* Built-in integration for over 600 smart contracts with precompiled Solidity ABI files \n\n[Read the full API documentation](https://web3-ethereum-defi.readthedocs.io/)).\nFor code examples please see below.\n\n# Prerequisites\n\nTo use this package you need to\n\n* Have Python 3.10, Python 3.11, or Python 3.12 (no other versions tested)\n* macOS, Linux or Windows Subsystem for Linux (WSL) needed, Microsoft Windows is not officially supported\n* [Be proficient in Python programming](https://wiki.python.org/moin/BeginnersGuide)\n* [Understand of Web3.py library](https://web3py.readthedocs.io/en/stable/) \n* [Understand Pytest basics](https://docs.pytest.org/)\n\n# Install\n\nWith `pip`:\n\n```shell\npip install \"web3-ethereum-defi[data]\"\n```\n\nWith `poetry`:\n\n```shell\n# Poetry version\npoetry add -E data web3-ethereum-defi\n```\n\nWith `poetry` - master Git branch: \n\n```shell\ngit clone git@github.com:tradingstrategy-ai/web3-ethereum-defi.git\ncd web3-ethereum-defi\npoetry shell\npoetry install --all-extras\n```\n\n# Example code\n\nSee [the tutorials section in the documentation](https://web3-ethereum-defi.readthedocs.io/tutorials/index.html)\nfor full code examples.\n\n## PancakeSwap swap example\n\n- This example shows how to read the live trades of PancakeSwap,\n and other [Uniswap v2 compatible forks](https://tradingstrategy.ai/glossary/fork) on BNB Smart Chain\n\n- [See the instructions and full example source code in Tutorials](https://web3-ethereum-defi.readthedocs.io/tutorials/pancakeswap-live-minimal.html)\n\n```python\nimport os\nimport time\nfrom functools import lru_cache\n\nfrom web3 import HTTPProvider, Web3\n\nfrom eth_defi.abi import get_contract\nfrom eth_defi.chain import install_chain_middleware\nfrom eth_defi.event_reader.filter import Filter\nfrom eth_defi.event_reader.logresult import decode_log\nfrom eth_defi.event_reader.reader import read_events, LogResult\nfrom eth_defi.uniswap_v2.pair import fetch_pair_details, PairDetails\n\n\nQUOTE_TOKENS = [\"BUSD\", \"USDC\", \"USDT\"]\n\n\n@lru_cache(maxsize=100)\ndef fetch_pair_details_cached(web3: Web3, pair_address: str) -> PairDetails:\n return fetch_pair_details(web3, pair_address)\n\n\ndef main():\n json_rpc_url = os.environ.get(\"JSON_RPC_BINANCE\", \"https://bsc-dataseed.binance.org/\")\n web3 = Web3(HTTPProvider(json_rpc_url))\n web3.middleware_onion.clear()\n install_chain_middleware(web3)\n\n # Read the prepackaged ABI files and set up event filter\n # for any Uniswap v2 like pool on BNB Smart Chain (not just PancakeSwap).\n #\n # We use ABI files distributed by SushiSwap project.\n #\n Pair = get_contract(web3, \"sushi/UniswapV2Pair.json\")\n\n filter = Filter.create_filter(address=None, event_types=[Pair.events.Swap])\n\n latest_block = web3.eth.block_number\n\n # Keep reading events as they land\n while True:\n\n start = latest_block\n end = web3.eth.block_number\n\n evt: LogResult\n for evt in read_events(\n web3,\n start_block=start,\n end_block=end,\n filter=filter,\n ):\n\n decoded = decode_log(evt)\n\n # Swap() events are generated by UniswapV2Pool contracts\n pair = fetch_pair_details_cached(web3, decoded[\"address\"])\n token0 = pair.token0\n token1 = pair.token1\n block_number = evt[\"blockNumber\"]\n\n # Determine the human-readable order of token tickers\n if token0.symbol in QUOTE_TOKENS:\n base = token1 # token\n quote = token0 # stablecoin/BNB\n base_amount = decoded[\"args\"][\"amount1Out\"] - decoded[\"args\"][\"amount1In\"]\n quote_amount = decoded[\"args\"][\"amount0Out\"] - decoded[\"args\"][\"amount0In\"]\n else:\n base = token0 # stablecoin/BNB\n quote = token1 # token\n base_amount = decoded[\"args\"][\"amount0Out\"] - decoded[\"args\"][\"amount0Out\"]\n quote_amount = decoded[\"args\"][\"amount1Out\"] - decoded[\"args\"][\"amount1Out\"]\n\n # Calculate the price in Python Decimal class\n if base_amount and quote_amount:\n human_base_amount = base.convert_to_decimals(base_amount)\n human_quote_amount = quote.convert_to_decimals(quote_amount)\n price = human_quote_amount / human_base_amount\n\n if human_quote_amount > 0:\n # We define selling when the stablecoin amount increases\n # in the swap\n direction = \"sell\"\n else:\n direction = \"buy\"\n\n price = abs(price)\n\n print(f\"Swap block:{block_number:,} tx:{evt['transactionHash']} {direction} price:{price:,.8f} {base.symbol}/{quote.symbol}\")\n else:\n # Swap() event from DEX that is not Uniswap v2 compatible\n # print(f\"Swap block:{block_number:,} tx:{evt['transactionHash']} could not decode\")\n pass\n\n else:\n # No event detected between these blocks\n print(\".\")\n\n latest_block = end\n time.sleep(1)\n\n\nif __name__ == \"__main__\":\n main()\n```\n\n# How to use the library in your Python project\n\nAdd `web3-ethereum-defi` as a development dependency:\n\nUsing [Poetry](https://python-poetry.org/):\n\n```shell\n# Data optional dependencies include pandas and gql, needed to fetch Uniswap v3 data\npoetry add -D \"web3-ethereum-defi[data]\"\n```\n\n# Documentation\n\n- [Browse API documentation](https://web3-ethereum-defi.readthedocs.io/).\n- [Browse tutorials](https://web3-ethereum-defi.readthedocs.io/tutorials/index.html).\n\n# Development and contributing\n\n- [Read development instructions](https://web3-ethereum-defi.readthedocs.io/development.html).\n\n# Version history\n\n- [Read changelog](https://github.com/tradingstrategy-ai/web3-ethereum-defi/blob/master/CHANGELOG.md).\n- [See releases](https://pypi.org/project/web3-ethereum-defi/#history).\n\n# Support \n\n- [Join Discord for any questions](https://tradingstrategy.ai/community).\n\n# Social media\n\n- [Watch tutorials on YouTube](https://www.youtube.com/@tradingstrategyprotocol)\n- [Follow on Twitter](https://twitter.com/TradingProtocol)\n- [Follow on Telegram](https://t.me/trading_protocol)\n- [Follow on LinkedIn](https://www.linkedin.com/company/trading-strategy/)\n\n# License \n\nMIT.\n\n[Created by Trading Strategy](https://tradingstrategy.ai).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python library for Uniswap, Aave, ChainLink, Enzyme and other protocols on BNB Chain, Polygon, Ethereum and other blockchains",
"version": "0.26.1",
"project_urls": {
"Changelog": "https://github.com/tradingstrategy-ai/web3-ethereum-defi/blob/master/CHANGELOG.md",
"Discord": "https://discord.gg/5M88m9nM8H",
"Documentation": "https://web3-ethereum-defi.readthedocs.io/",
"Homepage": "https://web3-ethereum-defi.readthedocs.io/",
"Repository": "https://github.com/tradingstrategy-ai/web3-ethereum-defi",
"Sponsor": "https://tradingstrategy.ai",
"Twitter": "https://twitter.com/tradingprotocol",
"Youtube": "https://www.youtube.com/@tradingstrategyprotocol"
},
"split_keywords": [
"ethereum",
" cryptocurrency",
" uniswap",
" erc-20",
" pancakeswap",
" bnb smart chain",
" polygon",
" web3",
" blockchain",
" avalanche",
" arbitrum",
" chainlink"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "89c527fb5c6c10eb55dbb628a01868361edb464d87941f017b11b5fee6151f55",
"md5": "8d67c7c9ea3d02dac0f60642f3abf33b",
"sha256": "45e5caa67e1ba7651a8b5b41f82644505e1fb57eed6645ae8d5f294500f5d7a1"
},
"downloads": -1,
"filename": "web3_ethereum_defi-0.26.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8d67c7c9ea3d02dac0f60642f3abf33b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.10",
"size": 5767248,
"upload_time": "2024-10-14T10:35:10",
"upload_time_iso_8601": "2024-10-14T10:35:10.516067Z",
"url": "https://files.pythonhosted.org/packages/89/c5/27fb5c6c10eb55dbb628a01868361edb464d87941f017b11b5fee6151f55/web3_ethereum_defi-0.26.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dc2b73d63c17737f250d3d633abf5357702ec07125c1af601bbb2541f43ab5b3",
"md5": "eb983b2ed8cd05b320d5a98f99e5c653",
"sha256": "3ba8f3c57e370782217c1d04fd998c41ce9a6b6fbd4d82d6943cb532eb927d79"
},
"downloads": -1,
"filename": "web3_ethereum_defi-0.26.1.tar.gz",
"has_sig": false,
"md5_digest": "eb983b2ed8cd05b320d5a98f99e5c653",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.10",
"size": 4716820,
"upload_time": "2024-10-14T10:35:14",
"upload_time_iso_8601": "2024-10-14T10:35:14.980476Z",
"url": "https://files.pythonhosted.org/packages/dc/2b/73d63c17737f250d3d633abf5357702ec07125c1af601bbb2541f43ab5b3/web3_ethereum_defi-0.26.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-14 10:35:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tradingstrategy-ai",
"github_project": "web3-ethereum-defi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "web3-ethereum-defi"
}
JSON
