starkfi 0.4.4 → 0.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "starkfi",
-	"version": "0.4.4",
-	"description": "AI-native Starknet DeFi CLI + MCP Server + Agent Skills — Swaps, multi-swap, batch (multicall), staking, lending, simulation, portfolio, gas abstraction",
+	"version": "0.6.0",
+	"description": "AI-native Starknet DeFi CLI + MCP Server + Agent Skills — Swaps, multi-swap, batch (multicall), staking, lending, DCA, confidential transfers, simulation, portfolio, gas abstraction",
 	"type": "module",
 	"bin": {
 		"starkfi": "./dist/index.js"
@@ -19,7 +19,7 @@
 	],
 	"scripts": {
 		"build": "tsup",
-		"dev": "node --import tsx/esm src/index.ts",
+		"dev": "tsx --import ./scripts/stub-peers-loader.mjs src/index.ts",
 		"typecheck": "tsc --noEmit",
 		"lint": "eslint src/",
 		"lint:fix": "eslint src/ --fix",
@@ -48,6 +48,9 @@
 		"lending",
 		"gasless",
 		"gas-abstraction",
+		"dca",
+		"confidential",
+		"tongo",
 		"vesu",
 		"fibrous",
 		"web3",
@@ -66,9 +69,10 @@
 	"engines": {
 		"node": ">=18"
 	},
-	"dependencies": {},
 	"pnpm": {
-		"onlyBuiltDependencies": ["esbuild"]
+		"onlyBuiltDependencies": [
+			"esbuild"
+		]
 	},
 	"devDependencies": {
 		"@eslint/js": "^10.0.1",
@@ -77,17 +81,20 @@
 		"chalk": "^5.6.2",
 		"commander": "^14.0.3",
 		"env-paths": "^3.0.0",
-		"eslint": "^10.0.3",
+		"eslint": "^10.1.0",
 		"eslint-config-prettier": "^10.1.8",
 		"globals": "^17.4.0",
 		"jiti": "^2.6.1",
 		"ora": "^9.3.0",
 		"prettier": "^3.8.1",
-		"starkzap": "^1.0.0",
+		"starkzap": "^2.0.0",
 		"tsup": "^8.5.1",
 		"tsx": "^4.21.0",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.57.0",
+		"typescript-eslint": "^8.57.2",
 		"zod": "^4.3.6"
+	},
+	"dependencies": {
+		"@fatsolutions/tongo-sdk": "^1.3.2"
 	}
 }

package/skills/README.md

