starkfi 0.5.0 → 0.6.0
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.
- package/MCP.md +171 -28
- package/README.md +190 -112
- package/dist/index.js +245 -156
- package/package.json +11 -5
- package/skills/README.md +11 -3
- package/skills/balance/SKILL.md +2 -0
- package/skills/batch/SKILL.md +46 -13
- package/skills/confidential/SKILL.md +183 -0
- package/skills/config/SKILL.md +6 -4
- package/skills/dca/SKILL.md +133 -0
- package/skills/lending/SKILL.md +17 -12
- package/skills/multi-swap/SKILL.md +14 -11
- package/skills/portfolio/SKILL.md +3 -2
- package/skills/send/SKILL.md +1 -0
- package/skills/trade/SKILL.md +22 -18
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
</p>
|
|
6
6
|
|
|
7
7
|
<p align="center">
|
|
8
|
-
A production-grade CLI, MCP server, and Telegram bot that gives both developers and AI agents full access to swaps, multi-swap, atomic batch transactions, staking, lending, portfolio management, and gasless transactions — all powered by the <a href="https://github.com/keep-starknet-strange/starkzap">Starkzap SDK</a>.
|
|
8
|
+
A production-grade CLI, MCP server, and Telegram bot that gives both developers and AI agents full access to swaps, multi-swap, atomic batch transactions, staking, lending, DCA (Dollar-Cost Averaging), confidential transfers, portfolio management, and gasless transactions — all powered by the <a href="https://github.com/keep-starknet-strange/starkzap">Starkzap SDK</a>.
|
|
9
9
|
</p>
|
|
10
10
|
|
|
11
11
|
<p align="center">
|
|
@@ -23,7 +23,7 @@ npx starkfi@latest --help
|
|
|
23
23
|
|
|
24
24
|
Most DeFi tools are built for humans clicking buttons. StarkFi is built for **agents**.
|
|
25
25
|
|
|
26
|
-
- 🤖 **
|
|
26
|
+
- 🤖 **42 MCP tools** — Any AI assistant (Cursor, Claude, Antigravity) can execute DeFi operations autonomously
|
|
27
27
|
- ⚡ **Atomic Batching** — Combine swap + stake + lend + send into a single multicall transaction
|
|
28
28
|
- 💸 **Gas Abstraction Built-In** — Pay gas in STRK, ETH, USDC, USDT, or DAI via AVNU Paymaster, or let the developer sponsor gas entirely (gasfree mode)
|
|
29
29
|
- 📊 **Full Portfolio** — Unified view of balances, staking positions, and lending positions with USD values
|
|
@@ -35,36 +35,37 @@ Most DeFi tools are built for humans clicking buttons. StarkFi is built for **ag
|
|
|
35
35
|
## Architecture
|
|
36
36
|
|
|
37
37
|
```
|
|
38
|
-
|
|
39
|
-
│ StarkFi
|
|
40
|
-
│
|
|
41
|
-
│ ┌──────────┐ ┌────────────────┐ ┌────────────────┐ ┌─────────────────────────┐
|
|
42
|
-
│ │ CLI │ │ MCP Server │ │ Agent Skills │ │ Telegram Bot │
|
|
43
|
-
│ │ (
|
|
44
|
-
|
|
45
|
-
│
|
|
46
|
-
│
|
|
47
|
-
│
|
|
48
|
-
│
|
|
49
|
-
│
|
|
50
|
-
│
|
|
51
|
-
│ │
|
|
52
|
-
│ │
|
|
53
|
-
│ │ │
|
|
54
|
-
│ │
|
|
55
|
-
│ │
|
|
56
|
-
│ │
|
|
57
|
-
│ │
|
|
58
|
-
│ │
|
|
59
|
-
│ │
|
|
60
|
-
│ │
|
|
61
|
-
│
|
|
62
|
-
│
|
|
63
|
-
│
|
|
64
|
-
│
|
|
65
|
-
│ │
|
|
66
|
-
│
|
|
67
|
-
|
|
38
|
+
┌───────────────────────────────────────────────────────────────────────────────────────┐
|
|
39
|
+
│ StarkFi │
|
|
40
|
+
│ │
|
|
41
|
+
│ ┌──────────┐ ┌────────────────┐ ┌────────────────┐ ┌─────────────────────────┐ │
|
|
42
|
+
│ │ CLI │ │ MCP Server │ │ Agent Skills │ │ Telegram Bot │ │
|
|
43
|
+
│ │ (42+ │ │ (42 tools) │ │ (12 workflows) │ │ (BYOAI · Chat DeFi) │ │
|
|
44
|
+
|
|
45
|
+
│ │ commands)│ │ stdio transport│ │ npx starkfi │ │ OpenAI / Claude / │ │
|
|
46
|
+
│ └────┬─────┘ └──────┬─────────┘ └─────┬──────────┘ │ Gemini │ │
|
|
47
|
+
│ │ │ │ └───────────┬─────────────┘ │
|
|
48
|
+
│ └───────────────┼──────────────────┼─────────────────────────┘ │
|
|
49
|
+
│ ▼ ▼ │
|
|
50
|
+
│ ┌────────────────────────────────────────────────────────────────────────────────┐ │
|
|
51
|
+
│ │ Service Layer │ │
|
|
52
|
+
│ │ ┌────────┐ ┌────────┐ ┌──────┐ ┌─────┐ ┌────────┐ ┌─────────┐ ┌──────────────┐ │ │
|
|
53
|
+
│ │ │ DEX │ │Staking │ │ Vesu │ │ DCA │ │ Batch │ │Portfolio│ │ Confidential │ │ │
|
|
54
|
+
│ │ │ Swap │ │Lifecycl│ │ V2 │ │ │ │Multical│ │Dashboard│ │ Tongo Cash │ │ │
|
|
55
|
+
│ │ └────┬─────┘ └────┬─────┘ └───┬────┘ └───┬──┘ └────┬─────┘ └────┬─────┘ │ │
|
|
56
|
+
│ │ └─────────────┴────────────┴───────────┴──────────┴─────────────┘ │ │
|
|
57
|
+
│ │ │ │ │
|
|
58
|
+
│ │ ┌───────────┴───────────────────────────────┐ │ │
|
|
59
|
+
│ │ │ Starkzap SDK (starkzap v2.0.0) │ │ │
|
|
60
|
+
│ │ │ Wallet · TxBuilder · Tokens · Paymaster │ │ │
|
|
61
|
+
│ │ └─────────────┬─────────────────────────────┘ │ │
|
|
62
|
+
│ └───────────────────────┼────────────────────────────────────────────────────────┘ │
|
|
63
|
+
│ ▼ │
|
|
64
|
+
│ ┌──────────────────────────────────────┐ ┌──────────────────────┐ │
|
|
65
|
+
│ │ Auth Server (Hono + Privy TEE) │ │ AVNU Paymaster │ │
|
|
66
|
+
│ │ Email OTP · Wallet · Sign · Gas │ │ Gas Abstraction │ │
|
|
67
|
+
│ └──────────────────────────────────────┘ └──────────────────────┘ │
|
|
68
|
+
└───────────────────────────────────────────────────────────────────────────────────────┘
|
|
68
69
|
│
|
|
69
70
|
▼
|
|
70
71
|
┌──────────────────┐
|
|
@@ -80,25 +81,53 @@ StarkFi leverages **all core Starkzap modules**:
|
|
|
80
81
|
|
|
81
82
|
| Module | Usage in StarkFi |
|
|
82
83
|
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
|
|
83
|
-
| **Wallets** | `
|
|
84
|
+
| **Wallets** | `OnboardStrategy.Privy` + `argentXV050` preset for automated email-based wallet onboarding via Privy TEE |
|
|
84
85
|
| **Gasless Transactions (Paymaster)** | Paymaster integration with 5 gas tokens (STRK, ETH, USDC, USDT, DAI) + developer-sponsored gasfree mode |
|
|
85
86
|
| **Staking** | Multi-token staking lifecycle (STRK, WBTC, tBTC, SolvBTC, LBTC) — stake, claim, compound, unstake (2-step) |
|
|
86
|
-
| **
|
|
87
|
+
| **DCA** | Dollar-Cost Averaging via AVNU and Ekubo — create, preview, list, and cancel recurring buy orders |
|
|
88
|
+
| **TxBuilder** | Atomic multicall batching — combine swap + stake + supply + send + borrow + repay + withdraw + dca in one transaction |
|
|
89
|
+
| **Confidential (Tongo Cash)** | Privacy-preserving transfers via TongoConfidential — fund, transfer, withdraw, ragequit, rollover |
|
|
87
90
|
| **ERC-20 Tokens** | Token presets, balance queries, transfers, approvals |
|
|
88
91
|
|
|
89
92
|
---
|
|
90
93
|
|
|
91
94
|
## Features
|
|
92
95
|
|
|
93
|
-
### 🔄
|
|
96
|
+
### 🔄 Token Swap (Multi-Provider)
|
|
94
97
|
|
|
95
|
-
|
|
98
|
+
Swap tokens on Starknet via Fibrous (default), AVNU, or Ekubo — or use `--provider auto` to race all providers for the best price. Supports multi-pair batch swaps.
|
|
96
99
|
|
|
97
100
|
```bash
|
|
98
|
-
npx starkfi@latest trade 100 USDC ETH
|
|
101
|
+
npx starkfi@latest trade 100 USDC ETH # Swap via Fibrous (default)
|
|
102
|
+
npx starkfi@latest trade 100 USDC ETH --provider auto # Race all providers for best price
|
|
99
103
|
npx starkfi@latest multi-swap "100 USDC>ETH, 50 USDT>ETH"
|
|
100
104
|
```
|
|
101
105
|
|
|
106
|
+
### 📅 Dollar-Cost Averaging (DCA)
|
|
107
|
+
|
|
108
|
+
Set up recurring buy orders that automatically swap a fixed amount at regular intervals. Supports AVNU and Ekubo DCA providers.
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
npx starkfi@latest dca-preview 10 USDC ETH # Preview single cycle
|
|
112
|
+
npx starkfi@latest dca-create 1000 USDC ETH --per-cycle 10 --frequency P1D # Daily DCA
|
|
113
|
+
npx starkfi@latest dca-list --status ACTIVE # View orders
|
|
114
|
+
npx starkfi@latest dca-cancel <order_id> # Cancel order
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### 🔒 Confidential Transfers (Tongo Cash)
|
|
118
|
+
|
|
119
|
+
Privacy-preserving transfers using ZK proofs via Tongo. Amounts are hidden on-chain; recipients are identified by elliptic curve public keys.
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
npx starkfi@latest conf-setup --key <TONGO_KEY> --contract 0x… # One-time setup
|
|
123
|
+
npx starkfi@latest conf-balance # Check confidential balance
|
|
124
|
+
npx starkfi@latest conf-fund 100 --token USDC # Fund confidential account
|
|
125
|
+
npx starkfi@latest conf-transfer 50 --recipient-x 0x… --recipient-y 0x… # Private transfer
|
|
126
|
+
npx starkfi@latest conf-withdraw 100 # Withdraw to public balance
|
|
127
|
+
npx starkfi@latest conf-ragequit # Emergency full withdrawal
|
|
128
|
+
npx starkfi@latest conf-rollover # Activate pending balance
|
|
129
|
+
```
|
|
130
|
+
|
|
102
131
|
### ⚛️ Atomic Transaction Batching
|
|
103
132
|
|
|
104
133
|
Bundle multiple DeFi operations into a single Starknet multicall. Minimum 2 operations.
|
|
@@ -108,7 +137,9 @@ npx starkfi@latest batch \
|
|
|
108
137
|
--swap "100 USDC ETH" \
|
|
109
138
|
--stake "50 STRK karnot" \
|
|
110
139
|
--supply "200 USDC Prime" \
|
|
111
|
-
--send "10 STRK 0xAddr"
|
|
140
|
+
--send "10 STRK 0xAddr" \
|
|
141
|
+
--borrow "0.5 ETH 500 USDC Prime" \
|
|
142
|
+
--withdraw "200 USDC Prime"
|
|
112
143
|
```
|
|
113
144
|
|
|
114
145
|
### 🥩 Multi-Token Staking Lifecycle
|
|
@@ -147,6 +178,26 @@ npx starkfi@latest lend-auto -p Prime --collateral-token ETH --borrow-token USDC
|
|
|
147
178
|
npx starkfi@latest lend-auto -p Prime --collateral-token ETH --borrow-token USDC --simulate
|
|
148
179
|
```
|
|
149
180
|
|
|
181
|
+
### 🌐 Network Support (Mainnet + Sepolia)
|
|
182
|
+
|
|
183
|
+
Switch between Mainnet and Sepolia instantly — no re-login required. All token addresses resolve dynamically per-network.
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
npx starkfi@latest config set-network sepolia # Switch to testnet
|
|
187
|
+
npx starkfi@latest config set-network mainnet # Switch back
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
| Module | Network-Aware | Notes |
|
|
191
|
+
| --------------------- | ------------- | ------------------------------------------------------------ |
|
|
192
|
+
| **Lending (Vesu V2)** | ✅ | Pools, supply, borrow, monitor, auto-rebalance |
|
|
193
|
+
| **Staking** | ✅ | Multi-token — STRK, WBTC, tBTC, SolvBTC, LBTC |
|
|
194
|
+
| **Batch** | ✅ | All batch operations (supply, borrow, repay, withdraw, stake, send, dca) |
|
|
195
|
+
| **Portfolio** | ✅ | Balances, staking positions, lending positions |
|
|
196
|
+
| **Wallet (Send)** | ✅ | Token transfers and simulation |
|
|
197
|
+
| **Swap** | Mainnet only | Fibrous (default), AVNU, Ekubo — selectable via `--provider` |
|
|
198
|
+
| **Multi-Swap** | Mainnet only | Per-pair provider selection |
|
|
199
|
+
| **Rebalance** | Mainnet only | Uses swap routing for rebalance execution |
|
|
200
|
+
|
|
150
201
|
### 💸 Gas Abstraction
|
|
151
202
|
|
|
152
203
|
Users pay gas fees in their preferred ERC-20 token via AVNU Paymaster — no native STRK or ETH required. Alternatively, developers can sponsor gas entirely.
|
|
@@ -195,7 +246,7 @@ npx starkfi@latest portfolio-rebalance --target "60 ETH, 40 STRK" --simulate
|
|
|
195
246
|
|
|
196
247
|
## AI Integration (MCP)
|
|
197
248
|
|
|
198
|
-
StarkFi exposes **
|
|
249
|
+
StarkFi exposes **42 MCP tools** via stdio transport, enabling AI assistants to execute DeFi operations.
|
|
199
250
|
|
|
200
251
|
```bash
|
|
201
252
|
# Start the MCP server
|
|
@@ -204,13 +255,16 @@ npx starkfi@latest mcp-start
|
|
|
204
255
|
|
|
205
256
|
### Tool Categories
|
|
206
257
|
|
|
207
|
-
| Category
|
|
208
|
-
|
|
|
209
|
-
| **Auth & Config**
|
|
210
|
-
| **Wallet**
|
|
211
|
-
| **Trade**
|
|
212
|
-
| **Staking**
|
|
213
|
-
| **Lending**
|
|
258
|
+
| Category | Tools | Count |
|
|
259
|
+
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
|
|
260
|
+
| **Auth & Config** | `get_auth_status`, `config_action` | 2 |
|
|
261
|
+
| **Wallet** | `get_balance`, `get_portfolio`, `deploy_account`, `send_tokens`, `get_tx_status`, `rebalance_portfolio` | 6 |
|
|
262
|
+
| **Trade** | `get_swap_quote`, `swap_tokens`, `get_multi_swap_quote`, `multi_swap`, `batch_execute` | 5 |
|
|
263
|
+
| **Staking** | `list_validators`, `list_pools`, `get_staking_info`, `get_stake_status`, `stake_tokens`, `unstake_tokens`, `claim_rewards`, `compound_rewards` | 8 |
|
|
264
|
+
| **Lending** | `list_lending_pools`, `get_lending_position`, `supply_assets`, `withdraw_assets`, `borrow_assets`, `repay_debt`, `close_position`, `monitor_lending_position`, `auto_rebalance_lending` | 9 |
|
|
265
|
+
| **DCA** | `dca_preview`, `dca_create`, `dca_list`, `dca_cancel` | 4 |
|
|
266
|
+
| **Confidential** | `confidential_setup`, `confidential_balance`, `confidential_fund`, `confidential_transfer`, `confidential_withdraw`, `confidential_ragequit`, `confidential_rollover` | 7 |
|
|
267
|
+
| **Health (Lending)** | `lending_quote_health` | 1 |
|
|
214
268
|
|
|
215
269
|
### Example — AI Agent Workflow
|
|
216
270
|
|
|
@@ -244,14 +298,14 @@ For the complete tool registry and schemas, see [MCP Documentation](https://docs
|
|
|
244
298
|
|
|
245
299
|
## Agent Skills
|
|
246
300
|
|
|
247
|
-
StarkFi ships with **
|
|
301
|
+
StarkFi ships with **12 agent skills** — structured instruction sets that teach AI coding assistants how to use StarkFi without custom prompting.
|
|
248
302
|
|
|
249
|
-
| Category | Skills
|
|
250
|
-
| ---------------- |
|
|
251
|
-
| **Auth** | `authenticate-wallet`
|
|
252
|
-
| **Wallet Data** | `balance`, `portfolio`
|
|
253
|
-
| **Transactions** | `send`, `trade`, `multi-swap`, `batch`, `staking`, `lending` |
|
|
254
|
-
| **Utility** | `config`
|
|
303
|
+
| Category | Skills |
|
|
304
|
+
| ---------------- | ----------------------------------------------------------------------------------- |
|
|
305
|
+
| **Auth** | `authenticate-wallet` |
|
|
306
|
+
| **Wallet Data** | `balance`, `portfolio` |
|
|
307
|
+
| **Transactions** | `send`, `trade`, `multi-swap`, `batch`, `staking`, `lending`, `dca`, `confidential` |
|
|
308
|
+
| **Utility** | `config` |
|
|
255
309
|
|
|
256
310
|
```bash
|
|
257
311
|
# Install skills for your AI assistant
|
|
@@ -313,18 +367,39 @@ npx starkfi@latest trade 10 STRK ETH # Execute
|
|
|
313
367
|
| `send <amount> <token> <recipient> [--simulate] [--json]` | Transfer tokens |
|
|
314
368
|
| `portfolio [--json]` | Full DeFi portfolio |
|
|
315
369
|
|
|
316
|
-
### Trading
|
|
370
|
+
### Trading
|
|
317
371
|
|
|
318
|
-
| Command
|
|
319
|
-
|
|
|
320
|
-
| `trade <amount> <from> <to> [--slippage <%>] [--simulate] [--json]` | Swap tokens
|
|
321
|
-
| `multi-swap "<pairs>" [--slippage <%>] [--simulate] [--json]`
|
|
372
|
+
| Command | Description |
|
|
373
|
+
| ------------------------------------------------------------------------------------------------------------- | --------------------------- |
|
|
374
|
+
| `trade <amount> <from> <to> [--provider <fibrous\|avnu\|ekubo\|auto>] [--slippage <%>] [--simulate] [--json]` | Swap tokens (via Fibrous) |
|
|
375
|
+
| `multi-swap "<pairs>" [--provider <name>] [--slippage <%>] [--simulate] [--json]` | Multi-pair swap (2-3 pairs) |
|
|
376
|
+
|
|
377
|
+
### DCA (Dollar-Cost Averaging)
|
|
378
|
+
|
|
379
|
+
| Command | Description |
|
|
380
|
+
| --------------------------------------------------------------------------------------------------------------------- | -------------------- |
|
|
381
|
+
| `dca-preview <amount> <sell> <buy> [--provider <avnu\|ekubo>] [--json]` | Preview single cycle |
|
|
382
|
+
| `dca-create <amount> <sell> <buy> --per-cycle <n> [--frequency <duration>] [--provider <name>] [--simulate] [--json]` | Create DCA order |
|
|
383
|
+
| `dca-list [--status <ACTIVE\|CLOSED\|INDEXING>] [--provider <name>] [--page <n>] [--json]` | List DCA orders |
|
|
384
|
+
| `dca-cancel <order_id> [--provider <name>] [--json]` | Cancel a DCA order |
|
|
385
|
+
|
|
386
|
+
### Confidential Transfers (Tongo Cash)
|
|
387
|
+
|
|
388
|
+
| Command | Description |
|
|
389
|
+
| ------------------------------------------------------------------------------ | ------------------------------------ |
|
|
390
|
+
| `conf-setup --key <key> --contract <address>` | Configure Tongo Cash credentials |
|
|
391
|
+
| `conf-balance [--json]` | Show confidential balance |
|
|
392
|
+
| `conf-fund <amount> [--token <symbol>] [--simulate] [--json]` | Fund confidential account |
|
|
393
|
+
| `conf-transfer <amount> --recipient-x <x> --recipient-y <y> [--simulate] [--json]` | Confidential transfer |
|
|
394
|
+
| `conf-withdraw <amount> [--to <address>] [--token <symbol>] [--simulate] [--json]` | Withdraw to public address |
|
|
395
|
+
| `conf-ragequit [--to <address>] [--json]` | Emergency full withdrawal |
|
|
396
|
+
| `conf-rollover [--json]` | Activate pending balance |
|
|
322
397
|
|
|
323
398
|
### Batching (Multicall)
|
|
324
399
|
|
|
325
400
|
| Command | Description |
|
|
326
401
|
| --------------------------------------------------------------------------- | ---------------------------- |
|
|
327
|
-
| `batch [--simulate] --swap "..." --stake "..." --supply "..." --send "..."` | Atomic multicall (min 2 ops) |
|
|
402
|
+
| `batch [--simulate] --swap "..." --stake "..." --supply "..." --send "..." --borrow "..." --repay "..." --withdraw "..." --dca-create "..." --dca-cancel "..."` | Atomic multicall (min 2 ops) |
|
|
328
403
|
|
|
329
404
|
### Staking
|
|
330
405
|
|
|
@@ -339,37 +414,37 @@ npx starkfi@latest trade 10 STRK ETH # Execute
|
|
|
339
414
|
|
|
340
415
|
### Lending (Vesu V2)
|
|
341
416
|
|
|
342
|
-
| Command
|
|
343
|
-
|
|
|
344
|
-
| `lend-pools [name]`
|
|
345
|
-
| `lend-supply <amount> -p <pool> -t <token
|
|
346
|
-
| `lend-withdraw <amount> -p <pool> -t <token
|
|
347
|
-
| `lend-borrow -p <pool> --collateral-amount <n> --collateral-token <t> --borrow-amount <n> --borrow-token <t> [--use-supplied]` | Borrow |
|
|
348
|
-
| `lend-repay <amount> -p <pool> -t <token> --collateral-token <t
|
|
349
|
-
| `lend-status [-p <pool> --collateral-token <t> [--borrow-token <t>]]`
|
|
350
|
-
| `lend-close -p <pool> --collateral-token <t> --borrow-token <t
|
|
351
|
-
| `lend-monitor [-p <pool> --collateral-token <t> --borrow-token <t>]`
|
|
352
|
-
| `lend-auto -p <pool> --collateral-token <t> --borrow-token <t> [--strategy <type>]` | Auto-rebalance position |
|
|
417
|
+
| Command | Description |
|
|
418
|
+
| ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
|
|
419
|
+
| `lend-pools [name]` | List lending pools |
|
|
420
|
+
| `lend-supply <amount> -p <pool> -t <token> [--simulate]` | Supply assets |
|
|
421
|
+
| `lend-withdraw <amount> -p <pool> -t <token> [--simulate]` | Withdraw assets |
|
|
422
|
+
| `lend-borrow -p <pool> --collateral-amount <n> --collateral-token <t> --borrow-amount <n> --borrow-token <t> [--use-supplied] [--simulate]` | Borrow |
|
|
423
|
+
| `lend-repay <amount> -p <pool> -t <token> --collateral-token <t> [--simulate]` | Repay debt |
|
|
424
|
+
| `lend-status [-p <pool> --collateral-token <t> [--borrow-token <t>]]` | Position status (auto-scan if no args) |
|
|
425
|
+
| `lend-close -p <pool> --collateral-token <t> --borrow-token <t> [--simulate]` | Close position atomically |
|
|
426
|
+
| `lend-monitor [-p <pool> --collateral-token <t> --borrow-token <t>]` | Monitor health factors |
|
|
427
|
+
| `lend-auto -p <pool> --collateral-token <t> --borrow-token <t> [--strategy <type>] [--simulate]` | Auto-rebalance position |
|
|
353
428
|
|
|
354
429
|
### Portfolio
|
|
355
430
|
|
|
356
|
-
| Command
|
|
357
|
-
|
|
|
358
|
-
| `portfolio [--json]`
|
|
359
|
-
| `portfolio-rebalance --target "<allocation>" [--slippage <%>] [--simulate] [--json]`
|
|
431
|
+
| Command | Description |
|
|
432
|
+
| ------------------------------------------------------------------------------------ | ------------------------------ |
|
|
433
|
+
| `portfolio [--json]` | Full DeFi dashboard |
|
|
434
|
+
| `portfolio-rebalance --target "<allocation>" [--slippage <%>] [--simulate] [--json]` | Rebalance to target allocation |
|
|
360
435
|
|
|
361
436
|
### Configuration
|
|
362
437
|
|
|
363
|
-
| Command | Description
|
|
364
|
-
| --------------------------------------- |
|
|
365
|
-
| `config list` | Show current configuration
|
|
366
|
-
| `config reset` | Reset all settings to defaults
|
|
367
|
-
| `config set-rpc <url>` | Set custom RPC endpoint
|
|
368
|
-
| `config get-rpc` | Show current RPC
|
|
369
|
-
| `config set-network <mainnet\|sepolia>` | Switch network
|
|
370
|
-
| `config set-gas-token <token\|reset>` | Set gas payment token
|
|
371
|
-
| `config set-gasfree <on\|off>` | Toggle developer-sponsored gas
|
|
372
|
-
| `tx-status <hash>` | Check transaction status
|
|
438
|
+
| Command | Description |
|
|
439
|
+
| --------------------------------------- | ---------------------------------------------------------- |
|
|
440
|
+
| `config list` | Show current configuration (with effective network source) |
|
|
441
|
+
| `config reset` | Reset all settings to defaults |
|
|
442
|
+
| `config set-rpc <url>` | Set custom RPC endpoint |
|
|
443
|
+
| `config get-rpc` | Show current RPC |
|
|
444
|
+
| `config set-network <mainnet\|sepolia>` | Switch network instantly (no re-login needed) |
|
|
445
|
+
| `config set-gas-token <token\|reset>` | Set gas payment token |
|
|
446
|
+
| `config set-gasfree <on\|off>` | Toggle developer-sponsored gas |
|
|
447
|
+
| `tx-status <hash>` | Check transaction status |
|
|
373
448
|
|
|
374
449
|
---
|
|
375
450
|
|
|
@@ -404,14 +479,16 @@ StarkFi has a dedicated **[Telegram bot](https://github.com/ahmetenesdur/starkfi
|
|
|
404
479
|
|
|
405
480
|
**BYOAI Model** — each user provides their own API key (OpenAI, Claude, or Gemini). No shared keys, no centralized billing.
|
|
406
481
|
|
|
407
|
-
| Feature
|
|
408
|
-
|
|
|
409
|
-
| **Swap**
|
|
410
|
-
| **Stake**
|
|
411
|
-
| **Lend**
|
|
412
|
-
| **
|
|
413
|
-
| **
|
|
414
|
-
| **
|
|
482
|
+
| Feature | Description |
|
|
483
|
+
| ----------------- | ------------------------------------------------------------------- |
|
|
484
|
+
| **Swap** | Token trading via Fibrous (default), AVNU, or Ekubo |
|
|
485
|
+
| **Stake** | Multi-token staking (STRK, WBTC, tBTC, SolvBTC, LBTC) |
|
|
486
|
+
| **Lend** | Supply, borrow, repay, withdraw, close on Vesu V2 |
|
|
487
|
+
| **DCA** | Dollar-Cost Averaging with recurring buy orders (AVNU, Ekubo) |
|
|
488
|
+
| **Confidential** | Privacy-preserving transfers via Tongo Cash (ZK proofs) |
|
|
489
|
+
| **Portfolio** | Balances with USD valuations and position health |
|
|
490
|
+
| **Batch** | Combine swap + stake + supply + send + borrow + repay + withdraw + DCA in one transaction |
|
|
491
|
+
| **Gas Modes** | Gasless (pay in ERC-20) and gasfree (developer-sponsored) |
|
|
415
492
|
|
|
416
493
|
```bash
|
|
417
494
|
git clone https://github.com/ahmetenesdur/starkfi-telegram-bot.git
|
|
@@ -427,31 +504,32 @@ See [`starkfi-telegram-bot/`](https://github.com/ahmetenesdur/starkfi-telegram-b
|
|
|
427
504
|
|
|
428
505
|
## Tech Stack
|
|
429
506
|
|
|
430
|
-
| Layer | Technology
|
|
431
|
-
| --------------- |
|
|
432
|
-
| **Core SDK** | [Starkzap](https://github.com/keep-starknet-strange/starkzap)
|
|
433
|
-
| **CLI** | [Commander.js](https://github.com/tj/commander.js) v14.0.3
|
|
434
|
-
| **MCP** | [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) v1.27.1
|
|
435
|
-
| **Schema** | [Zod](https://zod.dev/) v4.3.6
|
|
436
|
-
| **Auth Server** | [Hono](https://hono.dev/) v4.12.7 + [Privy TEE](https://privy.io/)
|
|
437
|
-
| **DEX Routing** | [Fibrous](https://fibrous.finance/)
|
|
438
|
-
| **Lending** | [Vesu](https://vesu.io/) V2 Protocol
|
|
439
|
-
| **Gas** | [AVNU](https://avnu.fi/) Paymaster
|
|
507
|
+
| Layer | Technology |
|
|
508
|
+
| --------------- | ---------------------------------------------------------------------------------------------------- |
|
|
509
|
+
| **Core SDK** | [Starkzap](https://github.com/keep-starknet-strange/starkzap) v2.0.0 |
|
|
510
|
+
| **CLI** | [Commander.js](https://github.com/tj/commander.js) v14.0.3 |
|
|
511
|
+
| **MCP** | [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) v1.27.1 |
|
|
512
|
+
| **Schema** | [Zod](https://zod.dev/) v4.3.6 |
|
|
513
|
+
| **Auth Server** | [Hono](https://hono.dev/) v4.12.7 + [Privy TEE](https://privy.io/) |
|
|
514
|
+
| **DEX Routing** | [Fibrous](https://fibrous.finance/) (default), [AVNU](https://avnu.fi/), [Ekubo](https://ekubo.org/) |
|
|
515
|
+
| **Lending** | [Vesu](https://vesu.io/) V2 Protocol |
|
|
516
|
+
| **Gas** | [AVNU](https://avnu.fi/) Paymaster |
|
|
440
517
|
|
|
441
518
|
---
|
|
442
519
|
|
|
443
520
|
## Error Handling
|
|
444
521
|
|
|
445
|
-
StarkFi implements a robust error handling system with a custom `StarkfiError` class and **
|
|
446
|
-
|
|
447
|
-
| Domain | Error Codes
|
|
448
|
-
| -------------- |
|
|
449
|
-
| **Auth** | `AUTH_REQUIRED`, `AUTH_FAILED`, `SESSION_EXPIRED`
|
|
450
|
-
| **Wallet** | `WALLET_NOT_DEPLOYED`, `WALLET_NOT_FOUND`, `INSUFFICIENT_BALANCE`
|
|
451
|
-
| **Network** | `NETWORK_ERROR`, `RATE_LIMITED`, `TX_FAILED`, `TX_NOT_FOUND`, `PAYMASTER_ERROR`
|
|
452
|
-
| **Validation** | `INVALID_CONFIG`, `INVALID_ADDRESS`, `INVALID_AMOUNT`, `INVALID_ALLOCATION`
|
|
453
|
-
| **DeFi** | `SWAP_FAILED`, `NO_ROUTE_FOUND`, `SLIPPAGE_EXCEEDED`, `STAKING_FAILED`, `LENDING_FAILED`, `POOL_NOT_FOUND`, `EXIT_NOT_READY`, `VALIDATOR_NOT_FOUND`, `MONITOR_FAILED`, `REBALANCE_FAILED` |
|
|
454
|
-
| **
|
|
522
|
+
StarkFi implements a robust error handling system with a custom `StarkfiError` class and **34 specific error codes** organized by domain:
|
|
523
|
+
|
|
524
|
+
| Domain | Error Codes |
|
|
525
|
+
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
526
|
+
| **Auth** | `AUTH_REQUIRED`, `AUTH_FAILED`, `SESSION_EXPIRED` |
|
|
527
|
+
| **Wallet** | `WALLET_NOT_DEPLOYED`, `WALLET_NOT_FOUND`, `INSUFFICIENT_BALANCE` |
|
|
528
|
+
| **Network** | `NETWORK_ERROR`, `RATE_LIMITED`, `TX_FAILED`, `TX_NOT_FOUND`, `PAYMASTER_ERROR` |
|
|
529
|
+
| **Validation** | `INVALID_CONFIG`, `INVALID_ADDRESS`, `INVALID_AMOUNT`, `INVALID_ALLOCATION` |
|
|
530
|
+
| **DeFi** | `SWAP_FAILED`, `NO_ROUTE_FOUND`, `SLIPPAGE_EXCEEDED`, `PROVIDER_UNAVAILABLE`, `ALL_PROVIDERS_FAILED`, `STAKING_FAILED`, `LENDING_FAILED`, `DCA_FAILED`, `CONFIDENTIAL_FAILED`, `POOL_NOT_FOUND`, `EXIT_NOT_READY`, `VALIDATOR_NOT_FOUND`, `MONITOR_FAILED`, `REBALANCE_FAILED` |
|
|
531
|
+
| **Confidential** | `CONFIDENTIAL_NOT_CONFIGURED` |
|
|
532
|
+
| **System** | `SIMULATION_FAILED`, `BATCH_LIMIT_EXCEEDED`, `UNKNOWN` |
|
|
455
533
|
|
|
456
534
|
All network operations include **automatic retry with exponential backoff** (500ms base, max 2 retries). Parallel operations use a **sliding-window concurrency pool** to prevent RPC rate-limiting.
|
|
457
535
|
|