# web3-ethereum-defi: a Python layer over EVM protocols and chains

> web3-ethereum-defi, imported as eth_defi, is a Python library for integrating EVM compatible DeFi protocols into an application, covering Uniswap swaps, Aave credit, Chainlink oracles, USDC transfers and several trading venues. It is a research and integration toolkit with a substantial test suite, not a custody or execution service.

**tradingstrategy-ai/web3-ethereum-defi** — A Python library for trading automation on DeFi, data research and integration. Supporting Uniswap, Aave, Chainlink, USDC and other protocols.

- Repository: https://github.com/tradingstrategy-ai/web3-ethereum-defi
- Website: https://tradingstrategy.ai
- Stars: 829 · Forks: 187
- Language: Python
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/tradingstrategy-ai-web3-ethereum-defi

## A Python surface over EVM protocols

web3-ethereum-defi, imported into code as eth_defi, lets you integrate EVM compatible Web3 and DeFi protocols into a Python application. The package is published on PyPI as web3-ethereum-defi and the import name is the shorter eth_defi, and the source tree holds that package under eth_defi/.

The declared use cases give you a clear picture of who it is for. Trading and bots sit at the top, followed by data research, extraction, transformation and loading, then portfolio management and accounting, system integrations and backends, and finally AI agent interaction for EVM chains. That last entry is a recent addition to the category and explains a good deal of the library's shape, since an agent that wants to move funds needs a single Python API rather than a scattered set of protocol wrappers.

The mechanical core is a protocol wrapper library. The keyword list in the packaging metadata names uniswap, aave, gmx, gnosis, ethereum, erc-20, web3, blockchain, arbitrum, chainlink, hyperliquid, ccxt and freqtrade, which describes the shape of the dependency surface: Ethereum JSON-RPC access, protocol specific clients, and adapters for trading bot frameworks.

## Protocol coverage is wide but tied to the chains you configure

The supported protocols table is long and it is the most useful part of the README for an evaluation, because it lists actions rather than marketing.

Uniswap and PancakeSwap appear for token swaps and data research, with LFG and CoW Swap covering further swap and vault integration. Aave, BENQI and Lendle are listed for credit, borrow and reading rates. Sky, listed as MakerDAO, provides savings vaults, and Enzyme handles depositing to vaults, deploying and reading vault data, with Lagoon offering more of the same. Chainlink covers reading oracle prices and setting up oracles. Circle USDC and Circle CCTP V2 cover USDC interactions and cross-chain USDC transfers by the burn-and-mint route. LI.FI handles a cross-chain bridge and gas feeding. Gnosis Safe is there for Safe deployment customisation and modules. For trading, GMX covers margin and spot trading, Derive covers perpetuals and options, and gTrade and Ostium cover margin trading and vaults.

The important caveat is that this list is a menu, not a guarantee of availability. The vault scanner configuration in the compose file takes one JSON-RPC endpoint per chain through variables such as JSON_RPC_ETHEREUM, JSON_RPC_BERACHAIN, JSON_RPC_UNICHAIN and JSON_RPC_SONIC, plus a CHAIN_ORDER variable that decides which chains are processed. A protocol you want on a chain you have not configured is not usable, and the ordering variable suggests the scanner is meant to run over an explicitly chosen sequence.

## Install with Poetry extras rather than a bare pip install

The packaging is Poetry based, and the install comment at the top of pyproject.toml shows the intended invocation, with extras selected by flag:

```bash
poetry install -E data -E test -E docs -E hypersync -E ccxt -E cloudflare_r2 -E duckdb
```

Those extras are self describing. data pulls the datasets used for research, test brings the test dependencies, docs builds the documentation, hypersync the hypersync client, ccxt the exchange integration, cloudflare_r2 the object storage client and duckdb the analytical database engine. Installing everything by default would pull a lot you probably do not use, so picking extras is the intended path rather than a convenience.