@@ -9,12 +9,14 @@ Agent Skills for the [StarkFi](https://github.com/ahmetenesdur/starkfi) CLI —
 | [authenticate-wallet](./authenticate-wallet/SKILL.md) | auth        | Email OTP login, session management, wallet deploy                |
 | [balance](./balance/SKILL.md)                         | wallet-data | Check STRK, ETH, and ERC-20 token balances                        |
 | [send](./send/SKILL.md)                               | transaction | Transfer tokens to a Starknet address                             |
-| [trade](./trade/SKILL.md)                             | transaction | Swap tokens via Fibrous aggregation                               |
+| [trade](./trade/SKILL.md)                             | transaction | Swap tokens via Fibrous (default), AVNU, or Ekubo         |
 | [multi-swap](./multi-swap/SKILL.md)                   | transaction | Multiple swaps in one transaction (up to 3)                       |
-| [batch](./batch/SKILL.md)                             | transaction | Combine swap + stake + supply + send in one multicall             |
+| [batch](./batch/SKILL.md)                             | transaction | Combine swap + stake + supply + send + borrow + repay + withdraw + DCA in one multicall |
 | [staking](./staking/SKILL.md)                         | transaction | Stake, unstake, claim, compound (STRK, WBTC, tBTC, SolvBTC, LBTC) |
-| [lending](./lending/SKILL.md)                         | transaction | Vesu V2 lending: supply, borrow, repay, withdraw, close           |
-| [portfolio](./portfolio/SKILL.md)                     | wallet-data | Aggregated DeFi dashboard with USD valuations                     |
+| [lending](./lending/SKILL.md)                         | transaction | Vesu V2 lending: supply, borrow, repay, monitor, auto-rebalance |
+| [dca](./dca/SKILL.md)                                 | transaction | Dollar-Cost Averaging: create, preview, list, cancel recurring orders |
+| [confidential](./confidential/SKILL.md)               | transaction | Tongo Cash: fund, transfer, withdraw, ragequit, rollover (ZK privacy) |
+| [portfolio](./portfolio/SKILL.md)                     | wallet-data | DeFi dashboard + portfolio optimization via rebalancing           |
 | [config](./config/SKILL.md)                           | utility     | RPC, network, gas settings, transaction status                    |
 
 ## Installation
@@ -36,7 +38,7 @@ npx skills add ahmetenesdur/starkfi
 
 1. **Authenticate** → `authenticate-wallet` (required first)
 2. **Check funds** → `balance` or `portfolio`
-3. **Execute** → `send`, `trade`, `multi-swap`, `batch`, `staking`, or `lending`
+3. **Execute** → `send`, `trade`, `multi-swap`, `batch`, `staking`, `lending`, `dca`, or `confidential`
 4. **Verify** → `tx-status` (via `config` skill)
 
 ## Trigger Examples
@@ -49,10 +51,19 @@ npx skills add ahmetenesdur/starkfi
 | "Swap 100 USDC for ETH"             | `trade`               |
 | "Swap USDC to ETH and USDT to STRK" | `multi-swap`          |
 | "Swap ETH and then stake STRK"      | `batch`               |
+| "Withdraw from lending and swap"    | `batch`               |
 | "Stake 1000 STRK with Karnot"       | `staking`             |
 | "Supply 500 USDC to Prime pool"     | `lending`             |
+| "Is my position safe?"              | `lending`             |
+| "Fix my risky position"             | `lending`             |
 | "Show me my portfolio"              | `portfolio`           |
+| "Rebalance to 50% ETH, 30% USDC"   | `portfolio`           |
+| "DCA 100 USDC into ETH daily"       | `dca`                 |
+| "Show my active DCA orders"         | `dca`                 |
 | "I'm getting rate limit errors"     | `config`              |
+| "Set up my Tongo account"           | `confidential`        |
+| "Fund 100 USDC confidentially"      | `confidential`        |
+| "Send 50 privately"                 | `confidential`        |
 
 ## License
 

package/skills/balance/SKILL.md

@@ -77,4 +77,6 @@ npx starkfi@latest balance --json
 - Run this BEFORE `send` or `trade` to verify sufficient funds.
 - Run this BEFORE `staking` to confirm available STRK/BTC tokens.
 - Run this BEFORE `lending` supply operations to confirm available assets.
+- Run this BEFORE `dca` to verify sufficient sell token balance for the total DCA amount.
+- Run this BEFORE `confidential` `conf-fund` to verify sufficient tokens for funding the confidential account.
 - Use `portfolio` for a complete view including staking and lending positions with USD values.

package/skills/batch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: batch
-description: Execute multiple different DeFi operations in a single Starknet transaction — combine swaps, staking, lending supply, and token sends into one multicall. Use this skill when the user wants to batch, combine, bundle, or chain multiple diverse operations together in one atomic transaction, such as "swap ETH and then stake STRK" or "swap and send in one go". Also trigger when the user mentions multicall, combining operations, doing multiple things at once, or wants to save gas by bundling actions — even if they don't use the word "batch".
+description: Execute multiple different DeFi operations in a single Starknet transaction — combine swaps, staking, lending supply/borrow/repay/withdraw, token sends, and DCA orders into one multicall. Use this skill when the user wants to batch, combine, bundle, or chain multiple diverse operations together in one atomic transaction, such as "swap ETH and then stake STRK" or "withdraw from lending and swap" or "repay debt and stake" or "swap and send in one go" or "create a DCA order and stake". Also trigger when the user mentions multicall, combining operations, doing multiple things at once, or wants to save gas by bundling actions — even if they don't use the word "batch".
 license: MIT
 compatibility: Requires Node.js 18+ and npx.
 metadata:
@@ -17,7 +17,7 @@ allowed-tools:
 
 # Batch Execute
 
-Bundle multiple diverse DeFi operations into a single Starknet multicall transaction. Supports combining **swaps**, **staking**, **lending supply**, and **token sends** — all executed atomically in one on-chain call.
+Bundle multiple diverse DeFi operations into a single Starknet multicall transaction. Supports combining **swaps**, **staking**, **lending supply/borrow/repay/withdraw**, **token sends**, and **DCA orders** — all executed atomically in one on-chain call.
 
 ## Prerequisites
 
@@ -28,8 +28,8 @@ Bundle multiple diverse DeFi operations into a single Starknet multicall transac
 ## Rules
 
 1. BEFORE any batch, you MUST run `npx starkfi@latest status` and `npx starkfi@latest balance` to verify connectivity and funds.
-2. A batch MUST include at least **2 operations**. For single operations, use the dedicated skill (`trade`, `send`, `staking`, or `lending`).
-3. Each `--swap`, `--stake`, `--supply`, and `--send` flag can appear **multiple times** (repeatable).
+2. A batch MUST include at least **2 operations**. For single operations, use the dedicated skill (`trade`, `send`, `staking`, `lending`, or `dca`).
+3. Each `--swap`, `--stake`, `--supply`, `--send`, `--dca-create`, and `--dca-cancel` flag can appear **multiple times** (repeatable).
 4. If the batch includes a `--send` operation, you MUST confirm the recipient address with the user before executing.
 5. Suggest using `--simulate` first to verify the entire batch would succeed.
 6. AFTER a successful batch, verify with `npx starkfi@latest tx-status <hash>`.
@@ -41,8 +41,13 @@ Bundle multiple diverse DeFi operations into a single Starknet multicall transac
 npx starkfi@latest batch [--simulate] [--json] \
   --swap "<amount> <from> <to>" \
   --stake "<amount> <token> <validator_or_pool>" \
-  --supply "<amount> <token> <pool_address>" \
-  --send "<amount> <token> <recipient>"
+  --supply "<amount> <token> <pool>" \
+  --send "<amount> <token> <recipient>" \
+  --borrow "<col_amt> <col_token> <bor_amt> <bor_token> <pool>" \
+  --repay "<amount> <token> <col_token> <pool>" \
+  --withdraw "<amount> <token> <pool>" \
+  --dca-create "<amount> <sell> <buy> <perCycle> [frequency]" \
+  --dca-cancel "<orderId>"
 ```
 
 ## Operation Formats
@@ -51,8 +56,13 @@ npx starkfi@latest batch [--simulate] [--json] \
 | ---------- | ------------------------------------------ | ------------------------------- |
 | `--swap`   | `"<amount> <from> <to>"`                   | `--swap "100 USDC ETH"`         |
 | `--stake`  | `"<amount> <token> <validator_or_0xPool>"` | `--stake "500 STRK Karnot"`     |
-| `--supply` | `"<amount> <token> <0xPool>"`              | `--supply "100 USDC 0x04a3..."` |
-| `--send`   | `"<amount> <token> <0xRecipient>"`         | `--send "10 STRK 0x07b2..."`    |
+| `--supply` | `"<amount> <token> <pool>"`                | `--supply "100 USDC Prime"`     |
+| `--send`       | `"<amount> <token> <0xRecipient>"`         | `--send "10 STRK 0x07b2..."`    |
+| `--borrow`     | `"<col_amt> <col_token> <bor_amt> <bor_token> <pool>"` | `--borrow "0.5 ETH 500 USDC Prime"` |
+| `--repay`      | `"<amount> <token> <col_token> <pool>"`    | `--repay "100 USDC ETH Prime"`  |
+| `--withdraw`   | `"<amount> <token> <pool>"`                | `--withdraw "200 USDC Prime"`   |
+| `--dca-create` | `"<amount> <sell> <buy> <perCycle> [freq]"` | `--dca-create "1000 USDC ETH 10 P1D"` |
+| `--dca-cancel` | `"<orderId>"`                              | `--dca-cancel "abc123"`         |
 
 > **Note:** `--stake` accepts either a validator name (e.g. `Karnot`) or a pool contract address (starting with `0x`). The CLI auto-detects the format.
 
@@ -63,7 +73,12 @@ npx starkfi@latest batch [--simulate] [--json] \
 | `--swap`     | string | Swap operation (repeatable)           | No\*     |
 | `--stake`    | string | Stake operation (repeatable)          | No\*     |
 | `--supply`   | string | Lending supply operation (repeatable) | No\*     |
-| `--send`     | string | Token transfer operation (repeatable) | No\*     |
+| `--send`       | string | Token transfer operation (repeatable) | No\*     |
+| `--borrow`     | string | Borrow from lending pool (repeatable) | No\*     |
+| `--repay`      | string | Repay lending debt (repeatable)       | No\*     |
+| `--withdraw`   | string | Withdraw from lending pool (repeatable) | No\*   |
+| `--dca-create` | string | Create DCA order (repeatable)         | No\*     |
+| `--dca-cancel` | string | Cancel DCA order (repeatable)         | No\*     |
 | `--simulate` | flag   | Estimate fees without broadcasting    | No       |
 | `--json`     | flag   | Output as JSON                        | No       |
 
@@ -80,15 +95,32 @@ npx starkfi@latest batch --swap "100 USDC ETH" --stake "500 STRK Karnot"
 npx starkfi@latest tx-status <hash>
 ```
 
-**User:** "Batch: swap 50 USDT to STRK, supply 100 USDC and send 10 STRK"
+**User:** "Withdraw my USDC from Prime lending and swap it to ETH"
+
+```bash
+npx starkfi@latest status
+npx starkfi@latest balance
+npx starkfi@latest batch --withdraw "200 USDC Prime" --swap "200 USDC ETH"
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "Repay my USDC debt on Prime and stake STRK"
+
+```bash
+npx starkfi@latest status
+npx starkfi@latest balance
+npx starkfi@latest batch --repay "100 USDC ETH Prime" --stake "50 STRK karnot"
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "Borrow USDC using ETH as collateral and swap half to STRK"
 
 ```bash
 npx starkfi@latest status
 npx starkfi@latest balance
 npx starkfi@latest batch \
-  --swap "50 USDT STRK" \
-  --supply "100 USDC 0x04a3..." \
-  --send "10 STRK 0x07b2..."
+  --borrow "0.5 ETH 500 USDC Prime" \
+  --swap "250 USDC STRK"
 npx starkfi@latest tx-status <hash>
 ```
 
@@ -117,3 +149,4 @@ npx starkfi@latest batch --simulate \
 - Use `staking` for standalone staking operations.
 - Use `lending` for standalone lending operations.
 - Use `send` for standalone token transfers.
+- Use `dca` for standalone DCA order management.

package/skills/confidential/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: confidential
+description: Manage confidential (private) transfers via Tongo Cash on Starknet — setup, fund, transfer, withdraw, ragequit, rollover using ZK proofs. Use this skill when the user wants to send tokens privately, hide transfer amounts, use zero-knowledge proofs, set up Tongo, fund or withdraw from a confidential account, perform an emergency exit (ragequit), or activate pending balance (rollover). Also trigger when the user says "send privately", "confidential transfer", "hide my transaction", "Tongo Cash", "ZK transfer", or any variation about privacy-preserving transfers — even if they don't use the word "confidential".
+license: MIT
+compatibility: Requires Node.js 18+ and npx.
+metadata:
+    version: 0.1.0
+    author: ahmetenesdur
+    category: transaction
+allowed-tools:
+    - Bash(npx starkfi@latest conf-setup *)
+    - Bash(npx starkfi@latest conf-balance)
+    - Bash(npx starkfi@latest conf-balance *)
+    - Bash(npx starkfi@latest conf-fund *)
+    - Bash(npx starkfi@latest conf-transfer *)
+    - Bash(npx starkfi@latest conf-withdraw *)
+    - Bash(npx starkfi@latest conf-ragequit)
+    - Bash(npx starkfi@latest conf-ragequit *)
+    - Bash(npx starkfi@latest conf-rollover)
+    - Bash(npx starkfi@latest conf-rollover *)
+    - Bash(npx starkfi@latest status)
+    - Bash(npx starkfi@latest balance)
+    - Bash(npx starkfi@latest balance *)
+    - Bash(npx starkfi@latest tx-status *)
+---
+
+# Confidential Transfers (Tongo Cash)
+
+Privacy-preserving token transfers using ZK proofs on Starknet. Amounts are hidden on-chain; recipients are identified by elliptic curve public keys, not Starknet addresses.
+
+## Prerequisites
+
+- Active session required. If not authenticated, run `authenticate-wallet` skill first.
+- Tongo credentials configured (`conf-setup`). Must be done once before any other confidential command.
+- Sufficient public token balance for `conf-fund` operations.
+
+## Rules
+
+1. BEFORE any confidential operation, run `npx starkfi@latest status` to verify authentication.
+2. `conf-setup` MUST be called before any other confidential command. It only needs to run once.
+3. BEFORE `conf-fund`, check `balance` to verify sufficient public token balance.
+4. BEFORE `conf-transfer` or `conf-withdraw`, check `conf-balance` to verify sufficient active balance.
+5. After the recipient receives a transfer, remind them to run `conf-rollover` to activate pending balance.
+6. `conf-ragequit` is a DESTRUCTIVE operation — it empties the entire confidential balance. Always warn the user and get explicit confirmation.
+7. AFTER any transactional operation (`conf-fund`, `conf-transfer`, `conf-withdraw`, `conf-ragequit`, `conf-rollover`), verify with `tx-status`.
+8. The Tongo private key is stored locally at `~/.local/share/starkfi/confidential.json` with strict `0o600` permissions and is **never sent to the network**.
+
+## Setup (One-Time)
+
+```bash
+npx starkfi@latest conf-setup --key <TONGO_PRIVATE_KEY> --contract 0x1234…
+```
+
+## Commands
+
+### Check Balance
+
+```bash
+npx starkfi@latest conf-balance [--json]
+```
+
+Returns: active balance, pending balance, nonce, Tongo address.
+
+### Fund Confidential Account
+
+Move public ERC-20 tokens into a private confidential balance.
+
+```bash
+npx starkfi@latest conf-fund <amount> [--token <symbol>] [--simulate] [--json]
+```
+
+### Transfer Confidentially
+
+Send tokens privately to another Tongo account. Recipient is identified by their public key coordinates (x, y).
+
+```bash
+npx starkfi@latest conf-transfer <amount> --recipient-x <x> --recipient-y <y> [--token <symbol>] [--simulate] [--json]
+```
+
+### Withdraw to Public
+
+Convert private balance back to public ERC-20 tokens.
+
+```bash
+npx starkfi@latest conf-withdraw <amount> [--to <address>] [--token <symbol>] [--simulate] [--json]
+```
+
+### Ragequit (Emergency Exit)
+
+Withdraw the entire confidential balance to a public address immediately.
+
+```bash
+npx starkfi@latest conf-ragequit [--to <address>] [--json]
+```
+
+### Rollover (Activate Pending)
+
+Received transfers start as "pending" and must be rolled over to become spendable.
+
+```bash
+npx starkfi@latest conf-rollover [--json]
+```
+
+## Parameters
+
+| Parameter        | Type   | Description                              | Required   |
+| ---------------- | ------ | ---------------------------------------- | ---------- |
+| `amount`         | number | Amount for fund/transfer/withdraw        | Yes        |
+| `--key`          | string | Tongo private key (setup only)           | Yes (setup)|
+| `--contract`     | string | Tongo contract address                   | Yes (setup)|
+| `--recipient-x`  | string | Recipient public key X coordinate        | Yes (transfer) |
+| `--recipient-y`  | string | Recipient public key Y coordinate        | Yes (transfer) |
+| `--token`        | string | Token symbol (default: `USDC`)           | No         |
+| `--to`           | string | Recipient Starknet address               | No         |
+| `--simulate`     | flag   | Estimate fees without broadcasting       | No         |
+| `--json`         | flag   | Output as JSON                           | No         |
+
+## Examples
+
+**User:** "Set up my Tongo account"
+
+```bash
+npx starkfi@latest conf-setup --key <KEY> --contract 0x1234…
+```
+
+**User:** "Fund 100 USDC into my confidential account"
+
+```bash
+npx starkfi@latest status
+npx starkfi@latest balance --token USDC
+npx starkfi@latest conf-fund 100 --token USDC --simulate
+npx starkfi@latest conf-fund 100 --token USDC
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "Send 50 privately to this public key"
+
+```bash
+npx starkfi@latest conf-balance
+npx starkfi@latest conf-transfer 50 --recipient-x 0xABC --recipient-y 0xDEF --simulate
+npx starkfi@latest conf-transfer 50 --recipient-x 0xABC --recipient-y 0xDEF
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "Withdraw 100 from my confidential account"
+
+```bash
+npx starkfi@latest conf-balance
+npx starkfi@latest conf-withdraw 100 --simulate
+npx starkfi@latest conf-withdraw 100
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "Emergency withdraw everything"
+
+```bash
+# WARN: This empties the entire confidential balance
+npx starkfi@latest conf-ragequit
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "Activate my pending balance"
+
+```bash
+npx starkfi@latest conf-rollover
+npx starkfi@latest tx-status <hash>
+```
+
+## Error Handling
+
+| Error                           | Action                                                     |
+| ------------------------------- | ---------------------------------------------------------- |
+| `CONFIDENTIAL_NOT_CONFIGURED`   | Run `conf-setup` with valid Tongo key and contract address.|
+| `CONFIDENTIAL_FAILED`           | Check balance, credentials, and retry.                     |
+| `Insufficient balance`          | Check `conf-balance` for active balance before operations. |
+| `Not authenticated`             | Run `authenticate-wallet` skill first.                     |
+
+## Related Skills
+
+- Use `authenticate-wallet` to ensure an active session before confidential operations.
+- Use `balance` to verify public token balance before funding.
+- Use `send` for standard (non-private) token transfers.
+- Use `config` to set a custom RPC if experiencing rate limits.

package/skills/config/SKILL.md

@@ -19,7 +19,7 @@ Manage local configuration for the StarkFi CLI and check transaction status on-c
 ## Prerequisites
 
 - None for configuration commands (`config list`, `config set-*`, `config get-rpc`).
-- Active session required for `tx-status` (it reads the network from the session).
+- Active session required for `tx-status` and for `config list` to show the effective network source.
 
 ## Configuration Commands
 
@@ -36,7 +36,7 @@ npx starkfi@latest config set-rpc <url>
 # Get current RPC URL
 npx starkfi@latest config get-rpc
 
-# Switch network
+# Switch network (takes effect immediately, no re-login needed)
 npx starkfi@latest config set-network <network>
 
 # Toggle developer-sponsored gas (Gasfree mode)
@@ -81,8 +81,9 @@ Gasfree and Gasless are mutually exclusive — enabling one disables the other.
 
 1. **Rate Limits**: If any skill fails with "rate limit" or "429" errors, use `config set-rpc` to set a custom RPC endpoint.
 2. **Persistence**: Settings are stored locally and persist across sessions.
-3. Use `tx-status` AFTER every `send`, `trade`, `multi-swap`, `batch`, and staking/lending transaction to verify success.
-4. Use `config get-rpc` to check the current RPC URL before changing it.
+3. **Network switching**: `set-network` takes effect instantly for all commands — no re-login required. The config setting overrides the session's login network. `config list` shows the effective network with its source (e.g. `sepolia (config override, session: mainnet)`).
+4. Use `tx-status` AFTER every `send`, `trade`, `multi-swap`, `batch`, `dca-create`, `dca-cancel`, `conf-fund`, `conf-transfer`, `conf-withdraw`, and staking/lending transaction to verify success.
+5. Use `config get-rpc` to check the current RPC URL before changing it.
 
 ## Examples
 
@@ -103,6 +104,7 @@ npx starkfi@latest config list
 
 ```bash
 npx starkfi@latest config set-network sepolia
+npx starkfi@latest config list    # Verify: shows "sepolia (config override, session: mainnet)"
 ```
 
 **User:** "Enable free gas mode"

package/skills/dca/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: dca
+description: Create, preview, list, and cancel recurring Dollar-Cost Averaging (DCA) buy orders on Starknet via AVNU or Ekubo. Use this skill when the user wants to set up automatic recurring purchases, dollar cost average into a token, create a DCA order, schedule periodic buys, or manage existing DCA orders — even if they don't use the term "DCA" explicitly.
+license: MIT
+compatibility: Requires Node.js 18+ and npx.
+metadata:
+    version: 0.1.0
+    author: ahmetenesdur
+    category: transaction
+allowed-tools:
+    - Bash(npx starkfi@latest dca-create *)
+    - Bash(npx starkfi@latest dca-list *)
+    - Bash(npx starkfi@latest dca-cancel *)
+    - Bash(npx starkfi@latest dca-preview *)
+    - Bash(npx starkfi@latest status)
+    - Bash(npx starkfi@latest balance)
+    - Bash(npx starkfi@latest balance *)
+    - Bash(npx starkfi@latest tx-status *)
+---
+
+# Dollar-Cost Averaging (DCA)
+
+Create recurring buy orders that automatically swap a fixed amount of one token into another at regular intervals. Supports AVNU and Ekubo DCA providers.
+
+## Prerequisites
+
+- Active session required.
+- Sufficient balance of the sell token for the total DCA amount.
+- Account must be deployed on-chain.
+
+## Rules
+
+1. BEFORE any DCA operation, you MUST run `npx starkfi@latest status` and `npx starkfi@latest balance` to verify connectivity and funds.
+2. ALWAYS run `dca-preview` before `dca-create` to verify the expected output per cycle.
+3. The `--per-cycle` flag is **required** for `dca-create`. It sets the amount sold each execution cycle.
+4. Frequency uses ISO 8601 duration format: `P1D` (daily), `PT12H` (12 hours), `P1W` (weekly).
+5. Suggest using `--simulate` first to verify the DCA order would succeed.
+6. AFTER a successful creation, verify with `npx starkfi@latest tx-status <hash>`.
+
+## Commands
+
+### Preview a Cycle
+
+```bash
+npx starkfi@latest dca-preview <amount> <sell_token> <buy_token> [--provider <avnu|ekubo>] [--json]
+```
+
+### Create a DCA Order
+
+```bash
+npx starkfi@latest dca-create <total_amount> <sell_token> <buy_token> \
+  --per-cycle <amount> \
+  [--frequency <duration>] \
+  [--provider <avnu|ekubo>] \
+  [--simulate] [--json]
+```
+
+### List DCA Orders
+
+```bash
+npx starkfi@latest dca-list [--status <ACTIVE|CLOSED|INDEXING>] [--provider <avnu|ekubo>] [--page <n>] [--json]
+```
+
+### Cancel a DCA Order
+
+```bash
+npx starkfi@latest dca-cancel <order_id> [--provider <avnu|ekubo>] [--json]
+```
+
+## Parameters
+
+| Parameter     | Type   | Description                                  | Required |
+| ------------- | ------ | -------------------------------------------- | -------- |
+| `amount`      | string | Total sell amount (create) or per-cycle amount (preview) | **Yes** |
+| `sell_token`  | string | Token to sell (e.g. `STRK`, `ETH`)           | **Yes**  |
+| `buy_token`   | string | Token to buy (e.g. `USDC`, `ETH`)            | **Yes**  |
+| `--per-cycle` | string | Amount to sell per cycle                      | **Yes** (create) |
+| `--frequency` | string | ISO 8601 duration (default: `P1D`=daily)     | No       |
+| `--provider`  | string | DCA provider: `avnu` (default) or `ekubo`    | No       |
+| `--status`    | string | Filter orders: `ACTIVE`, `CLOSED`, `INDEXING` | No (list) |
+| `--simulate`  | flag   | Estimate fees without broadcasting           | No       |
+| `--json`      | flag   | Output as JSON                               | No       |
+
+## Examples
+
+**User:** "Buy 10 USDC worth of ETH every day for 100 days"
+
+```bash
+npx starkfi@latest status
+npx starkfi@latest balance
+npx starkfi@latest dca-preview 10 USDC ETH
+npx starkfi@latest dca-create 1000 USDC ETH --per-cycle 10 --frequency P1D --simulate
+npx starkfi@latest dca-create 1000 USDC ETH --per-cycle 10 --frequency P1D
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "DCA into STRK weekly with 50 USDC per week, total 200 USDC"
+
+```bash
+npx starkfi@latest status
+npx starkfi@latest balance
+npx starkfi@latest dca-preview 50 USDC STRK
+npx starkfi@latest dca-create 200 USDC STRK --per-cycle 50 --frequency P1W
+```
+
+**User:** "Show my active DCA orders"
+
+```bash
+npx starkfi@latest dca-list --status ACTIVE --json
+```
+
+**User:** "Cancel my DCA order"
+
+```bash
+npx starkfi@latest dca-list --status ACTIVE
+npx starkfi@latest dca-cancel <order_id>
+npx starkfi@latest tx-status <hash>
+```
+
+## Error Handling
+
+| Error                  | Action                                                     |
+| ---------------------- | ---------------------------------------------------------- |
+| `DCA_FAILED`           | Check the error message for details (balance, provider).   |
+| `Insufficient balance` | Check `balance` for the sell token.                        |
+| `Not authenticated`    | Run `authenticate-wallet` skill first.                     |
+| `Invalid frequency`    | Use ISO 8601 format: `P1D`, `PT12H`, `P1W`, `P1M`.        |
+
+## Related Skills
+
+- Use `trade` for a one-time swap instead of recurring.
+- Use `batch` to combine a DCA creation with other operations.
+- Use `portfolio` to check your overall positions and balances.