DeFiPy 1.0.9__tar.gz → 1.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. defipy-1.2.0/DeFiPy.egg-info/PKG-INFO +167 -0
  2. {defipy-1.0.9 → defipy-1.2.0}/DeFiPy.egg-info/SOURCES.txt +4 -0
  3. defipy-1.2.0/DeFiPy.egg-info/requires.txt +16 -0
  4. defipy-1.2.0/PKG-INFO +167 -0
  5. defipy-1.2.0/README.md +130 -0
  6. {defipy-1.0.9 → defipy-1.2.0}/python/prod/__init__.py +24 -5
  7. {defipy-1.0.9 → defipy-1.2.0}/python/prod/agents/ImpermanentLossAgent.py +3 -3
  8. {defipy-1.0.9 → defipy-1.2.0}/python/prod/agents/PriceThresholdSwapAgent.py +1 -1
  9. {defipy-1.0.9 → defipy-1.2.0}/python/prod/agents/TVLBasedLiquidityExitAgent.py +2 -2
  10. {defipy-1.0.9 → defipy-1.2.0}/python/prod/agents/VolumeSpikeNotifierAgent.py +3 -3
  11. defipy-1.2.0/python/prod/primitives/__init__.py +1 -0
  12. defipy-1.2.0/python/prod/primitives/position/AnalyzePosition.py +189 -0
  13. defipy-1.2.0/python/prod/primitives/position/__init__.py +1 -0
  14. defipy-1.2.0/python/prod/utils/data/PositionAnalysis.py +61 -0
  15. defipy-1.2.0/python/prod/utils/data/__init__.py +4 -0
  16. {defipy-1.0.9 → defipy-1.2.0}/setup.py +29 -17
  17. defipy-1.0.9/DeFiPy.egg-info/PKG-INFO +0 -247
  18. defipy-1.0.9/DeFiPy.egg-info/requires.txt +0 -6
  19. defipy-1.0.9/PKG-INFO +0 -247
  20. defipy-1.0.9/README.md +0 -212
  21. defipy-1.0.9/python/prod/utils/data/__init__.py +0 -1
  22. {defipy-1.0.9 → defipy-1.2.0}/DeFiPy.egg-info/dependency_links.txt +0 -0
  23. {defipy-1.0.9 → defipy-1.2.0}/DeFiPy.egg-info/not-zip-safe +0 -0
  24. {defipy-1.0.9 → defipy-1.2.0}/DeFiPy.egg-info/top_level.txt +0 -0
  25. {defipy-1.0.9 → defipy-1.2.0}/LICENSE +0 -0
  26. {defipy-1.0.9 → defipy-1.2.0}/NOTICE +0 -0
  27. {defipy-1.0.9 → defipy-1.2.0}/python/prod/agents/__init__.py +0 -0
  28. {defipy-1.0.9 → defipy-1.2.0}/python/prod/agents/config/ImpermanentLossConfig.py +0 -0
  29. {defipy-1.0.9 → defipy-1.2.0}/python/prod/agents/config/PriceThresholdConfig.py +0 -0
  30. {defipy-1.0.9 → defipy-1.2.0}/python/prod/agents/config/TVLExitConfig.py +0 -0
  31. {defipy-1.0.9 → defipy-1.2.0}/python/prod/agents/config/VolumeSpikeConfig.py +0 -0
  32. {defipy-1.0.9 → defipy-1.2.0}/python/prod/agents/config/__init__.py +0 -0
  33. {defipy-1.0.9 → defipy-1.2.0}/python/prod/agents/data/UniswapPoolData.py +0 -0
  34. {defipy-1.0.9 → defipy-1.2.0}/python/prod/agents/data/__init__.py +0 -0
  35. {defipy-1.0.9 → defipy-1.2.0}/python/prod/analytics/risk/__init__.py +0 -0
  36. {defipy-1.0.9 → defipy-1.2.0}/python/prod/analytics/simulate/__init__.py +0 -0
  37. {defipy-1.0.9 → defipy-1.2.0}/python/prod/erc/__init__.py +0 -0
  38. {defipy-1.0.9 → defipy-1.2.0}/python/prod/math/basic/__init__.py +0 -0
  39. {defipy-1.0.9 → defipy-1.2.0}/python/prod/math/interest/__init__.py +0 -0
  40. {defipy-1.0.9 → defipy-1.2.0}/python/prod/math/interest/ips/__init__.py +0 -0
  41. {defipy-1.0.9 → defipy-1.2.0}/python/prod/math/interest/ips/aggregate/__init__.py +0 -0
  42. {defipy-1.0.9 → defipy-1.2.0}/python/prod/math/model/__init__.py +0 -0
  43. {defipy-1.0.9 → defipy-1.2.0}/python/prod/math/risk/__init__.py +0 -0
  44. {defipy-1.0.9 → defipy-1.2.0}/python/prod/process/__init__.py +0 -0
  45. {defipy-1.0.9 → defipy-1.2.0}/python/prod/process/burn/__init__.py +0 -0
  46. {defipy-1.0.9 → defipy-1.2.0}/python/prod/process/deposit/__init__.py +0 -0
  47. {defipy-1.0.9 → defipy-1.2.0}/python/prod/process/join/Join.py +0 -0
  48. {defipy-1.0.9 → defipy-1.2.0}/python/prod/process/join/__init__.py +0 -0
  49. {defipy-1.0.9 → defipy-1.2.0}/python/prod/process/liquidity/AddLiquidity.py +0 -0
  50. {defipy-1.0.9 → defipy-1.2.0}/python/prod/process/liquidity/RemoveLiquidity.py +0 -0
  51. {defipy-1.0.9 → defipy-1.2.0}/python/prod/process/liquidity/__init__.py +0 -0
  52. {defipy-1.0.9 → defipy-1.2.0}/python/prod/process/mint/__init__.py +0 -0
  53. {defipy-1.0.9 → defipy-1.2.0}/python/prod/process/swap/Swap.py +0 -0
  54. {defipy-1.0.9 → defipy-1.2.0}/python/prod/process/swap/__init__.py +0 -0
  55. {defipy-1.0.9 → defipy-1.2.0}/python/prod/utils/client/__init__.py +0 -0
  56. {defipy-1.0.9 → defipy-1.2.0}/python/prod/utils/client/contract/ExecuteScript.py +0 -0
  57. {defipy-1.0.9 → defipy-1.2.0}/python/prod/utils/client/contract/__init__.py +0 -0
  58. {defipy-1.0.9 → defipy-1.2.0}/python/prod/utils/interfaces/__init__.py +0 -0
  59. {defipy-1.0.9 → defipy-1.2.0}/python/prod/utils/tools/UniswapScriptHelper.py +0 -0
  60. {defipy-1.0.9 → defipy-1.2.0}/python/prod/utils/tools/__init__.py +0 -0
  61. {defipy-1.0.9 → defipy-1.2.0}/python/prod/utils/tools/v3/__init__.py +0 -0
  62. {defipy-1.0.9 → defipy-1.2.0}/setup.cfg +0 -0