The runtime requirements are modest by comparison. Python is constrained to >=3.10,<4, and the pinned dependencies are the kind of list you read for a reason. urllib3 is held at >=2.6.3 with a comment that it must stay above the vulnerable 2.0.x line and that dependency review blocks optional SDK downgrades. cachetools, eth-bloom for log filters, futureproof for the timeout and retry behaviour, orjson for fast JSON-RPC decoding, and Brotli compression for the data side are also pinned.

The repository also carries tox.ini, a Makefile and a CHANGELOG.md, and the automated test suite plus a separate GMX test workflow run in continuous integration, which is the signal that a protocol change upstream will show up as a failing test rather than as a silent behaviour change.

## The vault scanner runs as a one-shot container with a stamped build

The compose file defines a single service, vault-scanner-oneshot, and the comment above it explains the intent: it runs the ERC-4626 vault scan once and exits, and it is skipped by a plain docker compose up -d because it sits in the oneshot profile. The manual invocation is:

```bash
docker compose --profile oneshot run --rm vault-scanner
```

The build section of that service carries an unusually detailed warning, and it is worth reading before you change anything. The image is built from Dockerfile.vault-scanner with the git revision stamped in at build time and read at runtime by eth_defi.version_info.VersionInfo. The comment says to always build the image with scripts/build-container.sh and not to call docker compose build directly for production images, because the wrapper extracts the current git hash, exact tag and commit message, passes them as build arguments and verifies the image stamp afterwards.

The GIT_VERSION_TAG variable carries a specific constraint: it must be an exact tag or empty, never a fallback describe string or an abbreviated hash. Untagged builds leave it empty, the default of unspecified applies, and VersionInfo normalises that sentinel to None so the tag field is null, with the commit hash acting as the primary build identifier. This is a small thing that tells you a lot, namely that the library cares about telling a deployed vault scanner exactly which commit it is.

## Contract ABIs are compiled locally and copied into the package

Not every protocol ships a clean Python binding, so parts of the library are wired to locally compiled contract ABIs. The Makefile shows how that works.

The sushi target compiles the Sushiswap contracts with yarn inside contracts/sushiswap, creates eth_defi/abi/sushi and copies the resulting artifacts there, excluding the debug files. The in-house target builds the custom integration contracts with forge inside contracts/in-house and then copies a hand-picked list of compiled JSON files into eth_defi/abi, including the Chainlink aggregator interface, mock ERC-20 contracts, the revert test contracts, the vault adapters and the USDC payment forwarder. The guard target builds contracts/guard with forge and copies the guard and vault libraries.

The comments explain why the copying is done by hand rather than wholesale. Forge bundles compiled dependencies into the same folder as the project contracts, so the Makefile picks out files one by one, and the in-house target still carries a note that it depends on Enzyme because OpenZeppelin changed its path structure and the import paths have to stay compatible.

The practical consequence is that this repository is not a pure Python install. The package data includes the ABI directories, and the build depends on a JavaScript and Rust toolchain if you want to recompile the contracts yourself.

## Where eth_defi is the wrong tool

Several situations fit other approaches better.

If you want full control over the RPC layer, the alternative is to talk JSON-RPC directly with web3.py or an equivalent and decode the ABIs yourself, then implement each protocol's quirks in your own code. The difference in approach is who owns the encoding of protocol details. Doing it yourself means no dependency surface and no abstraction, but every contract version change becomes your problem. eth_defi encodes those details for the protocols in its table and keeps them tested, at the cost of a dependency that only covers what its maintainers implemented.

The chain coverage is the other boundary. Support is per protocol and per chain, and the scanner is explicitly configured with one RPC endpoint per chain plus a chain order. A protocol on an unconfigured chain is not reachable, and there is no generic fallback to a public endpoint in the compose configuration, where every JSON_RPC variable is supplied by the operator.

There is a third boundary worth stating plainly. This is an integration and research library. It wraps the protocols, it does not custody keys, it does not decide what a trade should be, and the use case list includes trading and portfolio management without the library taking responsibility for execution risk. The failure_rate_notes.md file at the repository root suggests the maintainers track real failure rates, which is a good sign about honesty and a good reason to read it before trusting any unattended use.

## MIT licence, a docs pipeline and an active repository

The licence is MIT, recorded in the packaging metadata, so the code can be used in commercial and proprietary products under its terms.

