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.
- web3_agent_kit-0.3.0/LICENSE +21 -0
- web3_agent_kit-0.3.0/PKG-INFO +333 -0
- web3_agent_kit-0.3.0/README.md +301 -0
- web3_agent_kit-0.3.0/pyproject.toml +48 -0
- web3_agent_kit-0.3.0/setup.cfg +4 -0
- web3_agent_kit-0.3.0/setup.py +4 -0
- web3_agent_kit-0.3.0/src/__init__.py +33 -0
- web3_agent_kit-0.3.0/src/agent.py +239 -0
- web3_agent_kit-0.3.0/src/bridge.py +504 -0
- web3_agent_kit-0.3.0/src/chain.py +115 -0
- web3_agent_kit-0.3.0/src/defi/__init__.py +476 -0
- web3_agent_kit-0.3.0/src/llm.py +272 -0
- web3_agent_kit-0.3.0/src/portfolio.py +326 -0
- web3_agent_kit-0.3.0/src/sniper.py +511 -0
- web3_agent_kit-0.3.0/src/utils/__init__.py +140 -0
- web3_agent_kit-0.3.0/src/wallet.py +128 -0
- web3_agent_kit-0.3.0/tests/test_core.py +112 -0
- web3_agent_kit-0.3.0/web3_agent_kit.egg-info/PKG-INFO +333 -0
- web3_agent_kit-0.3.0/web3_agent_kit.egg-info/SOURCES.txt +20 -0
- web3_agent_kit-0.3.0/web3_agent_kit.egg-info/dependency_links.txt +1 -0
- web3_agent_kit-0.3.0/web3_agent_kit.egg-info/requires.txt +8 -0
- web3_agent_kit-0.3.0/web3_agent_kit.egg-info/top_level.txt +1 -0
|
@@ -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)
|
|
38
|
+
[](https://www.python.org/downloads/)
|
|
39
|
+
[](https://github.com/ulsreall/web3-agent-kit/actions)
|
|
40
|
+
[](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)
|
|
6
|
+
[](https://www.python.org/downloads/)
|
|
7
|
+
[](https://github.com/ulsreall/web3-agent-kit/actions)
|
|
8
|
+
[](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*"]
|