@@ -0,0 +1,167 @@
1
+ Metadata-Version: 2.4
2
+ Name: DeFiPy
3
+ Version: 1.2.0
4
+ Summary: Python SDK for DeFi Analytics, Simulation, and Agents
5
+ Home-page: http://github.com/defipy-devs/defipy
6
+ Author: icmoore
7
+ Author-email: defipy.devs@gmail.com
8
+ License: Apache-2.0
9
+ Description-Content-Type: text/markdown
10
+ License-File: LICENSE
11
+ License-File: NOTICE
12
+ Requires-Dist: scipy>=1.7.3
13
+ Requires-Dist: numpy>=1.21
14
+ Requires-Dist: gmpy2>=2.1
15
+ Requires-Dist: pandas>=1.3
16
+ Requires-Dist: pydantic>=2.11.0
17
+ Requires-Dist: attrs>=21.0
18
+ Requires-Dist: requests>=2.28
19
+ Requires-Dist: web3>=6.0
20
+ Requires-Dist: termcolor>=2.4.0
21
+ Requires-Dist: bokeh>=3.3
22
+ Requires-Dist: uniswappy>=1.7.7
23
+ Requires-Dist: balancerpy>=1.0.6
24
+ Requires-Dist: stableswappy>=1.0.5
25
+ Provides-Extra: book
26
+ Requires-Dist: web3scout>=0.2.0; extra == "book"
27
+ Dynamic: author
28
+ Dynamic: author-email
29
+ Dynamic: description
30
+ Dynamic: description-content-type
31
+ Dynamic: home-page
32
+ Dynamic: license
33
+ Dynamic: license-file
34
+ Dynamic: provides-extra
35
+ Dynamic: requires-dist
36
+ Dynamic: summary
37
+
38
+ # DeFiPy: Python SDK for DeFi Analytics and Agents
39
+
40
+ DeFiPy is the first unified Python SDK for DeFi analytics, simulation, and autonomous agents. Built with modularity in mind, DeFiPy lets you isolate and extend your analytics by protocol using:
41
+
42
+ * [UniswapPy](https://github.com/defipy-devs/uniswappy)
43
+ * [BalancerPy](https://github.com/defipy-devs/balancerpy)
44
+ * [StableSwapPy](https://github.com/defipy-devs/stableswappy)
45
+
46
+ For onchain event access and scripting, pair it with [Web3Scout](https://github.com/defipy-devs/web3scout) — a companion tool for [decoding pool events](https://defipy.readthedocs.io/en/latest/onchain/pool_events.html) and [interfacing with Solidity contracts](https://defipy.readthedocs.io/en/latest/onchain/testnet_sim_univ2.html). Whether you’re building dashboards, simulations, or agent-based trading systems, DeFiPy + Web3Scout deliver a uniquely powerful toolset — unlike anything else in the ecosystem.
47
+
48
+ 🔗 SPDX-Anchor: [anchorregistry.ai/AR-2026-YdPXB5g](https://anchorregistry.ai/AR-2026-YdPXB5g)
49
+
50
+ ## 📝 Docs
51
+ Visit [**DeFiPy docs**](https://defipy.org) for full documentation
52
+
53
+ ## 🔍 Install
54
+
55
+ DeFiPy requires **Python 3.10 or later**. Install via pip:
56
+
57
+ ```
58
+ > pip install defipy
59
+ ```
60
+
61
+ ### Book install (chapter 9 agents)
62
+
63
+ Chapter 9 of *Hands-On AMMs with Python* — *Building Autonomous DeFi Agents* — uses live chain integration via `web3scout`. To run those examples, install the `[book]` extra:
64
+
65
+ ```
66
+ > pip install defipy[book]
67
+ ```
68
+
69
+ This pulls in `web3scout` on top of the core install, enabling the chain event monitoring, ABI loading, and token-fetching utilities that chapter 9's agents require. Other chapters work with the core install alone.
70
+
71
+ ### Source install
72
+
73
+ To install from source:
74
+
75
+ ```
76
+ > git clone https://github.com/defipy-devs/defipy
77
+ > cd defipy
78
+ > pip install .
79
+ ```
80
+
81
+ ### System libraries for gmpy2
82
+
83
+ DeFiPy depends on `gmpy2` for high-precision arithmetic in StableSwap math. On most platforms, `pip` will install `gmpy2` from a prebuilt wheel and no further setup is needed. If the install fails, you may need the GMP, MPFR, and MPC system libraries installed *before* `pip install`:
84
+
85
+ **macOS (Homebrew):**
86
+ ```
87
+ > brew install gmp mpfr libmpc
88
+ ```
89
+
90
+ **Linux (Debian / Ubuntu):**
91
+ ```
92
+ > sudo apt install libgmp-dev libmpfr-dev libmpc-dev
93
+ ```
94
+
95
+ See the [gmpy2 installation docs](https://gmpy2.readthedocs.io/en/latest/install.html) for other platforms.
96
+
97
+ ## 🔍 Learning Resources
98
+
99
+ DeFiPy is accompanied by educational resources for developers and researchers
100
+ interested in on-chain analytics and DeFi modeling.
101
+
102
+ ### 📘 Textbook
103
+ **_DeFiPy: Python SDK for On-Chain Analytics_**
104
+
105
+ A comprehensive guide to DeFi analytics, AMM modeling, and simulation.
106
+
107
+ 🔗 **Buy on Amazon:** https://www.amazon.com/dp/B0G3RV5QRB
108
+
109
+ ### 🎓 Course
110
+ **On-Chain Analytics Foundations**
111
+
112
+ A practical course on transforming raw blockchain data into structured
113
+ analytics pipelines using Python.
114
+
115
+ Topics include:
116
+
117
+ - retrieving blockchain data via Ethereum RPC
118
+ - decoding event logs
119
+ - analyzing AMM swap events
120
+ - building DeFi analytics pipelines
121
+
122
+ 🔗 **Course Page:** https://defipy.thinkific.com/products/courses/foundations
123
+
124
+ ## 🚀 Quick Example (Uniswap V3)
125
+ --------------------------
126
+
127
+ To setup a liquidity pool, you must first create the tokens in the pair using the `ERC20` object. Next, create a liquidity pool (LP) factory using `IFactory` object. Once this is setup, an unlimited amount of LPs can be created; the procedures for such are as follows:
128
+
129
+ from defipy import *
130
+
131
+ # Step 1: Define tokens and parameters
132
+ eth = ERC20("ETH", "0x93")
133
+ tkn = ERC20("TKN", "0x111")
134
+ tick_spacing = 60
135
+ fee = 3000 # 0.3% fee tier
136
+
137
+ # Step 2: Set up exchange data for V3
138
+ exch_data = UniswapExchangeData(tkn0=eth, tkn1=tkn, symbol="LP", address="0x811", version='V3', tick_spacing=tick_spacing, fee=fee)
139
+
140
+ # Step 3: Initialize factory
141
+ factory = UniswapFactory("ETH pool factory", "0x2")
142
+
143
+ # Step 4: Deploy pool
144
+ lp = factory.deploy(exch_data)
145
+
146
+ # Step 5: Add initial liquidity within tick range
147
+ lwr_tick = UniV3Utils.getMinTick(tick_spacing)
148
+ upr_tick = UniV3Utils.getMaxTick(tick_spacing)
149
+ join = Join()
150
+ join.apply(lp, "user", 1000, 10000, lwr_tick, upr_tick)
151
+
152
+ # Step 6: Perform swap
153
+ swap = Swap()
154
+ out = swap.apply(lp, tkn, "user", 10)
155
+
156
+ # Check reserves and liquidity
157
+ lp.summary()
158
+
159
+ # OUTPUT:
160
+ Exchange ETH-TKN (LP)
161
+ Real Reserves: ETH = 999.0039930189599, TKN = 10010.0
162
+ Gross Liquidity: 3162.277660168379
163
+
164
+ ## License
165
+ Licensed under the Apache License, Version 2.0.
166
+ See [LICENSE](./LICENSE) and [NOTICE](./NOTICE) for details.
167
+ Portions of this project may include code from third-party projects under compatible open-source licenses.
@@ -31,6 +31,9 @@ python/prod/math/interest/ips/__init__.py
31
31
  python/prod/math/interest/ips/aggregate/__init__.py
32
32
  python/prod/math/model/__init__.py
33
33
  python/prod/math/risk/__init__.py
34
+ python/prod/primitives/__init__.py
35
+ python/prod/primitives/position/AnalyzePosition.py
36
+ python/prod/primitives/position/__init__.py
34
37
  python/prod/process/__init__.py
35
38
  python/prod/process/burn/__init__.py
36
39
  python/prod/process/deposit/__init__.py
@@ -45,6 +48,7 @@ python/prod/process/swap/__init__.py
45
48
  python/prod/utils/client/__init__.py
46
49
  python/prod/utils/client/contract/ExecuteScript.py
47
50
  python/prod/utils/client/contract/__init__.py
51
+ python/prod/utils/data/PositionAnalysis.py
48
52
  python/prod/utils/data/__init__.py
49
53
  python/prod/utils/interfaces/__init__.py
50
54
  python/prod/utils/tools/UniswapScriptHelper.py
@@ -0,0 +1,16 @@
1
+ scipy>=1.7.3
2
+ numpy>=1.21
3
+ gmpy2>=2.1
4
+ pandas>=1.3
5
+ pydantic>=2.11.0
6
+ attrs>=21.0
7
+ requests>=2.28
8
+ web3>=6.0
9
+ termcolor>=2.4.0
10
+ bokeh>=3.3
11
+ uniswappy>=1.7.7
12
+ balancerpy>=1.0.6
13
+ stableswappy>=1.0.5
14
+
15
+ [book]
16
+ web3scout>=0.2.0
defipy-1.2.0/PKG-INFO ADDED
@@ -0,0 +1,167 @@
1
+ Metadata-Version: 2.4
2
+ Name: DeFiPy
3
+ Version: 1.2.0
4
+ Summary: Python SDK for DeFi Analytics, Simulation, and Agents
5
+ Home-page: http://github.com/defipy-devs/defipy
6
+ Author: icmoore
7
+ Author-email: defipy.devs@gmail.com
8
+ License: Apache-2.0
9
+ Description-Content-Type: text/markdown
10
+ License-File: LICENSE
11
+ License-File: NOTICE
12
+ Requires-Dist: scipy>=1.7.3
13
+ Requires-Dist: numpy>=1.21
14
+ Requires-Dist: gmpy2>=2.1
15
+ Requires-Dist: pandas>=1.3
16
+ Requires-Dist: pydantic>=2.11.0
17
+ Requires-Dist: attrs>=21.0
18
+ Requires-Dist: requests>=2.28
19
+ Requires-Dist: web3>=6.0
20
+ Requires-Dist: termcolor>=2.4.0
21
+ Requires-Dist: bokeh>=3.3
22
+ Requires-Dist: uniswappy>=1.7.7
23
+ Requires-Dist: balancerpy>=1.0.6
24
+ Requires-Dist: stableswappy>=1.0.5
25
+ Provides-Extra: book
26
+ Requires-Dist: web3scout>=0.2.0; extra == "book"
27
+ Dynamic: author
28
+ Dynamic: author-email
29
+ Dynamic: description
30
+ Dynamic: description-content-type
31
+ Dynamic: home-page
32
+ Dynamic: license
33
+ Dynamic: license-file
34
+ Dynamic: provides-extra
35
+ Dynamic: requires-dist
36
+ Dynamic: summary
37
+
38
+ # DeFiPy: Python SDK for DeFi Analytics and Agents
39
+
40
+ DeFiPy is the first unified Python SDK for DeFi analytics, simulation, and autonomous agents. Built with modularity in mind, DeFiPy lets you isolate and extend your analytics by protocol using:
41
+
42
+ * [UniswapPy](https://github.com/defipy-devs/uniswappy)
43
+ * [BalancerPy](https://github.com/defipy-devs/balancerpy)
44
+ * [StableSwapPy](https://github.com/defipy-devs/stableswappy)
45
+
46
+ For onchain event access and scripting, pair it with [Web3Scout](https://github.com/defipy-devs/web3scout) — a companion tool for [decoding pool events](https://defipy.readthedocs.io/en/latest/onchain/pool_events.html) and [interfacing with Solidity contracts](https://defipy.readthedocs.io/en/latest/onchain/testnet_sim_univ2.html). Whether you’re building dashboards, simulations, or agent-based trading systems, DeFiPy + Web3Scout deliver a uniquely powerful toolset — unlike anything else in the ecosystem.
47
+
48
+ 🔗 SPDX-Anchor: [anchorregistry.ai/AR-2026-YdPXB5g](https://anchorregistry.ai/AR-2026-YdPXB5g)
49
+
50
+ ## 📝 Docs
51
+ Visit [**DeFiPy docs**](https://defipy.org) for full documentation
52
+
53
+ ## 🔍 Install
54
+
55
+ DeFiPy requires **Python 3.10 or later**. Install via pip:
56
+
57
+ ```
58
+ > pip install defipy
59
+ ```
60
+
61
+ ### Book install (chapter 9 agents)
62
+
63
+ Chapter 9 of *Hands-On AMMs with Python* — *Building Autonomous DeFi Agents* — uses live chain integration via `web3scout`. To run those examples, install the `[book]` extra:
64
+
65
+ ```
66
+ > pip install defipy[book]
67
+ ```
68
+
69
+ This pulls in `web3scout` on top of the core install, enabling the chain event monitoring, ABI loading, and token-fetching utilities that chapter 9's agents require. Other chapters work with the core install alone.
70
+
71
+ ### Source install
72
+
73
+ To install from source:
74
+
75
+ ```
76
+ > git clone https://github.com/defipy-devs/defipy
77
+ > cd defipy
78
+ > pip install .
79
+ ```
80
+
81
+ ### System libraries for gmpy2
82
+
83
+ DeFiPy depends on `gmpy2` for high-precision arithmetic in StableSwap math. On most platforms, `pip` will install `gmpy2` from a prebuilt wheel and no further setup is needed. If the install fails, you may need the GMP, MPFR, and MPC system libraries installed *before* `pip install`:
84
+
85
+ **macOS (Homebrew):**
86
+ ```
87
+ > brew install gmp mpfr libmpc
88
+ ```
89
+
90
+ **Linux (Debian / Ubuntu):**
91
+ ```
92
+ > sudo apt install libgmp-dev libmpfr-dev libmpc-dev
93
+ ```
94
+
95
+ See the [gmpy2 installation docs](https://gmpy2.readthedocs.io/en/latest/install.html) for other platforms.
96
+
97
+ ## 🔍 Learning Resources
98
+
99
+ DeFiPy is accompanied by educational resources for developers and researchers
100
+ interested in on-chain analytics and DeFi modeling.
101
+
102
+ ### 📘 Textbook
103
+ **_DeFiPy: Python SDK for On-Chain Analytics_**
104
+
105
+ A comprehensive guide to DeFi analytics, AMM modeling, and simulation.
106
+
107
+ 🔗 **Buy on Amazon:** https://www.amazon.com/dp/B0G3RV5QRB
108
+
109
+ ### 🎓 Course
110
+ **On-Chain Analytics Foundations**
111
+
112
+ A practical course on transforming raw blockchain data into structured
113
+ analytics pipelines using Python.
114
+
115
+ Topics include:
116
+
117
+ - retrieving blockchain data via Ethereum RPC
118
+ - decoding event logs
119
+ - analyzing AMM swap events
120
+ - building DeFi analytics pipelines
121
+
122
+ 🔗 **Course Page:** https://defipy.thinkific.com/products/courses/foundations
123
+
124
+ ## 🚀 Quick Example (Uniswap V3)
125
+ --------------------------
126
+
127
+ To setup a liquidity pool, you must first create the tokens in the pair using the `ERC20` object. Next, create a liquidity pool (LP) factory using `IFactory` object. Once this is setup, an unlimited amount of LPs can be created; the procedures for such are as follows:
128
+
129
+ from defipy import *
130
+
131
+ # Step 1: Define tokens and parameters
132
+ eth = ERC20("ETH", "0x93")
133
+ tkn = ERC20("TKN", "0x111")
134
+ tick_spacing = 60
135
+ fee = 3000 # 0.3% fee tier
136
+
137
+ # Step 2: Set up exchange data for V3
138
+ exch_data = UniswapExchangeData(tkn0=eth, tkn1=tkn, symbol="LP", address="0x811", version='V3', tick_spacing=tick_spacing, fee=fee)
139
+
140
+ # Step 3: Initialize factory
141
+ factory = UniswapFactory("ETH pool factory", "0x2")
142
+
143
+ # Step 4: Deploy pool
144
+ lp = factory.deploy(exch_data)
145
+
146
+ # Step 5: Add initial liquidity within tick range
147
+ lwr_tick = UniV3Utils.getMinTick(tick_spacing)
148
+ upr_tick = UniV3Utils.getMaxTick(tick_spacing)
149
+ join = Join()
150
+ join.apply(lp, "user", 1000, 10000, lwr_tick, upr_tick)
151
+
152
+ # Step 6: Perform swap
153
+ swap = Swap()
154
+ out = swap.apply(lp, tkn, "user", 10)
155
+
156
+ # Check reserves and liquidity
157
+ lp.summary()
158
+
159
+ # OUTPUT:
160
+ Exchange ETH-TKN (LP)
161
+ Real Reserves: ETH = 999.0039930189599, TKN = 10010.0
162
+ Gross Liquidity: 3162.277660168379
163
+
164
+ ## License
165
+ Licensed under the Apache License, Version 2.0.
166
+ See [LICENSE](./LICENSE) and [NOTICE](./NOTICE) for details.
167
+ Portions of this project may include code from third-party projects under compatible open-source licenses.
defipy-1.2.0/README.md ADDED
@@ -0,0 +1,130 @@
1
+ # DeFiPy: Python SDK for DeFi Analytics and Agents
2
+
3
+ DeFiPy is the first unified Python SDK for DeFi analytics, simulation, and autonomous agents. Built with modularity in mind, DeFiPy lets you isolate and extend your analytics by protocol using:
4
+
5
+ * [UniswapPy](https://github.com/defipy-devs/uniswappy)
6
+ * [BalancerPy](https://github.com/defipy-devs/balancerpy)
7
+ * [StableSwapPy](https://github.com/defipy-devs/stableswappy)
8
+
9
+ For onchain event access and scripting, pair it with [Web3Scout](https://github.com/defipy-devs/web3scout) — a companion tool for [decoding pool events](https://defipy.readthedocs.io/en/latest/onchain/pool_events.html) and [interfacing with Solidity contracts](https://defipy.readthedocs.io/en/latest/onchain/testnet_sim_univ2.html). Whether you’re building dashboards, simulations, or agent-based trading systems, DeFiPy + Web3Scout deliver a uniquely powerful toolset — unlike anything else in the ecosystem.
10
+
11
+ 🔗 SPDX-Anchor: [anchorregistry.ai/AR-2026-YdPXB5g](https://anchorregistry.ai/AR-2026-YdPXB5g)
12
+
13
+ ## 📝 Docs
14
+ Visit [**DeFiPy docs**](https://defipy.org) for full documentation
15
+
16
+ ## 🔍 Install
17
+
18
+ DeFiPy requires **Python 3.10 or later**. Install via pip:
19
+
20
+ ```
21
+ > pip install defipy
22
+ ```
23
+
24
+ ### Book install (chapter 9 agents)
25
+
26
+ Chapter 9 of *Hands-On AMMs with Python* — *Building Autonomous DeFi Agents* — uses live chain integration via `web3scout`. To run those examples, install the `[book]` extra:
27
+
28
+ ```
29
+ > pip install defipy[book]
30
+ ```
31
+
32
+ This pulls in `web3scout` on top of the core install, enabling the chain event monitoring, ABI loading, and token-fetching utilities that chapter 9's agents require. Other chapters work with the core install alone.
33
+
34
+ ### Source install
35
+
36
+ To install from source:
37
+
38
+ ```
39
+ > git clone https://github.com/defipy-devs/defipy
40
+ > cd defipy
41
+ > pip install .
42
+ ```
43
+
44
+ ### System libraries for gmpy2
45
+
46
+ DeFiPy depends on `gmpy2` for high-precision arithmetic in StableSwap math. On most platforms, `pip` will install `gmpy2` from a prebuilt wheel and no further setup is needed. If the install fails, you may need the GMP, MPFR, and MPC system libraries installed *before* `pip install`:
47
+
48
+ **macOS (Homebrew):**
49
+ ```
50
+ > brew install gmp mpfr libmpc
51
+ ```
52
+
53
+ **Linux (Debian / Ubuntu):**
54
+ ```
55
+ > sudo apt install libgmp-dev libmpfr-dev libmpc-dev
56
+ ```
57
+
58
+ See the [gmpy2 installation docs](https://gmpy2.readthedocs.io/en/latest/install.html) for other platforms.
59
+
60
+ ## 🔍 Learning Resources
61
+
62
+ DeFiPy is accompanied by educational resources for developers and researchers
63
+ interested in on-chain analytics and DeFi modeling.
64
+
65
+ ### 📘 Textbook
66
+ **_DeFiPy: Python SDK for On-Chain Analytics_**
67
+
68
+ A comprehensive guide to DeFi analytics, AMM modeling, and simulation.
69
+
70
+ 🔗 **Buy on Amazon:** https://www.amazon.com/dp/B0G3RV5QRB
71
+
72
+ ### 🎓 Course
73
+ **On-Chain Analytics Foundations**
74
+
75
+ A practical course on transforming raw blockchain data into structured
76
+ analytics pipelines using Python.
77
+
78
+ Topics include:
79
+
80
+ - retrieving blockchain data via Ethereum RPC
81
+ - decoding event logs
82
+ - analyzing AMM swap events
83
+ - building DeFi analytics pipelines
84
+
85
+ 🔗 **Course Page:** https://defipy.thinkific.com/products/courses/foundations
86
+
87
+ ## 🚀 Quick Example (Uniswap V3)
88
+ --------------------------
89
+
90
+ To setup a liquidity pool, you must first create the tokens in the pair using the `ERC20` object. Next, create a liquidity pool (LP) factory using `IFactory` object. Once this is setup, an unlimited amount of LPs can be created; the procedures for such are as follows:
91
+
92
+ from defipy import *
93
+
94
+ # Step 1: Define tokens and parameters
95
+ eth = ERC20("ETH", "0x93")
96
+ tkn = ERC20("TKN", "0x111")
97
+ tick_spacing = 60
98
+ fee = 3000 # 0.3% fee tier
99
+
100
+ # Step 2: Set up exchange data for V3
101
+ exch_data = UniswapExchangeData(tkn0=eth, tkn1=tkn, symbol="LP", address="0x811", version='V3', tick_spacing=tick_spacing, fee=fee)
102
+
103
+ # Step 3: Initialize factory
104
+ factory = UniswapFactory("ETH pool factory", "0x2")
105
+
106
+ # Step 4: Deploy pool
107
+ lp = factory.deploy(exch_data)
108
+
109
+ # Step 5: Add initial liquidity within tick range
110
+ lwr_tick = UniV3Utils.getMinTick(tick_spacing)
111
+ upr_tick = UniV3Utils.getMaxTick(tick_spacing)
112
+ join = Join()
113
+ join.apply(lp, "user", 1000, 10000, lwr_tick, upr_tick)
114
+
115
+ # Step 6: Perform swap
116
+ swap = Swap()
117
+ out = swap.apply(lp, tkn, "user", 10)
118
+
119
+ # Check reserves and liquidity
120
+ lp.summary()
121
+
122
+ # OUTPUT:
123
+ Exchange ETH-TKN (LP)
124
+ Real Reserves: ETH = 999.0039930189599, TKN = 10010.0
125
+ Gross Liquidity: 3162.277660168379
126
+
127
+ ## License
128
+ Licensed under the Apache License, Version 2.0.
129
+ See [LICENSE](./LICENSE) and [NOTICE](./NOTICE) for details.
130
+ Portions of this project may include code from third-party projects under compatible open-source licenses.
@@ -1,5 +1,3 @@
1
- # This file participates in a symbolic cognition substrate.
2
-
3
1
  from defipy.erc import *
4
2
  from defipy.math.basic import *
5
3
  from defipy.math.interest import *
@@ -21,9 +19,30 @@ from defipy.utils.data import *
21
19
  from defipy.utils.client import *
22
20
  from defipy.utils.client.contract import *
23
21
  from defipy.utils.tools import *
24
- from defipy.agents.config import *
25
- from defipy.agents.data import *
26
- from defipy.agents import *
22
+
23
+ # Agent modules require web3scout, available via the [book] extra.
24
+ # If web3scout isn't installed, skip agent imports so core defipy
25
+ # (primitives, math, analytics) remains usable.
26
+ try:
27
+ from defipy.agents.config import *
28
+ from defipy.agents.data import *
29
+ from defipy.agents import *
30
+ except ImportError as _agent_import_err:
31
+ if 'web3scout' in str(_agent_import_err):
32
+ import warnings as _warnings
33
+ _warnings.warn(
34
+ "defipy.agents requires web3scout. To enable agent support, "
35
+ "install with: pip install defipy[book]",
36
+ ImportWarning,
37
+ stacklevel=2,
38
+ )
39
+ del _warnings
40
+ else:
41
+ raise
42
+ del _agent_import_err
43
+
44
+ from defipy.primitives import *
45
+ from defipy.primitives.position import *
27
46
 
28
47
  from uniswappy.cpt.exchg import *
29
48
  from uniswappy.cpt.factory import *
@@ -168,10 +168,10 @@ class ImpermanentLossAgent:
168
168
  return position_value < threshold
169
169
 
170
170
  def withdraw_mock_position(self, lp, tkn, user_nm, lp_amt = None):
171
- assert self.mock_lp_pos_amt != None, 'TVLBasedLiquidityExitAgent: MOCK_POSITION_UNAVAILABLE'
171
+ assert self.mock_lp_pos_amt != None, 'ImpermanentLossAgent: MOCK_POSITION_UNAVAILABLE'
172
172
  lp_amt = self.mock_lp_pos_amt if lp_amt == None else lp_amt
173
- tkn_amt = LPQuote(False).get_amount_from_lp(lp, tkn0, lp_amt)
174
- amount_out = WithdrawSwap().apply(lp, tkn0, user_nm, tkn_amt)
173
+ tkn_amt = LPQuote(False).get_amount_from_lp(lp, tkn, lp_amt)
174
+ amount_out = WithdrawSwap().apply(lp, tkn, user_nm, tkn_amt)
175
175
  return amount_out
176
176
 
177
177
  def _init_lp_contract(self):
@@ -111,7 +111,7 @@ class PriceThresholdSwapAgent:
111
111
  out = Swap().apply(lp, tkn, "test_action", self.config.swap_amount)
112
112
  print(f"Block {block_num}: Swapped {self.config.swap_amount} {tkn0.token_name} for {out} {tkn1.token_name}")
113
113
  except Exception as e:
114
- print(f"Block {block_number}: Swap failed: {e}")
114
+ print(f"Block {block_num}: Swap failed: {e}")
115
115
 
116
116
  def get_token_price(self, tkn1_over_tkn0 = True, block_num = None):
117
117
 
@@ -93,8 +93,8 @@ class TVLBasedLiquidityExitAgent:
93
93
  def withdraw_mock_position(self, lp, tkn, user_nm, lp_amt = None):
94
94
  assert self.mock_lp_pos_amt != None, 'TVLBasedLiquidityExitAgent: MOCK_POSITION_UNAVAILABLE'
95
95
  lp_amt = self.mock_lp_pos_amt if lp_amt == None else lp_amt
96
- tkn_amt = LPQuote(False).get_amount_from_lp(lp, tkn0, lp_amt)
97
- amount_out = WithdrawSwap().apply(lp, tkn0, user_nm, tkn_amt)
96
+ tkn_amt = LPQuote(False).get_amount_from_lp(lp, tkn, lp_amt)
97
+ amount_out = WithdrawSwap().apply(lp, tkn, user_nm, tkn_amt)
98
98
  return amount_out
99
99
 
100
100
  def update_mock_pool(self, lp, cur_block):
@@ -149,10 +149,10 @@ class VolumeSpikeNotifierAgent:
149
149
  return self.mock_lp_pos_amt
150
150
 
151
151
  def withdraw_mock_position(self, lp, tkn, user_nm, lp_amt = None):
152
- assert self.mock_lp_pos_amt != None, 'TVLBasedLiquidityExitAgent: MOCK_POSITION_UNAVAILABLE'
152
+ assert self.mock_lp_pos_amt != None, 'VolumeSpikeNotifierAgent: MOCK_POSITION_UNAVAILABLE'
153
153
  lp_amt = self.mock_lp_pos_amt if lp_amt == None else lp_amt
154
- tkn_amt = LPQuote(False).get_amount_from_lp(lp, tkn0, lp_amt)
155
- amount_out = WithdrawSwap().apply(lp, tkn0, user_nm, tkn_amt)
154
+ tkn_amt = LPQuote(False).get_amount_from_lp(lp, tkn, lp_amt)
155
+ amount_out = WithdrawSwap().apply(lp, tkn, user_nm, tkn_amt)
156
156
  return amount_out
157
157
 
158
158
  def get_pool_volume(self, lp, tkn, block_num):
@@ -0,0 +1 @@
1
+ from .position import *