On upkeep, the last push was on 2026-10-14 and the repository is not archived. The release record is unusual in a way that is worth understanding: the only recent tagged release is docs-latest, described as the latest docs build and dated 2026-06-12, so the published artefacts on PyPI and the repository history are not on the same clock. The version in the packaging metadata is 1.1, and the changelog lives in CHANGELOG.md at the root with a link to it in the project URLs section.

The rest of the tree shows the working practices of the project. There is a .readthedocs.yml for the documentation build, an AGENTS.md and a CLAUDE.md at the root for tool guidance, a .1delta.env.example for local environment configuration, a vault-shell.sh for interactive work, an rpc-test.sh for exercising RPC behaviour, and an anvil-wtf.md that points at a local Ethereum test node. The presence of node_modules/ committed in the tree is a smell worth noting for anyone planning to fork, since it suggests the tree is not kept as a clean checkout.

The project lives under the tradingstrategy-ai organisation, with the main site at tradingstrategy.ai, the documentation for this library at web3-ethereum-defi.tradingstrategy.ai, and a Discord, sponsor, Twitter and YouTube link listed in the packaging metadata.

## Conclusion

Adopt web3-ethereum-defi if you are building Python tooling that has to read or interact with a specific set of EVM protocols, and you value a tested implementation of each protocol's quirks over controlling the RPC layer yourself. Do not adopt it as a generic multi-chain SDK, since the protocol and chain coverage is tied to the JSON-RPC endpoints you configure, and do not expect it to handle key custody, transaction signing policy or execution risk. Verify three things first: that the protocols you need are in the supported table and available on the chains you run, that your node or provider endpoints are configured through the JSON_RPC variables the vault scanner expects, and that the ABI bundles in eth_defi/abi match the contract versions your deployment uses. The licence is MIT, the package version is 1.1, and the last push was on 2026-10-14.

## FAQ

### What is the eth_defi Python package?

It is the import name for web3-ethereum-defi, a library that lets you integrate EVM compatible Web3 and DeFi protocols into a Python application. Its use cases include trading and bots, data research, portfolio management and accounting, system integrations, and AI agent interaction for EVM chains.

### Which DeFi protocols does web3-ethereum-defi support?

The supported table covers Uniswap, PancakeSwap, LFG and CoW Swap for swaps and vaults, Aave, BENQI and Lendle for credit and borrowing, Chainlink for oracle prices, Circle USDC and CCTP V2 for USDC and cross-chain transfers, LI.FI for bridging, Gnosis Safe, Enzyme and Lagoon for vaults, Sky for savings vaults, and GMX, Derive, gTrade and Ostium for leveraged and derivatives trading.

### How do I install web3-ethereum-defi?

The packaging metadata documents a Poetry install with extras, for example poetry install -E data -E test -E docs -E hypersync -E ccxt -E cloudflare_r2 -E duckdb. Python is required at version 3.10 or later and below 4.

### What does the vault scanner container do?

It runs the ERC-4626 vault scan once and exits, sitting in the oneshot compose profile so a normal docker compose up skips it. You trigger it manually with docker compose --profile oneshot run --rm vault-scanner, and the image should be built with scripts/build-container.sh so the git revision is stamped in and verified.

### Is web3-ethereum-defi suitable for running trading bots?

Trading and bots is one of its listed use cases, and it ships protocol wrappers for several trading venues plus integrations referenced in its keyword list. It provides integration code rather than custody or execution risk management, so the keys and the risk decisions stay with the application that uses it.

## Sources

- [License: MIT](https://github.com/tradingstrategy-ai/web3-ethereum-defi/blob/master/LICENSE)
- [Project website](https://tradingstrategy.ai)
- [README](https://github.com/tradingstrategy-ai/web3-ethereum-defi/blob/master/README.md)
- [Releases](https://github.com/tradingstrategy-ai/web3-ethereum-defi/releases)
- [tradingstrategy-ai/web3-ethereum-defi on GitHub](https://github.com/tradingstrategy-ai/web3-ethereum-defi)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tradingstrategy-ai-web3-ethereum-defi