starkfi 0.4.3 → 0.5.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.
Files changed (8) hide show
  1. package/MCP.md +36 -2
  2. package/README.md +93 -54
  3. package/dist/index.js +145 -129
  4. package/package.json +6 -5
  5. package/skills/README.md +5 -2
  6. package/skills/batch/SKILL.md +4 -3
  7. package/skills/lending/SKILL.md +95 -6
  8. package/skills/portfolio/SKILL.md +76 -11
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "starkfi",
3
- "version": "0.4.3",
3
+ "version": "0.5.0",
4
4
  "description": "AI-native Starknet DeFi CLI + MCP Server + Agent Skills — Swaps, multi-swap, batch (multicall), staking, lending, simulation, portfolio, gas abstraction",
5
5
  "type": "module",
6
6
  "bin": {
@@ -66,9 +66,10 @@
66
66
  "engines": {
67
67
  "node": ">=18"
68
68
  },
69
- "dependencies": {},
70
69
  "pnpm": {
71
- "onlyBuiltDependencies": ["esbuild"]
70
+ "onlyBuiltDependencies": [
71
+ "esbuild"
72
+ ]
72
73
  },
73
74
  "devDependencies": {
74
75
  "@eslint/js": "^10.0.1",
@@ -77,7 +78,7 @@
77
78
  "chalk": "^5.6.2",
78
79
  "commander": "^14.0.3",
79
80
  "env-paths": "^3.0.0",
80
- "eslint": "^10.0.3",
81
+ "eslint": "^10.1.0",
81
82
  "eslint-config-prettier": "^10.1.8",
82
83
  "globals": "^17.4.0",
83
84
  "jiti": "^2.6.1",
@@ -87,7 +88,7 @@
87
88
  "tsup": "^8.5.1",
88
89
  "tsx": "^4.21.0",
89
90
  "typescript": "^5.9.3",
90
- "typescript-eslint": "^8.57.0",
91
+ "typescript-eslint": "^8.57.1",
91
92
  "zod": "^4.3.6"
92
93
  }
93
94
  }
