starkfi 0.5.0 → 0.6.1
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 +166 -131
- package/dist/index.js +245 -156
- package/package.json +14 -8
- 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 +185 -0
- package/skills/config/SKILL.md +6 -4
- package/skills/dca/SKILL.md +134 -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
|
|
@@ -32,73 +32,59 @@ Most DeFi tools are built for humans clicking buttons. StarkFi is built for **ag
|
|
|
32
32
|
|
|
33
33
|
---
|
|
34
34
|
|
|
35
|
-
## Architecture
|
|
36
|
-
|
|
37
|
-
```
|
|
38
|
-
┌─────────────────────────────────────────────────────────────────────────────────────┐
|
|
39
|
-
│ StarkFi │
|
|
40
|
-
│ │
|
|
41
|
-
│ ┌──────────┐ ┌────────────────┐ ┌────────────────┐ ┌─────────────────────────┐ │
|
|
42
|
-
│ │ CLI │ │ MCP Server │ │ Agent Skills │ │ Telegram Bot │ │
|
|
43
|
-
│ │ (30+ │ │ (30 tools) │ │ (10 workflows) │ │ (BYOAI · Chat DeFi) │ │
|
|
44
|
-
│ │ commands)│ │ stdio transport│ │ npx starkfi │ │ OpenAI / Claude / │ │
|
|
45
|
-
│ └────┬─────┘ └──────┬─────────┘ └─────┬──────────┘ │ Gemini │ │
|
|
46
|
-
│ │ │ │ └───────────┬─────────────┘ │
|
|
47
|
-
│ └───────────────┼──────────────────┼─────────────────────────┘ │
|
|
48
|
-
│ ▼ ▼ │
|
|
49
|
-
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
|
|
50
|
-
│ │ Service Layer │ │
|
|
51
|
-
│ │ ┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐ ┌──────────────┐ │ │
|
|
52
|
-
│ │ │ Fibrous │ │ Staking │ │ Vesu │ │ Batch │ │ Portfolio │ │ │
|
|
53
|
-
│ │ │ Swap │ │ Lifecycle│ │ V2 │ │ Multicall│ │ Dashboard │ │ │
|
|
54
|
-
│ │ └────┬─────┘ └────┬─────┘ └───┬────┘ └────┬─────┘ └──────┬───────┘ │ │
|
|
55
|
-
│ │ └─────────────┴────────────┴────────────┴───────────────┘ │ │
|
|
56
|
-
│ │ │ │ │
|
|
57
|
-
│ │ ┌───────────────┴───────────────────────────┐ │ │
|
|
58
|
-
│ │ │ Starkzap SDK (starkzap v1.0.0) │ │ │
|
|
59
|
-
│ │ │ Wallet · TxBuilder · Tokens · Paymaster │ │ │
|
|
60
|
-
│ │ └───────────────┬───────────────────────────┘ │ │
|
|
61
|
-
│ └───────────────────────┼──────────────────────────────────────────────────────┘ │
|
|
62
|
-
│ ▼ │
|
|
63
|
-
│ ┌──────────────────────────────────────┐ ┌──────────────────────┐ │
|
|
64
|
-
│ │ Auth Server (Hono + Privy TEE) │ │ AVNU Paymaster │ │
|
|
65
|
-
│ │ Email OTP · Wallet · Sign · Gas │ │ Gas Abstraction │ │
|
|
66
|
-
│ └──────────────────────────────────────┘ └──────────────────────┘ │
|
|
67
|
-
└─────────────────────────────────────────────────────────────────────────────────────┘
|
|
68
|
-
│
|
|
69
|
-
▼
|
|
70
|
-
┌──────────────────┐
|
|
71
|
-
│ Starknet (L2) │
|
|
72
|
-
└──────────────────┘
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
---
|
|
76
|
-
|
|
77
35
|
## Starkzap Modules Used
|
|
78
36
|
|
|
79
37
|
StarkFi leverages **all core Starkzap modules**:
|
|
80
38
|
|
|
81
|
-
| Module | Usage in StarkFi
|
|
82
|
-
| ------------------------------------ |
|
|
83
|
-
| **Wallets** | `
|
|
84
|
-
| **Gasless Transactions (Paymaster)** | Paymaster integration with 5 gas tokens (STRK, ETH, USDC, USDT, DAI) + developer-sponsored gasfree mode
|
|
85
|
-
| **Staking** | Multi-token staking lifecycle (STRK, WBTC, tBTC, SolvBTC, LBTC) — stake, claim, compound, unstake (2-step)
|
|
86
|
-
| **
|
|
87
|
-
| **
|
|
39
|
+
| Module | Usage in StarkFi |
|
|
40
|
+
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
|
|
41
|
+
| **Wallets** | `OnboardStrategy.Privy` + `argentXV050` preset for automated email-based wallet onboarding via Privy TEE |
|
|
42
|
+
| **Gasless Transactions (Paymaster)** | Paymaster integration with 5 gas tokens (STRK, ETH, USDC, USDT, DAI) + developer-sponsored gasfree mode |
|
|
43
|
+
| **Staking** | Multi-token staking lifecycle (STRK, WBTC, tBTC, SolvBTC, LBTC) — stake, claim, compound, unstake (2-step) |
|
|
44
|
+
| **DCA** | Dollar-Cost Averaging via AVNU and Ekubo — create, preview, list, and cancel recurring buy orders |
|
|
45
|
+
| **TxBuilder** | Atomic multicall batching — combine swap + stake + supply + send + borrow + repay + withdraw + dca in one transaction |
|
|
46
|
+
| **Confidential (Tongo Cash)** | Privacy-preserving transfers via TongoConfidential — fund, transfer, withdraw, ragequit, rollover |
|
|
47
|
+
| **ERC-20 Tokens** | Token presets, balance queries, transfers, approvals |
|
|
88
48
|
|
|
89
49
|
---
|
|
90
50
|
|
|
91
51
|
## Features
|
|
92
52
|
|
|
93
|
-
### 🔄
|
|
53
|
+
### 🔄 Token Swap (Multi-Provider)
|
|
94
54
|
|
|
95
|
-
|
|
55
|
+
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
56
|
|
|
97
57
|
```bash
|
|
98
|
-
npx starkfi@latest trade 100 USDC ETH
|
|
58
|
+
npx starkfi@latest trade 100 USDC ETH # Swap via Fibrous (default)
|
|
59
|
+
npx starkfi@latest trade 100 USDC ETH --provider auto # Race all providers for best price
|
|
99
60
|
npx starkfi@latest multi-swap "100 USDC>ETH, 50 USDT>ETH"
|
|
100
61
|
```
|
|
101
62
|
|
|
63
|
+
### 📅 Dollar-Cost Averaging (DCA)
|
|
64
|
+
|
|
65
|
+
Set up recurring buy orders that automatically swap a fixed amount at regular intervals. Supports AVNU and Ekubo DCA providers.
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
npx starkfi@latest dca-preview 10 USDC ETH # Preview single cycle
|
|
69
|
+
npx starkfi@latest dca-create 1000 USDC ETH --per-cycle 10 --frequency P1D # Daily DCA
|
|
70
|
+
npx starkfi@latest dca-list --status ACTIVE # View orders
|
|
71
|
+
npx starkfi@latest dca-cancel <order_id> # Cancel order
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### 🔒 Confidential Transfers (Tongo Cash)
|
|
75
|
+
|
|
76
|
+
Privacy-preserving transfers using ZK proofs via Tongo. Amounts are hidden on-chain; recipients are identified by elliptic curve public keys.
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
npx starkfi@latest conf-setup --key <TONGO_KEY> --contract 0x… # One-time setup
|
|
80
|
+
npx starkfi@latest conf-balance # Check confidential balance
|
|
81
|
+
npx starkfi@latest conf-fund 100 --token USDC # Fund confidential account
|
|
82
|
+
npx starkfi@latest conf-transfer 50 --recipient-x 0x… --recipient-y 0x… # Private transfer
|
|
83
|
+
npx starkfi@latest conf-withdraw 100 # Withdraw to public balance
|
|
84
|
+
npx starkfi@latest conf-ragequit # Emergency full withdrawal
|
|
85
|
+
npx starkfi@latest conf-rollover # Activate pending balance
|
|
86
|
+
```
|
|
87
|
+
|
|
102
88
|
### ⚛️ Atomic Transaction Batching
|
|
103
89
|
|
|
104
90
|
Bundle multiple DeFi operations into a single Starknet multicall. Minimum 2 operations.
|
|
@@ -108,7 +94,9 @@ npx starkfi@latest batch \
|
|
|
108
94
|
--swap "100 USDC ETH" \
|
|
109
95
|
--stake "50 STRK karnot" \
|
|
110
96
|
--supply "200 USDC Prime" \
|
|
111
|
-
--send "10 STRK 0xAddr"
|
|
97
|
+
--send "10 STRK 0xAddr" \
|
|
98
|
+
--borrow "0.5 ETH 500 USDC Prime" \
|
|
99
|
+
--withdraw "200 USDC Prime"
|
|
112
100
|
```
|
|
113
101
|
|
|
114
102
|
### 🥩 Multi-Token Staking Lifecycle
|
|
@@ -147,6 +135,26 @@ npx starkfi@latest lend-auto -p Prime --collateral-token ETH --borrow-token USDC
|
|
|
147
135
|
npx starkfi@latest lend-auto -p Prime --collateral-token ETH --borrow-token USDC --simulate
|
|
148
136
|
```
|
|
149
137
|
|
|
138
|
+
### 🌐 Network Support (Mainnet + Sepolia)
|
|
139
|
+
|
|
140
|
+
Switch between Mainnet and Sepolia instantly — no re-login required. All token addresses resolve dynamically per-network.
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
npx starkfi@latest config set-network sepolia # Switch to testnet
|
|
144
|
+
npx starkfi@latest config set-network mainnet # Switch back
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
| Module | Network-Aware | Notes |
|
|
148
|
+
| --------------------- | ------------- | ------------------------------------------------------------------------ |
|
|
149
|
+
| **Lending (Vesu V2)** | ✅ | Pools, supply, borrow, monitor, auto-rebalance |
|
|
150
|
+
| **Staking** | ✅ | Multi-token — STRK, WBTC, tBTC, SolvBTC, LBTC |
|
|
151
|
+
| **Batch** | ✅ | All batch operations (supply, borrow, repay, withdraw, stake, send, dca) |
|
|
152
|
+
| **Portfolio** | ✅ | Balances, staking positions, lending positions |
|
|
153
|
+
| **Wallet (Send)** | ✅ | Token transfers and simulation |
|
|
154
|
+
| **Swap** | Mainnet only | Fibrous (default), AVNU, Ekubo — selectable via `--provider` |
|
|
155
|
+
| **Multi-Swap** | Mainnet only | Per-pair provider selection |
|
|
156
|
+
| **Rebalance** | Mainnet only | Uses swap routing for rebalance execution |
|
|
157
|
+
|
|
150
158
|
### 💸 Gas Abstraction
|
|
151
159
|
|
|
152
160
|
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 +203,7 @@ npx starkfi@latest portfolio-rebalance --target "60 ETH, 40 STRK" --simulate
|
|
|
195
203
|
|
|
196
204
|
## AI Integration (MCP)
|
|
197
205
|
|
|
198
|
-
StarkFi exposes **
|
|
206
|
+
StarkFi exposes **42 MCP tools** via stdio transport, enabling AI assistants to execute DeFi operations.
|
|
199
207
|
|
|
200
208
|
```bash
|
|
201
209
|
# Start the MCP server
|
|
@@ -204,13 +212,16 @@ npx starkfi@latest mcp-start
|
|
|
204
212
|
|
|
205
213
|
### Tool Categories
|
|
206
214
|
|
|
207
|
-
| Category
|
|
208
|
-
|
|
|
209
|
-
| **Auth & Config**
|
|
210
|
-
| **Wallet**
|
|
211
|
-
| **Trade**
|
|
212
|
-
| **Staking**
|
|
213
|
-
| **Lending**
|
|
215
|
+
| Category | Tools | Count |
|
|
216
|
+
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
|
|
217
|
+
| **Auth & Config** | `get_auth_status`, `config_action` | 2 |
|
|
218
|
+
| **Wallet** | `get_balance`, `get_portfolio`, `deploy_account`, `send_tokens`, `get_tx_status`, `rebalance_portfolio` | 6 |
|
|
219
|
+
| **Trade** | `get_swap_quote`, `swap_tokens`, `get_multi_swap_quote`, `multi_swap`, `batch_execute` | 5 |
|
|
220
|
+
| **Staking** | `list_validators`, `list_pools`, `get_staking_info`, `get_stake_status`, `stake_tokens`, `unstake_tokens`, `claim_rewards`, `compound_rewards` | 8 |
|
|
221
|
+
| **Lending** | `list_lending_pools`, `get_lending_position`, `supply_assets`, `withdraw_assets`, `borrow_assets`, `repay_debt`, `close_position`, `monitor_lending_position`, `auto_rebalance_lending` | 9 |
|
|
222
|
+
| **DCA** | `dca_preview`, `dca_create`, `dca_list`, `dca_cancel` | 4 |
|
|
223
|
+
| **Confidential** | `confidential_setup`, `confidential_balance`, `confidential_fund`, `confidential_transfer`, `confidential_withdraw`, `confidential_ragequit`, `confidential_rollover` | 7 |
|
|
224
|
+
| **Health (Lending)** | `lending_quote_health` | 1 |
|
|
214
225
|
|
|
215
226
|
### Example — AI Agent Workflow
|
|
216
227
|
|
|
@@ -244,14 +255,14 @@ For the complete tool registry and schemas, see [MCP Documentation](https://docs
|
|
|
244
255
|
|
|
245
256
|
## Agent Skills
|
|
246
257
|
|
|
247
|
-
StarkFi ships with **
|
|
258
|
+
StarkFi ships with **12 agent skills** — structured instruction sets that teach AI coding assistants how to use StarkFi without custom prompting.
|
|
248
259
|
|
|
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`
|
|
260
|
+
| Category | Skills |
|
|
261
|
+
| ---------------- | ----------------------------------------------------------------------------------- |
|
|
262
|
+
| **Auth** | `authenticate-wallet` |
|
|
263
|
+
| **Wallet Data** | `balance`, `portfolio` |
|
|
264
|
+
| **Transactions** | `send`, `trade`, `multi-swap`, `batch`, `staking`, `lending`, `dca`, `confidential` |
|
|
265
|
+
| **Utility** | `config` |
|
|
255
266
|
|
|
256
267
|
```bash
|
|
257
268
|
# Install skills for your AI assistant
|
|
@@ -313,18 +324,39 @@ npx starkfi@latest trade 10 STRK ETH # Execute
|
|
|
313
324
|
| `send <amount> <token> <recipient> [--simulate] [--json]` | Transfer tokens |
|
|
314
325
|
| `portfolio [--json]` | Full DeFi portfolio |
|
|
315
326
|
|
|
316
|
-
### Trading
|
|
327
|
+
### Trading
|
|
328
|
+
|
|
329
|
+
| Command | Description |
|
|
330
|
+
| ------------------------------------------------------------------------------------------------------------- | --------------------------- |
|
|
331
|
+
| `trade <amount> <from> <to> [--provider <fibrous\|avnu\|ekubo\|auto>] [--slippage <%>] [--simulate] [--json]` | Swap tokens (via Fibrous) |
|
|
332
|
+
| `multi-swap "<pairs>" [--provider <name>] [--slippage <%>] [--simulate] [--json]` | Multi-pair swap (2-3 pairs) |
|
|
333
|
+
|
|
334
|
+
### DCA (Dollar-Cost Averaging)
|
|
317
335
|
|
|
318
|
-
| Command
|
|
319
|
-
|
|
|
320
|
-
| `
|
|
321
|
-
| `
|
|
336
|
+
| Command | Description |
|
|
337
|
+
| --------------------------------------------------------------------------------------------------------------------- | -------------------- |
|
|
338
|
+
| `dca-preview <amount> <sell> <buy> [--provider <avnu\|ekubo>] [--json]` | Preview single cycle |
|
|
339
|
+
| `dca-create <amount> <sell> <buy> --per-cycle <n> [--frequency <duration>] [--provider <name>] [--simulate] [--json]` | Create DCA order |
|
|
340
|
+
| `dca-list [--status <ACTIVE\|CLOSED\|INDEXING>] [--provider <name>] [--page <n>] [--json]` | List DCA orders |
|
|
341
|
+
| `dca-cancel <order_id> [--provider <name>] [--json]` | Cancel a DCA order |
|
|
342
|
+
|
|
343
|
+
### Confidential Transfers (Tongo Cash)
|
|
344
|
+
|
|
345
|
+
| Command | Description |
|
|
346
|
+
| ---------------------------------------------------------------------------------- | -------------------------------- |
|
|
347
|
+
| `conf-setup --key <key> --contract <address>` | Configure Tongo Cash credentials |
|
|
348
|
+
| `conf-balance [--json]` | Show confidential balance |
|
|
349
|
+
| `conf-fund <amount> [--token <symbol>] [--simulate] [--json]` | Fund confidential account |
|
|
350
|
+
| `conf-transfer <amount> --recipient-x <x> --recipient-y <y> [--simulate] [--json]` | Confidential transfer |
|
|
351
|
+
| `conf-withdraw <amount> [--to <address>] [--token <symbol>] [--simulate] [--json]` | Withdraw to public address |
|
|
352
|
+
| `conf-ragequit [--to <address>] [--json]` | Emergency full withdrawal |
|
|
353
|
+
| `conf-rollover [--json]` | Activate pending balance |
|
|
322
354
|
|
|
323
355
|
### Batching (Multicall)
|
|
324
356
|
|
|
325
|
-
| Command
|
|
326
|
-
|
|
|
327
|
-
| `batch [--simulate] --swap "..." --stake "..." --supply "..." --send "..."` | Atomic multicall (min 2 ops) |
|
|
357
|
+
| Command | Description |
|
|
358
|
+
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
|
|
359
|
+
| `batch [--simulate] --swap "..." --stake "..." --supply "..." --send "..." --borrow "..." --repay "..." --withdraw "..." --dca-create "..." --dca-cancel "..."` | Atomic multicall (min 2 ops) |
|
|
328
360
|
|
|
329
361
|
### Staking
|
|
330
362
|
|
|
@@ -339,37 +371,37 @@ npx starkfi@latest trade 10 STRK ETH # Execute
|
|
|
339
371
|
|
|
340
372
|
### Lending (Vesu V2)
|
|
341
373
|
|
|
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 |
|
|
374
|
+
| Command | Description |
|
|
375
|
+
| ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
|
|
376
|
+
| `lend-pools [name]` | List lending pools |
|
|
377
|
+
| `lend-supply <amount> -p <pool> -t <token> [--simulate]` | Supply assets |
|
|
378
|
+
| `lend-withdraw <amount> -p <pool> -t <token> [--simulate]` | Withdraw assets |
|
|
379
|
+
| `lend-borrow -p <pool> --collateral-amount <n> --collateral-token <t> --borrow-amount <n> --borrow-token <t> [--use-supplied] [--simulate]` | Borrow |
|
|
380
|
+
| `lend-repay <amount> -p <pool> -t <token> --collateral-token <t> [--simulate]` | Repay debt |
|
|
381
|
+
| `lend-status [-p <pool> --collateral-token <t> [--borrow-token <t>]]` | Position status (auto-scan if no args) |
|
|
382
|
+
| `lend-close -p <pool> --collateral-token <t> --borrow-token <t> [--simulate]` | Close position atomically |
|
|
383
|
+
| `lend-monitor [-p <pool> --collateral-token <t> --borrow-token <t>]` | Monitor health factors |
|
|
384
|
+
| `lend-auto -p <pool> --collateral-token <t> --borrow-token <t> [--strategy <type>] [--simulate]` | Auto-rebalance position |
|
|
353
385
|
|
|
354
386
|
### Portfolio
|
|
355
387
|
|
|
356
|
-
| Command
|
|
357
|
-
|
|
|
358
|
-
| `portfolio [--json]`
|
|
359
|
-
| `portfolio-rebalance --target "<allocation>" [--slippage <%>] [--simulate] [--json]`
|
|
388
|
+
| Command | Description |
|
|
389
|
+
| ------------------------------------------------------------------------------------ | ------------------------------ |
|
|
390
|
+
| `portfolio [--json]` | Full DeFi dashboard |
|
|
391
|
+
| `portfolio-rebalance --target "<allocation>" [--slippage <%>] [--simulate] [--json]` | Rebalance to target allocation |
|
|
360
392
|
|
|
361
393
|
### Configuration
|
|
362
394
|
|
|
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
|
|
395
|
+
| Command | Description |
|
|
396
|
+
| --------------------------------------- | ---------------------------------------------------------- |
|
|
397
|
+
| `config list` | Show current configuration (with effective network source) |
|
|
398
|
+
| `config reset` | Reset all settings to defaults |
|
|
399
|
+
| `config set-rpc <url>` | Set custom RPC endpoint |
|
|
400
|
+
| `config get-rpc` | Show current RPC |
|
|
401
|
+
| `config set-network <mainnet\|sepolia>` | Switch network instantly (no re-login needed) |
|
|
402
|
+
| `config set-gas-token <token\|reset>` | Set gas payment token |
|
|
403
|
+
| `config set-gasfree <on\|off>` | Toggle developer-sponsored gas |
|
|
404
|
+
| `tx-status <hash>` | Check transaction status |
|
|
373
405
|
|
|
374
406
|
---
|
|
375
407
|
|
|
@@ -404,14 +436,16 @@ StarkFi has a dedicated **[Telegram bot](https://github.com/ahmetenesdur/starkfi
|
|
|
404
436
|
|
|
405
437
|
**BYOAI Model** — each user provides their own API key (OpenAI, Claude, or Gemini). No shared keys, no centralized billing.
|
|
406
438
|
|
|
407
|
-
| Feature
|
|
408
|
-
|
|
|
409
|
-
| **Swap**
|
|
410
|
-
| **Stake**
|
|
411
|
-
| **Lend**
|
|
412
|
-
| **
|
|
413
|
-
| **
|
|
414
|
-
| **
|
|
439
|
+
| Feature | Description |
|
|
440
|
+
| ---------------- | ----------------------------------------------------------------------------------------- |
|
|
441
|
+
| **Swap** | Token trading via Fibrous (default), AVNU, or Ekubo |
|
|
442
|
+
| **Stake** | Multi-token staking (STRK, WBTC, tBTC, SolvBTC, LBTC) |
|
|
443
|
+
| **Lend** | Supply, borrow, repay, withdraw, close on Vesu V2 |
|
|
444
|
+
| **DCA** | Dollar-Cost Averaging with recurring buy orders (AVNU, Ekubo) |
|
|
445
|
+
| **Confidential** | Privacy-preserving transfers via Tongo Cash (ZK proofs) |
|
|
446
|
+
| **Portfolio** | Balances with USD valuations and position health |
|
|
447
|
+
| **Batch** | Combine swap + stake + supply + send + borrow + repay + withdraw + DCA in one transaction |
|
|
448
|
+
| **Gas Modes** | Gasless (pay in ERC-20) and gasfree (developer-sponsored) |
|
|
415
449
|
|
|
416
450
|
```bash
|
|
417
451
|
git clone https://github.com/ahmetenesdur/starkfi-telegram-bot.git
|
|
@@ -427,31 +461,32 @@ See [`starkfi-telegram-bot/`](https://github.com/ahmetenesdur/starkfi-telegram-b
|
|
|
427
461
|
|
|
428
462
|
## Tech Stack
|
|
429
463
|
|
|
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
|
|
464
|
+
| Layer | Technology |
|
|
465
|
+
| --------------- | ---------------------------------------------------------------------------------------------------- |
|
|
466
|
+
| **Core SDK** | [Starkzap](https://github.com/keep-starknet-strange/starkzap) v2.0.0 |
|
|
467
|
+
| **CLI** | [Commander.js](https://github.com/tj/commander.js) v14.0.3 |
|
|
468
|
+
| **MCP** | [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) v1.27.1 |
|
|
469
|
+
| **Schema** | [Zod](https://zod.dev/) v4.3.6 |
|
|
470
|
+
| **Auth Server** | [Hono](https://hono.dev/) v4.12.7 + [Privy TEE](https://privy.io/) |
|
|
471
|
+
| **DEX Routing** | [Fibrous](https://fibrous.finance/) (default), [AVNU](https://avnu.fi/), [Ekubo](https://ekubo.org/) |
|
|
472
|
+
| **Lending** | [Vesu](https://vesu.io/) V2 Protocol |
|
|
473
|
+
| **Gas** | [AVNU](https://avnu.fi/) Paymaster |
|
|
440
474
|
|
|
441
475
|
---
|
|
442
476
|
|
|
443
477
|
## Error Handling
|
|
444
478
|
|
|
445
|
-
StarkFi implements a robust error handling system with a custom `StarkfiError` class and **
|
|
446
|
-
|
|
447
|
-
| Domain
|
|
448
|
-
|
|
|
449
|
-
| **Auth**
|
|
450
|
-
| **Wallet**
|
|
451
|
-
| **Network**
|
|
452
|
-
| **Validation**
|
|
453
|
-
| **DeFi**
|
|
454
|
-
| **
|
|
479
|
+
StarkFi implements a robust error handling system with a custom `StarkfiError` class and **34 specific error codes** organized by domain:
|
|
480
|
+
|
|
481
|
+
| Domain | Error Codes |
|
|
482
|
+
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
483
|
+
| **Auth** | `AUTH_REQUIRED`, `AUTH_FAILED`, `SESSION_EXPIRED` |
|
|
484
|
+
| **Wallet** | `WALLET_NOT_DEPLOYED`, `WALLET_NOT_FOUND`, `INSUFFICIENT_BALANCE` |
|
|
485
|
+
| **Network** | `NETWORK_ERROR`, `RATE_LIMITED`, `TX_FAILED`, `TX_NOT_FOUND`, `PAYMASTER_ERROR` |
|
|
486
|
+
| **Validation** | `INVALID_CONFIG`, `INVALID_ADDRESS`, `INVALID_AMOUNT`, `INVALID_ALLOCATION` |
|
|
487
|
+
| **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` |
|
|
488
|
+
| **Confidential** | `CONFIDENTIAL_NOT_CONFIGURED` |
|
|
489
|
+
| **System** | `SIMULATION_FAILED`, `BATCH_LIMIT_EXCEEDED`, `UNKNOWN` |
|
|
455
490
|
|
|
456
491
|
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
492
|
|