web3-agent-kit 0.3.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.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Maulana
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,333 @@
1
+ Metadata-Version: 2.4
2
+ Name: web3-agent-kit
3
+ Version: 0.3.0
4
+ Summary: Open-source framework for building autonomous AI agents that interact with blockchain networks
5
+ Author-email: Maulana <khasbim240803@gmail.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/ulsreall/web3-agent-kit
8
+ Project-URL: Repository, https://github.com/ulsreall/web3-agent-kit
9
+ Project-URL: Issues, https://github.com/ulsreall/web3-agent-kit/issues
10
+ Project-URL: Documentation, https://github.com/ulsreall/web3-agent-kit#readme
11
+ Keywords: web3,ai,agent,blockchain,defi,ethereum,uniswap,llm
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
20
+ Classifier: Topic :: Office/Business :: Financial
21
+ Requires-Python: >=3.10
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: web3>=6.0.0
25
+ Requires-Dist: eth-account>=0.10.0
26
+ Requires-Dist: python-dotenv>=1.0.0
27
+ Requires-Dist: requests>=2.31.0
28
+ Provides-Extra: dev
29
+ Requires-Dist: pytest>=7.0; extra == "dev"
30
+ Requires-Dist: pytest-cov>=4.0; extra == "dev"
31
+ Dynamic: license-file
32
+
33
+ # ๐Ÿค– Web3 Agent Kit
34
+
35
+ > Open-source framework for building autonomous AI agents that interact with blockchain networks.
36
+
37
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
38
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
39
+ [![CI](https://github.com/ulsreall/web3-agent-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/ulsreall/web3-agent-kit/actions)
40
+ [![Twitter](https://img.shields.io/twitter/follow/itseywacc?style=social)](https://twitter.com/itseywacc)
41
+
42
+ ---
43
+
44
+ ## What is this?
45
+
46
+ Web3 Agent Kit is a Python framework for building **AI agents that can autonomously interact with DeFi protocols**, manage wallets, execute trades, and perform complex on-chain operations across multiple blockchains.
47
+
48
+ ```python
49
+ from web3_agent_kit import Agent, Wallet, Chain
50
+ from web3_agent_kit.defi import Uniswap
51
+
52
+ agent = Agent(
53
+ wallet=Wallet.from_env("PRIVATE_KEY"),
54
+ chains=[Chain.BASE],
55
+ tools=[Uniswap()],
56
+ )
57
+
58
+ # Agent uses LLM reasoning to execute natural language goals
59
+ result = agent.run("Swap 0.1 ETH to USDC on Base")
60
+ ```
61
+
62
+ ---
63
+
64
+ ## โœจ Features
65
+
66
+ ### ๐Ÿค– Core
67
+ - ๐Ÿ”— **Multi-chain support** โ€” Ethereum, Base, Arbitrum, Optimism, Polygon, Avalanche, BSC
68
+ - ๐Ÿง  **LLM-powered reasoning** โ€” Multi-provider cascade (OpenAI, Anthropic, Groq, DeepSeek, OpenRouter, Kimi)
69
+ - ๐ŸŽฏ **Natural language goals** โ€” Tell the agent what to do in plain English
70
+ - ๐Ÿ” **Governed signing** โ€” Safety caps, kill-switch, operator confirmation
71
+
72
+ ### ๐Ÿ’ฐ DeFi
73
+ - ๐Ÿ’ฑ **Uniswap V2 swaps** โ€” Actual token swaps with quotes, approvals, slippage protection
74
+ - ๐ŸŒ‰ **Cross-chain bridges** โ€” Li.Fi + Socket aggregators for best routes
75
+ - ๐Ÿ“Š **Portfolio tracking** โ€” Real-time balances, P&L across all chains
76
+
77
+ ### ๐Ÿ”ซ Sniper
78
+ - ๐ŸŽฏ **Token sniper** โ€” Monitor new liquidity pools, auto-buy safe tokens
79
+ - ๐Ÿ›ก๏ธ **Risk assessment** โ€” Honeypot detection, liquidity checks, contract analysis
80
+ - โšก **Live monitoring** โ€” Background thread with callback alerts
81
+
82
+ ---
83
+
84
+ ## ๐Ÿš€ Quick Start
85
+
86
+ ### Install
87
+
88
+ ```bash
89
+ pip install web3-agent-kit
90
+ ```
91
+
92
+ ### Environment Variables
93
+
94
+ ```bash
95
+ # Required: Wallet
96
+ export PRIVATE_KEY="0x..."
97
+
98
+ # Required: At least one LLM provider
99
+ export OPENAI_API_KEY="sk-..." # OpenAI
100
+ export ANTHROPIC_API_KEY="sk-ant-..." # Anthropic (best reasoning)
101
+ export GROQ_API_KEY="gsk_..." # Groq (fastest)
102
+ export DEEPSEEK_API_KEY="sk-..." # DeepSeek (cheapest)
103
+
104
+ # Optional: Custom RPC endpoints
105
+ export ETH_RPC="https://..."
106
+ export BASE_RPC="https://..."
107
+ ```
108
+
109
+ ### Basic Usage
110
+
111
+ ```python
112
+ from web3_agent_kit import Agent, Wallet, Chain, ChainManager
113
+ from web3_agent_kit.defi import Uniswap
114
+
115
+ # Setup
116
+ chain_manager = ChainManager(chains=[Chain.BASE])
117
+ wallet = Wallet.from_env("PRIVATE_KEY", chain_manager=chain_manager)
118
+ uniswap = Uniswap(chain_manager=chain_manager)
119
+
120
+ # Create agent with LLM reasoning
121
+ agent = Agent(
122
+ wallet=wallet,
123
+ chains=[Chain.BASE],
124
+ tools=[uniswap],
125
+ )
126
+
127
+ # Natural language swap
128
+ result = agent.run("Swap 0.1 ETH to USDC on Base")
129
+ print(result)
130
+ ```
131
+
132
+ ---
133
+
134
+ ## ๐Ÿ“ฆ Examples
135
+
136
+ | Example | Description |
137
+ |---------|-------------|
138
+ | `examples/llm_swap_agent.py` | LLM-powered natural language swapping |
139
+ | `examples/direct_swap.py` | Programmatic Uniswap swap without LLM |
140
+ | `examples/token_sniper.py` | Monitor new pairs, auto-buy safe tokens |
141
+ | `examples/portfolio_dashboard.py` | Real-time portfolio across chains |
142
+ | `examples/bridge_agent.py` | Cross-chain transfers via Li.Fi/Socket |
143
+ | `examples/swap_agent.py` | Autonomous token swapping |
144
+ | `examples/yield_optimizer.py` | Cross-chain yield farming |
145
+ | `examples/airdrop_farmer.py` | Multi-chain airdrop farming |
146
+ | `examples/sniper_bot.py` | Token launch sniper |
147
+ | `examples/portfolio_tracker.py` | Portfolio tracking & reporting |
148
+
149
+ ---
150
+
151
+ ## ๐Ÿง  LLM Integration
152
+
153
+ Multi-provider cascade with automatic fallback:
154
+
155
+ ```python
156
+ from web3_agent_kit.llm import LLM
157
+
158
+ # Auto-detect from environment variables
159
+ llm = LLM()
160
+
161
+ # Cascade order: Anthropic โ†’ Kimi โ†’ OpenRouter โ†’ DeepSeek โ†’ Groq โ†’ OpenAI
162
+
163
+ # Simple chat
164
+ response = llm.chat("What is the best yield on Base?")
165
+
166
+ # JSON response
167
+ data = llm.chat_json("Analyze this swap: 0.1 ETH to USDC")
168
+ ```
169
+
170
+ **Supported providers:**
171
+ - **Anthropic** (Claude) โ€” Best reasoning
172
+ - **OpenAI** (GPT-4) โ€” General purpose
173
+ - **Groq** (Llama) โ€” Fastest inference
174
+ - **DeepSeek** โ€” Cheapest
175
+ - **OpenRouter** โ€” Multi-model fallback
176
+ - **Kimi** โ€” Long context
177
+
178
+ ---
179
+
180
+ ## ๐Ÿ”ซ Token Sniper
181
+
182
+ Monitor new liquidity pools and auto-buy safe tokens:
183
+
184
+ ```python
185
+ from web3_agent_kit import TokenSniper, SniperConfig, RiskLevel
186
+
187
+ config = SniperConfig(
188
+ max_buy=0.005, # max 0.005 ETH per snipe
189
+ auto_buy=True, # auto-buy safe tokens
190
+ honeypot_check=True, # check if token is honeypot
191
+ min_liquidity=0.5, # min 0.5 ETH liquidity
192
+ )
193
+
194
+ sniper = TokenSniper(chain_manager, wallet, config, uniswap=uniswap)
195
+
196
+ # Scan recent blocks
197
+ pairs = sniper.scan_recent_blocks(num_blocks=100, chain=Chain.BASE)
198
+
199
+ # Or start live monitoring
200
+ sniper.start(chain=Chain.BASE, poll_interval=12)
201
+ ```
202
+
203
+ ---
204
+
205
+ ## ๐Ÿ“Š Portfolio Dashboard
206
+
207
+ Track balances and P&L across chains:
208
+
209
+ ```python
210
+ from web3_agent_kit import PortfolioTracker
211
+
212
+ tracker = PortfolioTracker(chain_manager, wallet)
213
+ summary = tracker.get_summary()
214
+
215
+ print(summary)
216
+ # ๐Ÿ“Š Portfolio: 0x1234...
217
+ # ๐Ÿ’ฐ Total Value: $12,345.67
218
+ #
219
+ # ๐Ÿ”— ETHEREUM: $8,000.00
220
+ # Native: 1.5000 ETH ($5,250.00)
221
+ # USDC: 2750.0000 ($2,750.00)
222
+ #
223
+ # ๐Ÿ”— BASE: $4,345.67
224
+ # Native: 1.2000 ETH ($4,200.00)
225
+ # USDC: 145.6700 ($145.67)
226
+ ```
227
+
228
+ ---
229
+
230
+ ## ๐ŸŒ‰ Bridge Agent
231
+
232
+ Cross-chain transfers via Li.Fi and Socket:
233
+
234
+ ```python
235
+ from web3_agent_kit import BridgeAgent
236
+
237
+ bridge = BridgeAgent(chain_manager, wallet)
238
+
239
+ # Get best routes
240
+ routes = bridge.get_routes("ETH", 0.1, Chain.ETHEREUM, Chain.BASE)
241
+
242
+ for route in routes:
243
+ print(f"{route.bridge_name}: {route.amount_out:.6f} ETH (fee: ${route.fee_usd:.2f})")
244
+
245
+ # Execute transfer
246
+ result = bridge.transfer("ETH", 0.1, Chain.ETHEREUM, Chain.BASE)
247
+ print(f"TX: {result.tx_hash}")
248
+ ```
249
+
250
+ ---
251
+
252
+ ## ๐Ÿ—๏ธ Architecture
253
+
254
+ ```
255
+ web3-agent-kit/
256
+ โ”œโ”€โ”€ src/
257
+ โ”‚ โ”œโ”€โ”€ __init__.py # Package exports
258
+ โ”‚ โ”œโ”€โ”€ agent.py # Agent framework + LLM reasoning
259
+ โ”‚ โ”œโ”€โ”€ llm.py # Multi-provider LLM client
260
+ โ”‚ โ”œโ”€โ”€ wallet.py # Wallet management + signing
261
+ โ”‚ โ”œโ”€โ”€ chain.py # Multi-chain RPC + config
262
+ โ”‚ โ”œโ”€โ”€ sniper.py # Token sniper + monitoring
263
+ โ”‚ โ”œโ”€โ”€ portfolio.py # Portfolio tracking + P&L
264
+ โ”‚ โ”œโ”€โ”€ bridge.py # Cross-chain bridge agent
265
+ โ”‚ โ””โ”€โ”€ defi/
266
+ โ”‚ โ”œโ”€โ”€ __init__.py # Uniswap, Aerodrome, Aave, Curve
267
+ โ”œโ”€โ”€ examples/ # Ready-to-use examples
268
+ โ”œโ”€โ”€ tests/ # Test suite
269
+ โ””โ”€โ”€ docs/ # Documentation
270
+ ```
271
+
272
+ ---
273
+
274
+ ## ๐Ÿ” Safety
275
+
276
+ Web3 Agent Kit includes built-in safety features:
277
+
278
+ ```python
279
+ from web3_agent_kit.safety import SpendGovernor, SpendLimits
280
+
281
+ governor = SpendGovernor(
282
+ limits=SpendLimits(
283
+ max_per_tx=0.1, # max 0.1 ETH per transaction
284
+ daily_limit=1.0, # max 1 ETH per day
285
+ ),
286
+ require_confirm=True, # operator must confirm
287
+ )
288
+
289
+ # Kill switch for emergencies
290
+ governor.kill() # blocks all transactions
291
+ governor.unkill() # resume
292
+ ```
293
+
294
+ ---
295
+
296
+ ## ๐Ÿ› ๏ธ Supported Chains
297
+
298
+ | Chain | Status | Uniswap | Bridge |
299
+ |-------|--------|---------|--------|
300
+ | Ethereum | โœ… | โœ… | โœ… |
301
+ | Base | โœ… | โœ… | โœ… |
302
+ | Arbitrum | โœ… | โœ… | โœ… |
303
+ | Optimism | โœ… | โœ… | โœ… |
304
+ | Polygon | โœ… | โœ… | โœ… |
305
+ | Avalanche | โœ… | โ€” | โœ… |
306
+ | BSC | โœ… | โ€” | โœ… |
307
+ | Solana | ๐Ÿ”œ | โ€” | โ€” |
308
+
309
+ ---
310
+
311
+ ## ๐Ÿค Contributing
312
+
313
+ We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
314
+
315
+ ---
316
+
317
+ ## ๐Ÿ“„ License
318
+
319
+ MIT License โ€” see [LICENSE](LICENSE) for details.
320
+
321
+ ---
322
+
323
+ ## ๐Ÿ™ Acknowledgments
324
+
325
+ Built with:
326
+ - [web3.py](https://github.com/ethereum/web3.py) โ€” Ethereum interactions
327
+ - [OpenAI](https://openai.com) / [Anthropic](https://anthropic.com) / [Groq](https://groq.com) โ€” LLM providers
328
+ - [Uniswap](https://uniswap.org) โ€” DEX protocol
329
+ - [Li.Fi](https://li.fi) / [Socket](https://socket.tech) โ€” Bridge aggregators
330
+
331
+ ---
332
+
333
+ **Built by [Maulana](https://github.com/ulsreall)** ยท [Twitter](https://twitter.com/itseywacc)
@@ -0,0 +1,301 @@
1
+ # ๐Ÿค– Web3 Agent Kit
2
+
3
+ > Open-source framework for building autonomous AI agents that interact with blockchain networks.
4
+
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
6
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
7
+ [![CI](https://github.com/ulsreall/web3-agent-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/ulsreall/web3-agent-kit/actions)
8
+ [![Twitter](https://img.shields.io/twitter/follow/itseywacc?style=social)](https://twitter.com/itseywacc)
9
+
10
+ ---
11
+
12
+ ## What is this?
13
+
14
+ Web3 Agent Kit is a Python framework for building **AI agents that can autonomously interact with DeFi protocols**, manage wallets, execute trades, and perform complex on-chain operations across multiple blockchains.
15
+
16
+ ```python
17
+ from web3_agent_kit import Agent, Wallet, Chain
18
+ from web3_agent_kit.defi import Uniswap
19
+
20
+ agent = Agent(
21
+ wallet=Wallet.from_env("PRIVATE_KEY"),
22
+ chains=[Chain.BASE],
23
+ tools=[Uniswap()],
24
+ )
25
+
26
+ # Agent uses LLM reasoning to execute natural language goals
27
+ result = agent.run("Swap 0.1 ETH to USDC on Base")
28
+ ```
29
+
30
+ ---
31
+
32
+ ## โœจ Features
33
+
34
+ ### ๐Ÿค– Core
35
+ - ๐Ÿ”— **Multi-chain support** โ€” Ethereum, Base, Arbitrum, Optimism, Polygon, Avalanche, BSC
36
+ - ๐Ÿง  **LLM-powered reasoning** โ€” Multi-provider cascade (OpenAI, Anthropic, Groq, DeepSeek, OpenRouter, Kimi)
37
+ - ๐ŸŽฏ **Natural language goals** โ€” Tell the agent what to do in plain English
38
+ - ๐Ÿ” **Governed signing** โ€” Safety caps, kill-switch, operator confirmation
39
+
40
+ ### ๐Ÿ’ฐ DeFi
41
+ - ๐Ÿ’ฑ **Uniswap V2 swaps** โ€” Actual token swaps with quotes, approvals, slippage protection
42
+ - ๐ŸŒ‰ **Cross-chain bridges** โ€” Li.Fi + Socket aggregators for best routes
43
+ - ๐Ÿ“Š **Portfolio tracking** โ€” Real-time balances, P&L across all chains
44
+
45
+ ### ๐Ÿ”ซ Sniper
46
+ - ๐ŸŽฏ **Token sniper** โ€” Monitor new liquidity pools, auto-buy safe tokens
47
+ - ๐Ÿ›ก๏ธ **Risk assessment** โ€” Honeypot detection, liquidity checks, contract analysis
48
+ - โšก **Live monitoring** โ€” Background thread with callback alerts
49
+
50
+ ---
51
+
52
+ ## ๐Ÿš€ Quick Start
53
+
54
+ ### Install
55
+
56
+ ```bash
57
+ pip install web3-agent-kit
58
+ ```
59
+
60
+ ### Environment Variables
61
+
62
+ ```bash
63
+ # Required: Wallet
64
+ export PRIVATE_KEY="0x..."
65
+
66
+ # Required: At least one LLM provider
67
+ export OPENAI_API_KEY="sk-..." # OpenAI
68
+ export ANTHROPIC_API_KEY="sk-ant-..." # Anthropic (best reasoning)
69
+ export GROQ_API_KEY="gsk_..." # Groq (fastest)
70
+ export DEEPSEEK_API_KEY="sk-..." # DeepSeek (cheapest)
71
+
72
+ # Optional: Custom RPC endpoints
73
+ export ETH_RPC="https://..."
74
+ export BASE_RPC="https://..."
75
+ ```
76
+
77
+ ### Basic Usage
78
+
79
+ ```python
80
+ from web3_agent_kit import Agent, Wallet, Chain, ChainManager
81
+ from web3_agent_kit.defi import Uniswap
82
+
83
+ # Setup
84
+ chain_manager = ChainManager(chains=[Chain.BASE])
85
+ wallet = Wallet.from_env("PRIVATE_KEY", chain_manager=chain_manager)
86
+ uniswap = Uniswap(chain_manager=chain_manager)
87
+
88
+ # Create agent with LLM reasoning
89
+ agent = Agent(
90
+ wallet=wallet,
91
+ chains=[Chain.BASE],
92
+ tools=[uniswap],
93
+ )
94
+
95
+ # Natural language swap
96
+ result = agent.run("Swap 0.1 ETH to USDC on Base")
97
+ print(result)
98
+ ```
99
+
100
+ ---
101
+
102
+ ## ๐Ÿ“ฆ Examples
103
+
104
+ | Example | Description |
105
+ |---------|-------------|
106
+ | `examples/llm_swap_agent.py` | LLM-powered natural language swapping |
107
+ | `examples/direct_swap.py` | Programmatic Uniswap swap without LLM |
108
+ | `examples/token_sniper.py` | Monitor new pairs, auto-buy safe tokens |
109
+ | `examples/portfolio_dashboard.py` | Real-time portfolio across chains |
110
+ | `examples/bridge_agent.py` | Cross-chain transfers via Li.Fi/Socket |
111
+ | `examples/swap_agent.py` | Autonomous token swapping |
112
+ | `examples/yield_optimizer.py` | Cross-chain yield farming |
113
+ | `examples/airdrop_farmer.py` | Multi-chain airdrop farming |
114
+ | `examples/sniper_bot.py` | Token launch sniper |
115
+ | `examples/portfolio_tracker.py` | Portfolio tracking & reporting |
116
+
117
+ ---
118
+
119
+ ## ๐Ÿง  LLM Integration
120
+
121
+ Multi-provider cascade with automatic fallback:
122
+
123
+ ```python
124
+ from web3_agent_kit.llm import LLM
125
+
126
+ # Auto-detect from environment variables
127
+ llm = LLM()
128
+
129
+ # Cascade order: Anthropic โ†’ Kimi โ†’ OpenRouter โ†’ DeepSeek โ†’ Groq โ†’ OpenAI
130
+
131
+ # Simple chat
132
+ response = llm.chat("What is the best yield on Base?")
133
+
134
+ # JSON response
135
+ data = llm.chat_json("Analyze this swap: 0.1 ETH to USDC")
136
+ ```
137
+
138
+ **Supported providers:**
139
+ - **Anthropic** (Claude) โ€” Best reasoning
140
+ - **OpenAI** (GPT-4) โ€” General purpose
141
+ - **Groq** (Llama) โ€” Fastest inference
142
+ - **DeepSeek** โ€” Cheapest
143
+ - **OpenRouter** โ€” Multi-model fallback
144
+ - **Kimi** โ€” Long context
145
+
146
+ ---
147
+
148
+ ## ๐Ÿ”ซ Token Sniper
149
+
150
+ Monitor new liquidity pools and auto-buy safe tokens:
151
+
152
+ ```python
153
+ from web3_agent_kit import TokenSniper, SniperConfig, RiskLevel
154
+
155
+ config = SniperConfig(
156
+ max_buy=0.005, # max 0.005 ETH per snipe
157
+ auto_buy=True, # auto-buy safe tokens
158
+ honeypot_check=True, # check if token is honeypot
159
+ min_liquidity=0.5, # min 0.5 ETH liquidity
160
+ )
161
+
162
+ sniper = TokenSniper(chain_manager, wallet, config, uniswap=uniswap)
163
+
164
+ # Scan recent blocks
165
+ pairs = sniper.scan_recent_blocks(num_blocks=100, chain=Chain.BASE)
166
+
167
+ # Or start live monitoring
168
+ sniper.start(chain=Chain.BASE, poll_interval=12)
169
+ ```
170
+
171
+ ---
172
+
173
+ ## ๐Ÿ“Š Portfolio Dashboard
174
+
175
+ Track balances and P&L across chains:
176
+
177
+ ```python
178
+ from web3_agent_kit import PortfolioTracker
179
+
180
+ tracker = PortfolioTracker(chain_manager, wallet)
181
+ summary = tracker.get_summary()
182
+
183
+ print(summary)
184
+ # ๐Ÿ“Š Portfolio: 0x1234...
185
+ # ๐Ÿ’ฐ Total Value: $12,345.67
186
+ #
187
+ # ๐Ÿ”— ETHEREUM: $8,000.00
188
+ # Native: 1.5000 ETH ($5,250.00)
189
+ # USDC: 2750.0000 ($2,750.00)
190
+ #
191
+ # ๐Ÿ”— BASE: $4,345.67
192
+ # Native: 1.2000 ETH ($4,200.00)
193
+ # USDC: 145.6700 ($145.67)
194
+ ```
195
+
196
+ ---
197
+
198
+ ## ๐ŸŒ‰ Bridge Agent
199
+
200
+ Cross-chain transfers via Li.Fi and Socket:
201
+
202
+ ```python
203
+ from web3_agent_kit import BridgeAgent
204
+
205
+ bridge = BridgeAgent(chain_manager, wallet)
206
+
207
+ # Get best routes
208
+ routes = bridge.get_routes("ETH", 0.1, Chain.ETHEREUM, Chain.BASE)
209
+
210
+ for route in routes:
211
+ print(f"{route.bridge_name}: {route.amount_out:.6f} ETH (fee: ${route.fee_usd:.2f})")
212
+
213
+ # Execute transfer
214
+ result = bridge.transfer("ETH", 0.1, Chain.ETHEREUM, Chain.BASE)
215
+ print(f"TX: {result.tx_hash}")
216
+ ```
217
+
218
+ ---
219
+
220
+ ## ๐Ÿ—๏ธ Architecture
221
+
222
+ ```
223
+ web3-agent-kit/
224
+ โ”œโ”€โ”€ src/
225
+ โ”‚ โ”œโ”€โ”€ __init__.py # Package exports
226
+ โ”‚ โ”œโ”€โ”€ agent.py # Agent framework + LLM reasoning
227
+ โ”‚ โ”œโ”€โ”€ llm.py # Multi-provider LLM client
228
+ โ”‚ โ”œโ”€โ”€ wallet.py # Wallet management + signing
229
+ โ”‚ โ”œโ”€โ”€ chain.py # Multi-chain RPC + config
230
+ โ”‚ โ”œโ”€โ”€ sniper.py # Token sniper + monitoring
231
+ โ”‚ โ”œโ”€โ”€ portfolio.py # Portfolio tracking + P&L
232
+ โ”‚ โ”œโ”€โ”€ bridge.py # Cross-chain bridge agent
233
+ โ”‚ โ””โ”€โ”€ defi/
234
+ โ”‚ โ”œโ”€โ”€ __init__.py # Uniswap, Aerodrome, Aave, Curve
235
+ โ”œโ”€โ”€ examples/ # Ready-to-use examples
236
+ โ”œโ”€โ”€ tests/ # Test suite
237
+ โ””โ”€โ”€ docs/ # Documentation
238
+ ```
239
+
240
+ ---
241
+
242
+ ## ๐Ÿ” Safety
243
+
244
+ Web3 Agent Kit includes built-in safety features:
245
+
246
+ ```python
247
+ from web3_agent_kit.safety import SpendGovernor, SpendLimits
248
+
249
+ governor = SpendGovernor(
250
+ limits=SpendLimits(
251
+ max_per_tx=0.1, # max 0.1 ETH per transaction
252
+ daily_limit=1.0, # max 1 ETH per day
253
+ ),
254
+ require_confirm=True, # operator must confirm
255
+ )
256
+
257
+ # Kill switch for emergencies
258
+ governor.kill() # blocks all transactions
259
+ governor.unkill() # resume
260
+ ```
261
+
262
+ ---
263
+
264
+ ## ๐Ÿ› ๏ธ Supported Chains
265
+
266
+ | Chain | Status | Uniswap | Bridge |
267
+ |-------|--------|---------|--------|
268
+ | Ethereum | โœ… | โœ… | โœ… |
269
+ | Base | โœ… | โœ… | โœ… |
270
+ | Arbitrum | โœ… | โœ… | โœ… |
271
+ | Optimism | โœ… | โœ… | โœ… |
272
+ | Polygon | โœ… | โœ… | โœ… |
273
+ | Avalanche | โœ… | โ€” | โœ… |
274
+ | BSC | โœ… | โ€” | โœ… |
275
+ | Solana | ๐Ÿ”œ | โ€” | โ€” |
276
+
277
+ ---
278
+
279
+ ## ๐Ÿค Contributing
280
+
281
+ We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
282
+
283
+ ---
284
+
285
+ ## ๐Ÿ“„ License
286
+
287
+ MIT License โ€” see [LICENSE](LICENSE) for details.
288
+
289
+ ---
290
+
291
+ ## ๐Ÿ™ Acknowledgments
292
+
293
+ Built with:
294
+ - [web3.py](https://github.com/ethereum/web3.py) โ€” Ethereum interactions
295
+ - [OpenAI](https://openai.com) / [Anthropic](https://anthropic.com) / [Groq](https://groq.com) โ€” LLM providers
296
+ - [Uniswap](https://uniswap.org) โ€” DEX protocol
297
+ - [Li.Fi](https://li.fi) / [Socket](https://socket.tech) โ€” Bridge aggregators
298
+
299
+ ---
300
+
301
+ **Built by [Maulana](https://github.com/ulsreall)** ยท [Twitter](https://twitter.com/itseywacc)
@@ -0,0 +1,48 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68.0", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "web3-agent-kit"
7
+ version = "0.3.0"
8
+ description = "Open-source framework for building autonomous AI agents that interact with blockchain networks"
9
+ readme = "README.md"
10
+ license = {text = "MIT"}
11
+ requires-python = ">=3.10"
12
+ authors = [
13
+ {name = "Maulana", email = "khasbim240803@gmail.com"},
14
+ ]
15
+ keywords = ["web3", "ai", "agent", "blockchain", "defi", "ethereum", "uniswap", "llm"]
16
+ classifiers = [
17
+ "Development Status :: 4 - Beta",
18
+ "Intended Audience :: Developers",
19
+ "License :: OSI Approved :: MIT License",
20
+ "Programming Language :: Python :: 3",
21
+ "Programming Language :: Python :: 3.10",
22
+ "Programming Language :: Python :: 3.11",
23
+ "Programming Language :: Python :: 3.12",
24
+ "Topic :: Software Development :: Libraries :: Python Modules",
25
+ "Topic :: Office/Business :: Financial",
26
+ ]
27
+ dependencies = [
28
+ "web3>=6.0.0",
29
+ "eth-account>=0.10.0",
30
+ "python-dotenv>=1.0.0",
31
+ "requests>=2.31.0",
32
+ ]
33
+
34
+ [project.optional-dependencies]
35
+ dev = [
36
+ "pytest>=7.0",
37
+ "pytest-cov>=4.0",
38
+ ]
39
+
40
+ [project.urls]
41
+ Homepage = "https://github.com/ulsreall/web3-agent-kit"
42
+ Repository = "https://github.com/ulsreall/web3-agent-kit"
43
+ Issues = "https://github.com/ulsreall/web3-agent-kit/issues"
44
+ Documentation = "https://github.com/ulsreall/web3-agent-kit#readme"
45
+
46
+ [tool.setuptools.packages.find]
47
+ where = ["."]
48
+ include = ["src*"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+