package/skills/README.md CHANGED
@@ -13,8 +13,8 @@ Agent Skills for the [StarkFi](https://github.com/ahmetenesdur/starkfi) CLI —
13
13
  | [multi-swap](./multi-swap/SKILL.md) | transaction | Multiple swaps in one transaction (up to 3) |
14
14
  | [batch](./batch/SKILL.md) | transaction | Combine swap + stake + supply + send in one multicall |
15
15
  | [staking](./staking/SKILL.md) | transaction | Stake, unstake, claim, compound (STRK, WBTC, tBTC, SolvBTC, LBTC) |
16
- | [lending](./lending/SKILL.md) | transaction | Vesu V2 lending: supply, borrow, repay, withdraw, close |
17
- | [portfolio](./portfolio/SKILL.md) | wallet-data | Aggregated DeFi dashboard with USD valuations |
16
+ | [lending](./lending/SKILL.md) | transaction | Vesu V2 lending: supply, borrow, repay, monitor, auto-rebalance |
17
+ | [portfolio](./portfolio/SKILL.md) | wallet-data | DeFi dashboard + portfolio optimization via rebalancing |
18
18
  | [config](./config/SKILL.md) | utility | RPC, network, gas settings, transaction status |
19
19
 
20
20
  ## Installation
@@ -51,7 +51,10 @@ npx skills add ahmetenesdur/starkfi
51
51
  | "Swap ETH and then stake STRK" | `batch` |
52
52
  | "Stake 1000 STRK with Karnot" | `staking` |
53
53
  | "Supply 500 USDC to Prime pool" | `lending` |
54
+ | "Is my position safe?" | `lending` |
55
+ | "Fix my risky position" | `lending` |
54
56
  | "Show me my portfolio" | `portfolio` |
57
+ | "Rebalance to 50% ETH, 30% USDC" | `portfolio` |
55
58
  | "I'm getting rate limit errors" | `config` |
56
59
 
57
60
  ## License
package/skills/batch/SKILL.md CHANGED
@@ -30,9 +30,10 @@ Bundle multiple diverse DeFi operations into a single Starknet multicall transac
30
30
  1. BEFORE any batch, you MUST run `npx starkfi@latest status` and `npx starkfi@latest balance` to verify connectivity and funds.
31
31
  2. A batch MUST include at least **2 operations**. For single operations, use the dedicated skill (`trade`, `send`, `staking`, or `lending`).
32
32
  3. Each `--swap`, `--stake`, `--supply`, and `--send` flag can appear **multiple times** (repeatable).
33
- 4. Suggest using `--simulate` first to verify the entire batch would succeed.
34
- 5. AFTER a successful batch, verify with `npx starkfi@latest tx-status <hash>`.
35
- 6. All operations in a batch are **atomic** — if any one fails, the entire transaction reverts.
33
+ 4. If the batch includes a `--send` operation, you MUST confirm the recipient address with the user before executing.
34
+ 5. Suggest using `--simulate` first to verify the entire batch would succeed.
35
+ 6. AFTER a successful batch, verify with `npx starkfi@latest tx-status <hash>`.
36
+ 7. All operations in a batch are **atomic** — if any one fails, the entire transaction reverts.
36
37
 
37
38
  ## Commands
38
39
 
package/skills/lending/SKILL.md CHANGED
@@ -1,10 +1,10 @@
1
1
  ---
2
2
  name: lending
3
- description: Manage Vesu V2 lending positions on Starknet — supply assets, borrow against collateral, repay debt, withdraw, and close positions. Use this skill when the user mentions lending, borrowing, supplying collateral, Vesu, interest, health factor, liquidation, or DeFi yield from lending protocols.
3
+ description: Manage Vesu V2 lending positions on Starknet — supply assets, borrow against collateral, repay debt, withdraw, close positions, monitor health factors, and auto-rebalance risky positions. Use this skill when the user mentions lending, borrowing, supplying collateral, Vesu, interest, health factor, liquidation, monitoring positions, auto-rebalancing, protecting against liquidation, or DeFi yield from lending protocols.
4
4
  license: MIT
5
5
  compatibility: Requires Node.js 18+ and npx.
6
6
  metadata:
7
- version: 0.1.0
7
+ version: 0.2.0
8
8
  author: ahmetenesdur
9
9
  category: transaction
10
10
  allowed-tools:
@@ -16,6 +16,9 @@ allowed-tools:
16
16
  - Bash(npx starkfi@latest lend-borrow *)
17
17
  - Bash(npx starkfi@latest lend-repay *)
18
18
  - Bash(npx starkfi@latest lend-close *)
19
+ - Bash(npx starkfi@latest lend-monitor)
20
+ - Bash(npx starkfi@latest lend-monitor *)
21
+ - Bash(npx starkfi@latest lend-auto *)
19
22
  - Bash(npx starkfi@latest status)
20
23
  - Bash(npx starkfi@latest balance)
21
24
  - Bash(npx starkfi@latest balance *)
@@ -24,7 +27,7 @@ allowed-tools:
24
27
 
25
28
  # Lending (Vesu V2)
26
29
 
27
- Manage lending and borrowing positions on Vesu V2 protocol on Starknet. Supply assets to earn yield, borrow against collateral, repay debt, and close positions.
30
+ Manage lending and borrowing positions on Vesu V2 protocol on Starknet. Supply assets to earn yield, borrow against collateral, repay debt, monitor health factors, auto-rebalance risky positions, and close positions.
28
31
 
29
32
  ## Prerequisites
30
33
 
@@ -42,6 +45,8 @@ Manage lending and borrowing positions on Vesu V2 protocol on Starknet. Supply a
42
45
  - Health Factor **< 1.1** → DO NOT proceed without explicit double-confirmation from the user.
43
46
  4. AFTER any transactional operation, verify with `tx-status`.
44
47
  5. When using `--use-supplied`, the borrow is backed by the user's existing vTokens (supplied positions) rather than transferring from wallet.
48
+ 6. When the user asks about health, risk, or liquidation — use `lend-monitor` first for a comprehensive overview with 4-level risk classification (SAFE/WARNING/DANGER/CRITICAL).
49
+ 7. When a position's health factor is low, suggest `lend-auto` to automatically rebalance. Always use `--simulate` first to preview the action before executing.
45
50
 
46
51
  ## Commands
47
52
 
@@ -92,6 +97,33 @@ npx starkfi@latest lend-repay <amount> --pool <name|address> --token <symbol> --
92
97
  npx starkfi@latest lend-close --pool <name|address> --collateral-token <symbol> --borrow-token <symbol>
93
98
  ```
94
99
 
100
+ ### Health Monitoring
101
+
102
+ ```bash
103
+ # Scan all positions across all pools
104
+ npx starkfi@latest lend-monitor [--json]
105
+
106
+ # Monitor specific position
107
+ npx starkfi@latest lend-monitor --pool <name|address> --collateral-token <symbol> --borrow-token <symbol>
108
+
109
+ # Custom warning threshold
110
+ npx starkfi@latest lend-monitor --warning-threshold 1.5
111
+ ```
112
+
113
+ ### Auto-Rebalance
114
+
115
+ ```bash
116
+ # Auto-rebalance (picks best strategy — repay or add collateral)
117
+ npx starkfi@latest lend-auto --pool <name|address> --collateral-token <symbol> --borrow-token <symbol>
118
+
119
+ # With specific strategy
120
+ npx starkfi@latest lend-auto --pool <name|address> --collateral-token <symbol> --borrow-token <symbol> --strategy repay
121
+ npx starkfi@latest lend-auto --pool <name|address> --collateral-token <symbol> --borrow-token <symbol> --strategy add-collateral
122
+
123
+ # Simulate first (always recommended)
124
+ npx starkfi@latest lend-auto --pool <name|address> --collateral-token <symbol> --borrow-token <symbol> --simulate
125
+ ```
126
+
95
127
  ## Parameters
96
128
 
97
129
  ### lend-supply / lend-withdraw
@@ -142,6 +174,39 @@ Run without arguments to **auto-scan all pools**. Or specify `--pool` + `--colla
142
174
 
143
175
  > \* Required when `--pool` is specified.
144
176
 
177
+ ### lend-monitor
178
+
179
+ Run without arguments to **scan all pools**. Or specify `--pool` + `--collateral-token` + `--borrow-token` for a single position.
180
+
181
+ | Parameter | Type | Description | Required |
182
+ | ---------------------- | ------ | ------------------------------------ | ------------------------- |
183
+ | `--pool` | string | Pool name or address | No (scans all if omitted) |
184
+ | `--collateral-token` | string | Collateral token symbol | No* |
185
+ | `--borrow-token` | string | Debt token symbol | No* |
186
+ | `--warning-threshold` | number | Custom warning threshold (default: 1.3) | No |
187
+
188
+ > \* Required when `--pool` is specified.
189
+
190
+ **Risk Levels:**
191
+
192
+ | Level | Health Factor | Meaning |
193
+ | ------------ | ------------- | ------------------------------------- |
194
+ | **SAFE** | > 1.3 | No action needed |
195
+ | **WARNING** | 1.1 – 1.3 | Monitor closely |
196
+ | **DANGER** | 1.05 – 1.1 | Repay debt or add collateral |
197
+ | **CRITICAL** | ≤ 1.05 | Imminent liquidation risk |
198
+
199
+ ### lend-auto
200
+
201
+ | Parameter | Type | Description | Required |
202
+ | ---------------------- | ------ | ---------------------------------------------- | -------- |
203
+ | `--pool` | string | Pool name or address | Yes |
204
+ | `--collateral-token` | string | Collateral token symbol | Yes |
205
+ | `--borrow-token` | string | Debt token symbol | Yes |
206
+ | `--strategy` | string | `repay`, `add-collateral`, or `auto` (default) | No |
207
+ | `--target-hf` | number | Target health factor (default: 1.3) | No |
208
+ | `--simulate` | flag | Preview without executing | No |
209
+
145
210
  ## Examples
146
211
 
147
212
  **User:** "What lending pools are available?"
@@ -194,11 +259,32 @@ npx starkfi@latest tx-status <hash>
194
259
  **User:** "How healthy is my position?"
195
260
 
196
261
  ```bash
197
- # Quick overview of all positions
198
- npx starkfi@latest lend-status
262
+ # Comprehensive health monitoring with risk levels
263
+ npx starkfi@latest lend-monitor
199
264
 
200
265
  # Detailed health factor for specific position
201
- npx starkfi@latest lend-status --pool Prime --collateral-token ETH --borrow-token USDC
266
+ npx starkfi@latest lend-monitor --pool Prime --collateral-token ETH --borrow-token USDC
267
+ ```
268
+
269
+ **User:** "My position is at risk, fix it"
270
+
271
+ ```bash
272
+ # First, check current state
273
+ npx starkfi@latest lend-monitor --pool Prime --collateral-token ETH --borrow-token USDC
274
+
275
+ # Simulate the auto-rebalance action
276
+ npx starkfi@latest lend-auto --pool Prime --collateral-token ETH --borrow-token USDC --simulate
277
+
278
+ # Execute after user confirms
279
+ npx starkfi@latest lend-auto --pool Prime --collateral-token ETH --borrow-token USDC
280
+ npx starkfi@latest tx-status <hash>
281
+ ```
282
+
283
+ **User:** "Protect my ETH/USDC position from liquidation"
284
+
285
+ ```bash
286
+ # Choose a specific strategy — repay debt
287
+ npx starkfi@latest lend-auto --pool Prime --collateral-token ETH --borrow-token USDC --strategy repay --simulate
202
288
  ```
203
289
 
204
290
  ## Error Handling
@@ -211,6 +297,8 @@ npx starkfi@latest lend-status --pool Prime --collateral-token ETH --borrow-toke
211
297
  | `Dust limit` | Borrow amount is below the pool's minimum dollar value (~$10). Increase it. |
212
298
  | `Insufficient balance` | Check `balance` — user may need to swap for the token. |
213
299
  | `Not authenticated` | Run `authenticate-wallet` skill first. |
300
+ | `Monitor failed` | Check pool/token params and retry. |
301
+ | `Rebalance failed` | Check balances, health factor, and retry. |
214
302
 
215
303
  ## Related Skills
216
304
 
@@ -218,3 +306,4 @@ npx starkfi@latest lend-status --pool Prime --collateral-token ETH --borrow-toke
218
306
  - Use `trade` to swap tokens if the user doesn't have the right asset.
219
307
  - Use `portfolio` for a full overview including lending positions with USD values.
220
308
  - Use `batch` to combine supply operations with swaps or staking.
309
+ - Use `portfolio-rebalance` (within `portfolio` skill) to optimize overall portfolio allocation.
package/skills/portfolio/SKILL.md CHANGED
@@ -1,44 +1,74 @@
1
1
  ---
2
2
  name: portfolio
3
- description: View a comprehensive DeFi portfolio dashboard — token balances, staking positions, and lending positions with USD valuations. Use this skill when the user wants an overview, summary, dashboard, total value, net worth, or wants to see all their DeFi positions across Starknet at once. Also trigger when the user asks "what do I have", "show me everything", "how much am I worth", "my positions", "my investments", or any request for a holistic view of their Starknet holdings — even if they don't explicitly say "portfolio".
3
+ description: View a comprehensive DeFi portfolio dashboard and optimize portfolio allocation via automated rebalancing. Use this skill when the user wants an overview, summary, dashboard, total value, net worth, portfolio rebalancing, target allocation, or wants to see all their DeFi positions across Starknet at once. Also trigger when the user asks "what do I have", "show me everything", "how much am I worth", "my positions", "my investments", "rebalance my portfolio", "I want 50% ETH", "optimize my holdings", or any request for a holistic view of their Starknet holdings — even if they don't explicitly say "portfolio".
4
4
  license: MIT
5
5
  compatibility: Requires Node.js 18+ and npx.
6
6
  metadata:
7
- version: 0.1.0
7
+ version: 0.2.0
8
8
  author: ahmetenesdur
9
9
  category: wallet-data
10
10
  allowed-tools:
11
11
  - Bash(npx starkfi@latest portfolio)
12
12
  - Bash(npx starkfi@latest portfolio *)
13
+ - Bash(npx starkfi@latest portfolio-rebalance *)
13
14
  - Bash(npx starkfi@latest status)
15
+ - Bash(npx starkfi@latest balance)
16
+ - Bash(npx starkfi@latest balance *)
17
+ - Bash(npx starkfi@latest tx-status *)
14
18
  ---
15
19
 
16
- # Portfolio Overview
20
+ # Portfolio Overview & Optimization
17
21
 
18
- Display a comprehensive DeFi portfolio dashboard aggregating token balances, staking positions, and lending positions — all with USD valuations. This is a read-only, single-command skill that provides a complete snapshot of the user's Starknet DeFi activity.
22
+ Display a comprehensive DeFi portfolio dashboard aggregating token balances, staking positions, and lending positions — all with USD valuations. Rebalance the portfolio to a target allocation via automated batch swaps.
19
23
 
20
24
  ## Prerequisites
21
25
 
22
26
  - Active session required.
27
+ - For rebalancing: sufficient token balances + gas for batch swap transactions.
23
28
 
24
29
  ## Rules
25
30
 
26
- 1. Use this as the FIRST command when the user asks "what do I have?" or wants an overall assessment.
27
- 2. This is a read-only operation — it never modifies any on-chain state.
31
+ 1. Use `portfolio` as the FIRST command when the user asks "what do I have?" or wants an overall assessment.
32
+ 2. The `portfolio` command is read-only — it never modifies any on-chain state.
28
33
  3. USD prices are sourced from Fibrous aggregation and may have slight variations.
34
+ 4. For `portfolio-rebalance`, ALWAYS use `--simulate` first to preview the plan before executing.
35
+ 5. Target allocations must sum to **100%**. If they don't, inform the user and ask them to adjust.
36
+ 6. After rebalancing, run `portfolio` again to confirm the new allocation.
29
37
 
30
38
  ## Commands
31
39
 
40
+ ### Portfolio Dashboard
41
+
32
42
  ```bash
33
43
  npx starkfi@latest portfolio [--json]
34
44
  ```
35
45
 
46
+ ### Portfolio Rebalance
47
+
48
+ ```bash
49
+ # Rebalance to target allocation
50
+ npx starkfi@latest portfolio-rebalance --target "<allocation>" [--slippage <n>] [--simulate] [--json]
51
+ ```
52
+
36
53
  ## Parameters
37
54
 
55
+ ### portfolio
56
+
38
57
  | Parameter | Type | Description | Required |
39
58
  | --------- | ---- | -------------- | -------- |
40
59
  | `--json` | flag | Output as JSON | No |
41
60
 
61
+ ### portfolio-rebalance
62
+
63
+ | Parameter | Type | Description | Required |
64
+ | -------------- | ------ | ---------------------------------------------------- | -------- |
65
+ | `--target` | string | Target allocation (e.g. `"50 ETH, 30 USDC, 20 STRK"`) | Yes |
66
+ | `--slippage` | number | Slippage tolerance % (default: 1) | No |
67
+ | `--simulate` | flag | Preview plan without executing | No |
68
+ | `--json` | flag | Output as JSON | No |
69
+
70
+ **Target allocation format:** Comma-separated `<percentage> <token>` pairs that sum to 100.
71
+
42
72
  ## Dashboard Sections
43
73
 
44
74
  The portfolio displays three sections:
@@ -67,16 +97,51 @@ npx starkfi@latest portfolio
67
97
  npx starkfi@latest portfolio --json
68
98
  ```
69
99
 
100
+ **User:** "Rebalance to 50% ETH, 30% USDC, 20% STRK"
101
+
102
+ ```bash
103
+ # 1. View current allocation
104
+ npx starkfi@latest portfolio
105
+
106
+ # 2. Preview the rebalance plan
107
+ npx starkfi@latest portfolio-rebalance --target "50 ETH, 30 USDC, 20 STRK" --simulate
108
+
109
+ # 3. Execute after user confirms
110
+ npx starkfi@latest portfolio-rebalance --target "50 ETH, 30 USDC, 20 STRK"
111
+ npx starkfi@latest tx-status <hash>
112
+
113
+ # 4. Verify new allocation
114
+ npx starkfi@latest portfolio
115
+ ```
116
+
117
+ **User:** "I want 60% ETH and 40% STRK"
118
+
119
+ ```bash
120
+ npx starkfi@latest portfolio-rebalance --target "60 ETH, 40 STRK" --simulate
121
+ ```
122
+
123
+ **User:** "Optimize my portfolio with 2% slippage"
124
+
125
+ ```bash
126
+ npx starkfi@latest portfolio-rebalance --target "50 ETH, 30 USDC, 20 STRK" --slippage 2
127
+ ```
128
+
70
129
  ## Error Handling
71
130
 
72
- | Error | Action |
73
- | ------------------- | -------------------------------------------------------------------------------------------------- |
74
- | `Not authenticated` | Run `authenticate-wallet` skill first. |
75
- | `Partial failure` | Some sections may show errors while others succeed. The portfolio uses fault-tolerant aggregation. |
76
- | `Network error` | Retry once. Use `config` to set custom RPC. |
131
+ | Error | Action |
132
+ | ---------------------- | -------------------------------------------------------------------------------------------------- |
133
+ | `Not authenticated` | Run `authenticate-wallet` skill first. |
134
+ | `Partial failure` | Some sections may show errors while others succeed. The portfolio uses fault-tolerant aggregation. |
135
+ | `Network error` | Retry once. Use `config` to set custom RPC. |
136
+ | `Invalid allocation` | Ensure target percentages sum to 100 and token symbols are valid. |
137
+ | `Rebalance failed` | Check balances, ensure tokens have sufficient liquidity on Fibrous. |
138
+ | `Insufficient balance` | Not enough tokens to execute swaps — check `balance` first. |
77
139
 
78
140
  ## Related Skills
79
141
 
80
142
  - Use `balance` for a focused view of token balances only.
81
143
  - Use `staking` `stake-status` for detailed staking positions.
82
144
  - Use `lending` `lend-status` for detailed lending positions.
145
+ - Use `lending` `lend-monitor` to monitor health factors across lending positions.
146
+ - Use `trade` if you need to swap a single token pair (not full rebalance).
147
+