starkfi 0.6.1 → 0.6.3
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 +110 -450
- package/README.md +90 -468
- package/dist/index.js +125 -119
- package/package.json +1 -1
- package/skills/README.md +47 -21
- package/skills/config/SKILL.md +1 -1
- package/skills/dca/SKILL.md +2 -1
- package/skills/lending/SKILL.md +1 -1
- package/skills/portfolio/SKILL.md +3 -1
- package/skills/staking/SKILL.md +1 -1
package/README.md
CHANGED
|
@@ -5,12 +5,13 @@
|
|
|
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
|
|
8
|
+
A production-grade CLI, MCP server, and Telegram bot that gives both developers and AI agents full access to Starknet DeFi — 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">
|
|
12
12
|
<a href="https://www.npmjs.com/package/starkfi"><img src="https://img.shields.io/npm/v/starkfi?style=flat-square&color=CB3837&logo=npm&logoColor=white" alt="npm version"/></a>
|
|
13
13
|
<a href="https://www.npmjs.com/package/starkfi"><img src="https://img.shields.io/npm/dm/starkfi?style=flat-square&color=blue" alt="npm downloads"/></a>
|
|
14
|
+
<a href="https://docs.starkfi.app"><img src="https://img.shields.io/badge/docs-starkfi.app-blue?style=flat-square" alt="Documentation"/></a>
|
|
14
15
|
</p>
|
|
15
16
|
|
|
16
17
|
```bash
|
|
@@ -25,548 +26,169 @@ Most DeFi tools are built for humans clicking buttons. StarkFi is built for **ag
|
|
|
25
26
|
|
|
26
27
|
- 🤖 **42 MCP tools** — Any AI assistant (Cursor, Claude, Antigravity) can execute DeFi operations autonomously
|
|
27
28
|
- ⚡ **Atomic Batching** — Combine swap + stake + lend + send into a single multicall transaction
|
|
28
|
-
- 💸 **Gas Abstraction
|
|
29
|
-
-
|
|
30
|
-
-
|
|
31
|
-
-
|
|
29
|
+
- 💸 **Gas Abstraction** — Pay gas in STRK, ETH, USDC, USDT, or DAI — or let the developer sponsor gas entirely
|
|
30
|
+
- 🔒 **Confidential Transfers** — Privacy-preserving transfers via Tongo Cash (ZK proofs)
|
|
31
|
+
- 📅 **DCA** — Recurring buy orders via AVNU and Ekubo
|
|
32
|
+
- 🧪 **Simulate Everything** — Dry-run any transaction before broadcasting
|
|
33
|
+
- 💬 **Telegram Bot** — Chat-based DeFi via natural language with BYOAI model
|
|
32
34
|
|
|
33
35
|
---
|
|
34
36
|
|
|
35
|
-
##
|
|
36
|
-
|
|
37
|
-
StarkFi leverages **all core Starkzap modules**:
|
|
38
|
-
|
|
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 |
|
|
48
|
-
|
|
49
|
-
---
|
|
50
|
-
|
|
51
|
-
## Features
|
|
52
|
-
|
|
53
|
-
### 🔄 Token Swap (Multi-Provider)
|
|
54
|
-
|
|
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.
|
|
56
|
-
|
|
57
|
-
```bash
|
|
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
|
|
60
|
-
npx starkfi@latest multi-swap "100 USDC>ETH, 50 USDT>ETH"
|
|
61
|
-
```
|
|
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
|
-
|
|
88
|
-
### ⚛️ Atomic Transaction Batching
|
|
89
|
-
|
|
90
|
-
Bundle multiple DeFi operations into a single Starknet multicall. Minimum 2 operations.
|
|
91
|
-
|
|
92
|
-
```bash
|
|
93
|
-
npx starkfi@latest batch \
|
|
94
|
-
--swap "100 USDC ETH" \
|
|
95
|
-
--stake "50 STRK karnot" \
|
|
96
|
-
--supply "200 USDC Prime" \
|
|
97
|
-
--send "10 STRK 0xAddr" \
|
|
98
|
-
--borrow "0.5 ETH 500 USDC Prime" \
|
|
99
|
-
--withdraw "200 USDC Prime"
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
### 🥩 Multi-Token Staking Lifecycle
|
|
103
|
-
|
|
104
|
-
Full staking lifecycle across multiple validators with STRK, WBTC, tBTC, SolvBTC, and LBTC support.
|
|
105
|
-
|
|
106
|
-
```bash
|
|
107
|
-
npx starkfi@latest stake 100 -v karnot
|
|
108
|
-
npx starkfi@latest rewards -v karnot --compound
|
|
109
|
-
npx starkfi@latest unstake intent -v karnot -a 50
|
|
110
|
-
npx starkfi@latest unstake exit -v karnot
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
### 🏦 Lending & Borrowing (Vesu V2)
|
|
114
|
-
|
|
115
|
-
Supply collateral, borrow assets, monitor health factors, and atomically close positions.
|
|
116
|
-
|
|
117
|
-
```bash
|
|
118
|
-
npx starkfi@latest lend-supply 100 -p Prime -t STRK
|
|
119
|
-
npx starkfi@latest lend-borrow -p Prime \
|
|
120
|
-
--collateral-amount 200 --collateral-token STRK \
|
|
121
|
-
--borrow-amount 50 --borrow-token USDC
|
|
122
|
-
npx starkfi@latest lend-status # Auto-scan all pools
|
|
123
|
-
npx starkfi@latest lend-status -p Prime --collateral-token STRK --borrow-token USDC # Specific position
|
|
124
|
-
npx starkfi@latest lend-close -p Prime --collateral-token STRK --borrow-token USDC
|
|
125
|
-
```
|
|
126
|
-
|
|
127
|
-
### 🩺 Lending Agent (Health Monitoring)
|
|
128
|
-
|
|
129
|
-
Real-time health factor monitoring with risk classification and automated position rebalancing.
|
|
130
|
-
|
|
131
|
-
```bash
|
|
132
|
-
npx starkfi@latest lend-monitor # Scan all positions
|
|
133
|
-
npx starkfi@latest lend-monitor -p Prime --collateral-token ETH --borrow-token USDC
|
|
134
|
-
npx starkfi@latest lend-auto -p Prime --collateral-token ETH --borrow-token USDC
|
|
135
|
-
npx starkfi@latest lend-auto -p Prime --collateral-token ETH --borrow-token USDC --simulate
|
|
136
|
-
```
|
|
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
|
-
|
|
158
|
-
### 💸 Gas Abstraction
|
|
159
|
-
|
|
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.
|
|
37
|
+
## Quick Start
|
|
161
38
|
|
|
162
39
|
```bash
|
|
163
|
-
#
|
|
164
|
-
npx starkfi@latest
|
|
165
|
-
|
|
166
|
-
# Developer pays all gas (gasfree mode)
|
|
167
|
-
npx starkfi@latest config set-gasfree on
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
| Mode | Who Pays | Gas Tokens | Description |
|
|
171
|
-
| --------------------- | --------- | -------------------------- | --------------------------------- |
|
|
172
|
-
| **Gasless** (default) | User | STRK, ETH, USDC, USDT, DAI | User pays in ERC-20 via Paymaster |
|
|
173
|
-
| **Gasfree** | Developer | — | Developer sponsors all gas |
|
|
40
|
+
# 1. Authenticate
|
|
41
|
+
npx starkfi@latest auth login user@example.com
|
|
42
|
+
npx starkfi@latest auth verify user@example.com <OTP_CODE>
|
|
174
43
|
|
|
175
|
-
|
|
44
|
+
# 2. Check balance
|
|
45
|
+
npx starkfi@latest balance
|
|
176
46
|
|
|
177
|
-
|
|
47
|
+
# 3. Swap tokens
|
|
48
|
+
npx starkfi@latest trade 100 USDC ETH --simulate # Preview
|
|
49
|
+
npx starkfi@latest trade 100 USDC ETH # Execute
|
|
178
50
|
|
|
179
|
-
|
|
180
|
-
npx starkfi@latest
|
|
181
|
-
# → mode: SIMULATION, estimatedFee: 0.054 STRK ($0.0024), callCount: 4
|
|
51
|
+
# 4. View portfolio
|
|
52
|
+
npx starkfi@latest portfolio
|
|
182
53
|
```
|
|
183
54
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
Consolidated view of all DeFi positions in one call.
|
|
55
|
+
→ **[Full Quick Start Guide](https://docs.starkfi.app/docs/quick-start)**
|
|
187
56
|
|
|
188
|
-
|
|
189
|
-
npx starkfi@latest portfolio
|
|
190
|
-
# → Token Balances (USD), Staking Positions, Lending Positions, Total Value
|
|
191
|
-
```
|
|
57
|
+
---
|
|
192
58
|
|
|
193
|
-
|
|
59
|
+
## What You Can Do
|
|
194
60
|
|
|
195
|
-
|
|
61
|
+
| Feature | CLI Example | Docs |
|
|
62
|
+
| --- | --- | --- |
|
|
63
|
+
| **Swap** | `trade 100 USDC ETH --provider auto` | [Trading](/docs/cli/trading) |
|
|
64
|
+
| **Multi-Swap** | `multi-swap "100 USDC>ETH, 50 DAI>STRK"` | [Trading](/docs/cli/trading) |
|
|
65
|
+
| **Batch** | `batch --swap "0.1 ETH USDC" --stake "50 STRK karnot"` | [Batch](/docs/cli/batch) |
|
|
66
|
+
| **Stake** | `stake 100 -v karnot` | [Staking](/docs/cli/staking) |
|
|
67
|
+
| **Lend** | `lend-supply 100 -p Prime -t USDC` | [Lending](/docs/cli/lending) |
|
|
68
|
+
| **DCA** | `dca-create 1000 USDC ETH --per-cycle 10 --frequency P1D` | [DCA](/docs/cli/dca) |
|
|
69
|
+
| **Confidential** | `conf-fund 100 --token USDC` | [Confidential](/docs/cli/confidential) |
|
|
70
|
+
| **Portfolio** | `portfolio-rebalance --target "50 ETH, 30 USDC, 20 STRK"` | [Portfolio](/docs/cli/portfolio) |
|
|
71
|
+
| **Gas Modes** | `config set-gasfree on` / `config set-gas-token USDC` | [Configuration](/docs/configuration) |
|
|
196
72
|
|
|
197
|
-
|
|
198
|
-
npx starkfi@latest portfolio-rebalance --target "50 ETH, 30 USDC, 20 STRK"
|
|
199
|
-
npx starkfi@latest portfolio-rebalance --target "60 ETH, 40 STRK" --simulate
|
|
200
|
-
```
|
|
73
|
+
→ **[Full CLI Reference (41 commands)](https://docs.starkfi.app/docs/cli)**
|
|
201
74
|
|
|
202
75
|
---
|
|
203
76
|
|
|
204
|
-
## AI Integration
|
|
77
|
+
## AI Integration
|
|
205
78
|
|
|
206
|
-
|
|
79
|
+
### MCP Server (42 Tools)
|
|
207
80
|
|
|
208
81
|
```bash
|
|
209
|
-
# Start the MCP server
|
|
210
82
|
npx starkfi@latest mcp-start
|
|
211
83
|
```
|
|
212
84
|
|
|
213
|
-
|
|
214
|
-
|
|
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 |
|
|
225
|
-
|
|
226
|
-
### Example — AI Agent Workflow
|
|
227
|
-
|
|
228
|
-
```
|
|
229
|
-
User: "Swap 100 USDC to STRK and stake half on Karnot"
|
|
230
|
-
|
|
231
|
-
Agent:
|
|
232
|
-
1. get_swap_quote(amount: "100", from: "USDC", to: "STRK") → 500 STRK
|
|
233
|
-
2. swap_tokens(amount: "100", from: "USDC", to: "STRK") → txHash: 0x...
|
|
234
|
-
3. stake_tokens(amount: "250", validator: "karnot", token: "STRK") → txHash: 0x...
|
|
235
|
-
```
|
|
236
|
-
|
|
237
|
-
### MCP Configuration
|
|
238
|
-
|
|
239
|
-
Add to your AI assistant's MCP config (Cursor, Claude, etc.):
|
|
85
|
+
Add to your AI client config (Cursor, Claude Desktop, Antigravity):
|
|
240
86
|
|
|
241
87
|
```json
|
|
242
88
|
{
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
89
|
+
"mcpServers": {
|
|
90
|
+
"starkfi": {
|
|
91
|
+
"command": "npx",
|
|
92
|
+
"args": ["-y", "starkfi@latest", "mcp-start"]
|
|
93
|
+
}
|
|
94
|
+
}
|
|
249
95
|
}
|
|
250
96
|
```
|
|
251
97
|
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
98
|
+
| Category | Tools | Count |
|
|
99
|
+
| --- | --- | --- |
|
|
100
|
+
| Auth & Config | `get_auth_status`, `config_action` | 2 |
|
|
101
|
+
| Wallet | `get_balance`, `get_portfolio`, `deploy_account`, `send_tokens`, `get_tx_status`, `rebalance_portfolio` | 6 |
|
|
102
|
+
| Trade | `get_swap_quote`, `swap_tokens`, `get_multi_swap_quote`, `multi_swap`, `batch_execute` | 5 |
|
|
103
|
+
| Staking | `list_validators`, `list_pools`, `get_staking_info`, `get_stake_status`, `stake_tokens`, `unstake_tokens`, `claim_rewards`, `compound_rewards` | 8 |
|
|
104
|
+
| Lending | `list_lending_pools`, `get_lending_position`, `supply_assets`, `withdraw_assets`, `borrow_assets`, `repay_debt`, `close_position`, `monitor_lending_position`, `auto_rebalance_lending`, `lending_quote_health` | 10 |
|
|
105
|
+
| DCA | `dca_preview`, `dca_create`, `dca_list`, `dca_cancel` | 4 |
|
|
106
|
+
| Confidential | `confidential_setup`, `confidential_balance`, `confidential_fund`, `confidential_transfer`, `confidential_withdraw`, `confidential_ragequit`, `confidential_rollover` | 7 |
|
|
257
107
|
|
|
258
|
-
|
|
108
|
+
→ **[Full MCP Documentation](https://docs.starkfi.app/docs/mcp)** · **[Tool Schemas (MCP.md)](MCP.md)**
|
|
259
109
|
|
|
260
|
-
|
|
261
|
-
| ---------------- | ----------------------------------------------------------------------------------- |
|
|
262
|
-
| **Auth** | `authenticate-wallet` |
|
|
263
|
-
| **Wallet Data** | `balance`, `portfolio` |
|
|
264
|
-
| **Transactions** | `send`, `trade`, `multi-swap`, `batch`, `staking`, `lending`, `dca`, `confidential` |
|
|
265
|
-
| **Utility** | `config` |
|
|
110
|
+
### Agent Skills (12 Workflows)
|
|
266
111
|
|
|
267
112
|
```bash
|
|
268
|
-
# Install skills for your AI assistant
|
|
269
113
|
npx skills add ahmetenesdur/starkfi
|
|
270
114
|
```
|
|
271
115
|
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
---
|
|
275
|
-
|
|
276
|
-
## Quick Start
|
|
277
|
-
|
|
278
|
-
### Prerequisites
|
|
279
|
-
|
|
280
|
-
- **Node.js** v18+
|
|
281
|
-
- **StarkFi Auth Server** running (required for Privy email OTP and Paymaster proxy)
|
|
282
|
-
|
|
283
|
-
### 1. Authenticate
|
|
284
|
-
|
|
285
|
-
```bash
|
|
286
|
-
npx starkfi@latest auth login user@example.com
|
|
287
|
-
npx starkfi@latest auth verify user@example.com <OTP_CODE>
|
|
288
|
-
```
|
|
289
|
-
|
|
290
|
-
### 2. Deploy Account
|
|
291
|
-
|
|
292
|
-
```bash
|
|
293
|
-
npx starkfi@latest deploy
|
|
294
|
-
```
|
|
295
|
-
|
|
296
|
-
### 3. Check Balance
|
|
297
|
-
|
|
298
|
-
```bash
|
|
299
|
-
npx starkfi@latest balance
|
|
300
|
-
```
|
|
301
|
-
|
|
302
|
-
### 4. Start Trading
|
|
303
|
-
|
|
304
|
-
```bash
|
|
305
|
-
npx starkfi@latest trade 10 STRK ETH --simulate # Preview first
|
|
306
|
-
npx starkfi@latest trade 10 STRK ETH # Execute
|
|
307
|
-
```
|
|
308
|
-
|
|
309
|
-
---
|
|
310
|
-
|
|
311
|
-
## Command Reference
|
|
312
|
-
|
|
313
|
-
### Session & Wallet
|
|
314
|
-
|
|
315
|
-
| Command | Description |
|
|
316
|
-
| --------------------------------------------------------- | -------------------------------- |
|
|
317
|
-
| `auth login <email>` | Start email OTP authentication |
|
|
318
|
-
| `auth verify <email> <code>` | Complete authentication |
|
|
319
|
-
| `auth logout` | Terminate session |
|
|
320
|
-
| `status` | Check auth status and API health |
|
|
321
|
-
| `address` | Display Starknet address |
|
|
322
|
-
| `deploy` | Deploy smart account on-chain |
|
|
323
|
-
| `balance [--token <symbol>] [--json]` | Query token balances |
|
|
324
|
-
| `send <amount> <token> <recipient> [--simulate] [--json]` | Transfer tokens |
|
|
325
|
-
| `portfolio [--json]` | Full DeFi portfolio |
|
|
326
|
-
|
|
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)
|
|
335
|
-
|
|
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 |
|
|
354
|
-
|
|
355
|
-
### Batching (Multicall)
|
|
356
|
-
|
|
357
|
-
| Command | Description |
|
|
358
|
-
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
|
|
359
|
-
| `batch [--simulate] --swap "..." --stake "..." --supply "..." --send "..." --borrow "..." --repay "..." --withdraw "..." --dca-create "..." --dca-cancel "..."` | Atomic multicall (min 2 ops) |
|
|
360
|
-
|
|
361
|
-
### Staking
|
|
362
|
-
|
|
363
|
-
| Command | Description |
|
|
364
|
-
| ----------------------------------------------------------------------------- | ---------------------- |
|
|
365
|
-
| `validators [--json]` | List active validators |
|
|
366
|
-
| `pools <validator> [--json]` | Show delegation pools |
|
|
367
|
-
| `stake <amount> --validator <name> [--token <symbol>] [--simulate] [--json]` | Stake tokens |
|
|
368
|
-
| `stake-status [validator] [--json]` | Staking dashboard |
|
|
369
|
-
| `rewards --validator <name> [--token <symbol>] <--claim\|--compound>` | Manage rewards |
|
|
370
|
-
| `unstake <intent\|exit> --validator <name> [--token <symbol>] [--amount <n>]` | Unstake (2-step) |
|
|
371
|
-
|
|
372
|
-
### Lending (Vesu V2)
|
|
373
|
-
|
|
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 |
|
|
385
|
-
|
|
386
|
-
### Portfolio
|
|
387
|
-
|
|
388
|
-
| Command | Description |
|
|
389
|
-
| ------------------------------------------------------------------------------------ | ------------------------------ |
|
|
390
|
-
| `portfolio [--json]` | Full DeFi dashboard |
|
|
391
|
-
| `portfolio-rebalance --target "<allocation>" [--slippage <%>] [--simulate] [--json]` | Rebalance to target allocation |
|
|
392
|
-
|
|
393
|
-
### Configuration
|
|
394
|
-
|
|
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 |
|
|
405
|
-
|
|
406
|
-
---
|
|
407
|
-
|
|
408
|
-
## Auth Server
|
|
409
|
-
|
|
410
|
-
StarkFi includes a dedicated **authentication server** (`server/`) built for secure, non-custodial wallet management.
|
|
411
|
-
|
|
412
|
-
### Route Groups
|
|
116
|
+
Pre-packaged multi-step workflows for AI coding assistants — authenticate, swap, stake, lend, DCA, batch, and more.
|
|
413
117
|
|
|
414
|
-
|
|
415
|
-
| ------------ | ------------------------------------------------- |
|
|
416
|
-
| `/auth` | Email OTP login and verification via Privy |
|
|
417
|
-
| `/wallet` | Wallet creation and address retrieval |
|
|
418
|
-
| `/sign` | Transaction signing via Privy TEE (non-custodial) |
|
|
419
|
-
| `/paymaster` | Paymaster proxy for gas abstraction |
|
|
118
|
+
→ **[Skills Documentation](https://docs.starkfi.app/docs/skills)**
|
|
420
119
|
|
|
421
|
-
###
|
|
120
|
+
### Telegram Bot
|
|
422
121
|
|
|
423
|
-
-
|
|
424
|
-
- **Secure headers** via `hono/secure-headers`
|
|
425
|
-
- **Body size limit** (1MB)
|
|
426
|
-
- **Request ID tracking** for observability
|
|
427
|
-
- **Graceful shutdown** (SIGTERM/SIGINT with 5s force-kill)
|
|
122
|
+
Chat-based DeFi via natural language with BYOAI model (OpenAI, Claude, Gemini).
|
|
428
123
|
|
|
429
|
-
|
|
124
|
+
→ **[Bot Setup](https://docs.starkfi.app/docs/integrations/telegram-bot)** · **[Repository](https://github.com/ahmetenesdur/starkfi-telegram-bot)**
|
|
430
125
|
|
|
431
126
|
---
|
|
432
127
|
|
|
433
|
-
##
|
|
128
|
+
## Architecture
|
|
434
129
|
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
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) |
|
|
449
|
-
|
|
450
|
-
```bash
|
|
451
|
-
git clone https://github.com/ahmetenesdur/starkfi-telegram-bot.git
|
|
452
|
-
cd starkfi-telegram-bot
|
|
453
|
-
pnpm install
|
|
454
|
-
cp .env.example .env # Configure TELEGRAM_BOT_TOKEN, BOT_ENCRYPTION_SECRET
|
|
455
|
-
pnpm dev
|
|
130
|
+
```
|
|
131
|
+
src/
|
|
132
|
+
├── commands/ # 12 command groups (41 commands)
|
|
133
|
+
├── services/ # 15 service modules
|
|
134
|
+
├── mcp/ # MCP server (42 tools, stdio transport)
|
|
135
|
+
├── lib/ # 15 shared utilities
|
|
136
|
+
skills/ # 12 agent skills
|
|
137
|
+
server/ # Auth server (Hono + Privy TEE)
|
|
138
|
+
docs/ # Documentation site (Fumadocs)
|
|
456
139
|
```
|
|
457
140
|
|
|
458
|
-
|
|
141
|
+
→ **[Architecture Deep Dive](https://docs.starkfi.app/docs/architecture)** · **[Security Model](https://docs.starkfi.app/docs/architecture/security)**
|
|
459
142
|
|
|
460
143
|
---
|
|
461
144
|
|
|
462
|
-
##
|
|
145
|
+
## Starkzap Modules
|
|
463
146
|
|
|
464
|
-
|
|
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 |
|
|
474
|
-
|
|
475
|
-
---
|
|
147
|
+
StarkFi leverages **all core Starkzap modules**:
|
|
476
148
|
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
|
482
|
-
|
|
|
483
|
-
| **
|
|
484
|
-
| **
|
|
485
|
-
| **
|
|
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` |
|
|
490
|
-
|
|
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.
|
|
492
|
-
|
|
493
|
-
### Readable Starknet Errors
|
|
494
|
-
|
|
495
|
-
Raw Starknet JSON-RPC errors (hex-encoded Cairo strings like `u256_sub Overflow`) are automatically parsed into human-readable messages (15 patterns):
|
|
496
|
-
|
|
497
|
-
| Raw Error | Displayed Message |
|
|
498
|
-
| ---------------------------------------- | --------------------------------------------------------------------------------------- |
|
|
499
|
-
| `u256_sub Overflow` | Insufficient balance — you don't have enough tokens (including gas fees) |
|
|
500
|
-
| `u256_add Overflow` | Amount overflow — the value is too large |
|
|
501
|
-
| `ERC20: transfer amount exceeds balance` | Insufficient token balance for this transfer |
|
|
502
|
-
| `ERC20: burn amount exceeds balance` | Insufficient token balance to burn |
|
|
503
|
-
| `ERC20: insufficient allowance` | Token approval required — not enough allowance for this operation |
|
|
504
|
-
| `argent/multicall-failed` | One or more calls in the transaction failed |
|
|
505
|
-
| `argent/invalid-signature` | Invalid signature — try re-authenticating with: starkfi auth login |
|
|
506
|
-
| `argent/invalid-timestamp` | Transaction expired — please retry |
|
|
507
|
-
| `is_valid_signature` | Signature validation failed — try re-authenticating |
|
|
508
|
-
| `assert_not_zero` | Operation failed — a required value was zero |
|
|
509
|
-
| `Contract not found` | Contract not found — the target contract does not exist on this network |
|
|
510
|
-
| `UNAUTHORIZED` | Unauthorized — session may have expired, try: starkfi auth login |
|
|
511
|
-
| `nonce` | Transaction nonce error — please retry |
|
|
512
|
-
| `dusty-collateral-balance` | Collateral amount is below the pool's minimum (dust limit). Please increase the amount. |
|
|
513
|
-
| `dusty-debt-balance` | Borrow amount is below the pool's minimum (dust limit). Please increase the amount. |
|
|
514
|
-
|
|
515
|
-
This applies to both CLI output (`formatError`) and MCP responses (`withErrorHandling`).
|
|
149
|
+
| Module | Usage |
|
|
150
|
+
| --- | --- |
|
|
151
|
+
| **Wallets** | `OnboardStrategy.Privy` + `argentXV050` for email-based wallet onboarding |
|
|
152
|
+
| **Paymaster** | Gas abstraction with 5 tokens + developer-sponsored gasfree mode |
|
|
153
|
+
| **Staking** | Multi-token lifecycle (STRK, WBTC, tBTC, SolvBTC, LBTC) |
|
|
154
|
+
| **DCA** | Recurring buy orders via AVNU and Ekubo |
|
|
155
|
+
| **TxBuilder** | Atomic multicall batching (swap + stake + lend + send + DCA) |
|
|
156
|
+
| **Confidential** | Privacy-preserving transfers via Tongo Cash (ZK proofs) |
|
|
157
|
+
| **ERC-20** | Token presets, balance queries, transfers, approvals |
|
|
516
158
|
|
|
517
159
|
---
|
|
518
160
|
|
|
519
161
|
## Development
|
|
520
162
|
|
|
521
|
-
### Setup
|
|
522
|
-
|
|
523
163
|
```bash
|
|
524
164
|
git clone https://github.com/ahmetenesdur/starkfi.git
|
|
525
165
|
cd starkfi
|
|
526
166
|
pnpm install
|
|
527
|
-
```
|
|
528
|
-
|
|
529
|
-
### Build
|
|
530
|
-
|
|
531
|
-
```bash
|
|
532
|
-
pnpm build # Compile TypeScript → dist/
|
|
533
|
-
```
|
|
534
|
-
|
|
535
|
-
### Dev Mode
|
|
536
167
|
|
|
537
|
-
|
|
538
|
-
pnpm dev -- --help
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
### Lint & Format
|
|
542
|
-
|
|
543
|
-
```bash
|
|
544
|
-
pnpm lint # ESLint
|
|
545
|
-
pnpm format # Prettier
|
|
168
|
+
pnpm build # Compile TypeScript → dist/
|
|
169
|
+
pnpm dev -- --help # Run with tsx (hot-reload)
|
|
170
|
+
pnpm lint # ESLint
|
|
171
|
+
pnpm format # Prettier
|
|
546
172
|
```
|
|
547
173
|
|
|
548
174
|
### Auth Server
|
|
549
175
|
|
|
550
176
|
```bash
|
|
551
|
-
cd server
|
|
552
|
-
pnpm install
|
|
553
|
-
cp .env.example .env # Configure environment
|
|
554
|
-
pnpm dev
|
|
177
|
+
cd server && pnpm install && cp .env.example .env && pnpm dev
|
|
555
178
|
```
|
|
556
179
|
|
|
180
|
+
→ **[Development Guide](https://docs.starkfi.app/docs/architecture/contributing)**
|
|
181
|
+
|
|
557
182
|
---
|
|
558
183
|
|
|
559
184
|
## Contributing
|
|
560
185
|
|
|
561
|
-
Contributions are welcome! Here's how to get started:
|
|
562
|
-
|
|
563
186
|
1. **Fork** the repository and create a feature branch
|
|
564
187
|
2. **Install** dependencies: `pnpm install`
|
|
565
|
-
3. **
|
|
566
|
-
4. **
|
|
567
|
-
5. **Submit** a pull request with a clear description
|
|
188
|
+
3. **Build** and verify: `pnpm build && pnpm lint`
|
|
189
|
+
4. **Submit** a pull request with a clear description
|
|
568
190
|
|
|
569
|
-
For
|
|
191
|
+
For bugs and feature requests, [open an issue](https://github.com/ahmetenesdur/starkfi/issues).
|
|
570
192
|
|
|
571
193
|
## License
|
|
572
194
|
|