npx starkfi --help

Why StarkFi?

Most DeFi tools are built for humans clicking buttons. StarkFi is built for agents.

• 🤖 27 MCP tools — Any AI assistant (Cursor, Claude, Antigravity) can execute DeFi operations autonomously
• ⚡ Atomic Batching — Combine swap + stake + lend + send into a single multicall transaction
• 💸 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)
• 📊 Full Portfolio — Unified view of balances, staking positions, and lending positions with USD values
• 🧪 Simulate Everything — Dry-run any transaction to estimate fees before broadcasting

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                           StarkFi                                    │
│                                                                      │
│  ┌─────────────┐     ┌─────────────────────────────────────────┐     │
│  │   CLI (25+   │     │         MCP Server (27 tools)           │     │
│  │   commands)  │     │  AI agents connect via stdio transport  │     │
│  └──────┬───────┘     └──────────────┬──────────────────────────┘     │
│         │                            │                               │
│         └────────────┬───────────────┘                               │
│                      ▼                                               │
│  ┌──────────────────────────────────────────────────────────────┐    │
│  │                    Service Layer                              │    │
│  │                                                               │    │
│  │  ┌─────────┐  ┌─────────┐  ┌──────┐  ┌─────────┐           │    │
│  │  │ Fibrous │  │ Staking │  │ Vesu │  │  Batch  │           │    │
│  │  │  Swap   │  │Lifecycle│  │  V2  │  │Multicall│           │    │
│  │  └────┬────┘  └────┬────┘  └──┬───┘  └────┬────┘           │    │
│  │       │            │          │            │                 │    │
│  │  ┌────┴────────────┴──────────┴────────────┴────┐           │    │
│  │  │          Starkzap SDK (starkzap v1.0.0)       │           │    │
│  │  │  Wallet · TxBuilder · Tokens · Paymaster      │           │    │
│  │  └───────────────────┬───────────────────────────┘           │    │
│  └──────────────────────┼───────────────────────────────────────┘    │
│                         ▼                                            │
│  ┌─────────────────────────────────────┐  ┌─────────────────────┐   │
│  │  Auth Server (Hono + Privy TEE)     │  │  AVNU Paymaster     │   │
│  │  Email OTP · Wallet · Sign · Gas    │  │  Gas Abstraction    │   │
│  └─────────────────────────────────────┘  └─────────────────────┘   │
└──────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │  Starknet (L2)   │
                    └──────────────────┘

Starkzap Modules Used

StarkFi leverages all core Starkzap modules:

| Module | Usage in StarkFi | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------- | | Wallets | PrivySigner + ArgentXV050Preset for email-based wallet management via Privy TEE | | Gasless Transactions (Paymaster) | Paymaster integration with 5 gas tokens (STRK, ETH, USDC, USDT, DAI) + developer-sponsored gasfree mode | | Staking | Multi-token staking lifecycle (STRK, WBTC, tBTC, SolvBTC, LBTC) — stake, claim, compound, unstake (2-step) | | TxBuilder | Atomic multicall batching — combine swap + stake + supply + send in one transaction | | ERC-20 Tokens | Token presets, balance queries, transfers, approvals |

Features

🔄 Intelligent Swap Routing (Fibrous)

DEX-aggregated swaps with optimal routing. Single swaps, multi-swap (up to 3 pairs), and batch routing.

npx starkfi trade 100 USDC ETH --slippage 1
npx starkfi multi-swap "100 USDC>ETH, 50 USDT>ETH"

⚛️ Atomic Transaction Batching

Bundle multiple DeFi operations into a single Starknet multicall. Minimum 2 operations.

npx starkfi batch \
  --swap "100 USDC ETH" \
  --stake "50 STRK karnot" \
  --supply "200 USDC Prime" \
  --send "10 STRK 0xAddr"

🥩 Multi-Token Staking Lifecycle

Full staking lifecycle across multiple validators with STRK, WBTC, tBTC, SolvBTC, and LBTC support.

npx starkfi stake 100 -v karnot
npx starkfi rewards -v karnot --compound
npx starkfi unstake intent -v karnot -a 50
npx starkfi unstake exit -v karnot

🏦 Lending & Borrowing (Vesu V2)

Supply collateral, borrow assets, monitor health factors, and atomically close positions.

npx starkfi lend-supply 100 -p Prime -t STRK
npx starkfi lend-borrow -p Prime \
  --collateral-amount 200 --collateral-token STRK \
  --borrow-amount 50 --borrow-token USDC
npx starkfi lend-status -p Prime --collateral-token STRK --borrow-token USDC
npx starkfi lend-close -p Prime --collateral-token STRK --borrow-token USDC

💸 Gas Abstraction

All transactions are gasless by default. Users pay gas fees in their preferred ERC-20 token via Paymaster.

# Pay gas in USDC instead of STRK
npx starkfi config set-gas-token USDC

# Developer pays all gas (gasfree mode)
npx starkfi config set-gasfree on

| Mode | Who Pays | Gas Tokens | Description | | --------------------- | --------- | -------------------------- | --------------------------------- | | Gasless (default) | User | STRK, ETH, USDC, USDT, DAI | User pays in ERC-20 via Paymaster | | Gasfree | Developer | — | Developer sponsors all gas |

🧪 Simulation / Dry-Run

Estimate fees and validate any transaction before broadcasting.

npx starkfi trade 100 USDC ETH --simulate
# → mode: SIMULATION, estimatedFee: 0.000142 ETH ($0.52), callCount: 4

📊 Portfolio Dashboard

Consolidated view of all DeFi positions in one call.

npx starkfi portfolio
# → Token Balances (USD), Staking Positions, Lending Positions, Total Value

AI Integration (MCP)

StarkFi exposes 27 MCP tools via stdio transport, enabling AI assistants to execute DeFi operations.

# Start the MCP server
npx starkfi mcp-start

Tool Categories

| Category | Tools | Count | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | Auth & Config | get_auth_status, config_action | 2 | | Wallet | get_balance, get_portfolio, deploy_account, send_tokens, get_tx_status | 5 | | Trade | get_swap_quote, swap_tokens, get_multi_swap_quote, multi_swap, batch_execute | 5 | | Staking | list_validators, list_pools, get_staking_info, get_stake_status, stake_tokens, unstake_tokens, claim_rewards, compound_rewards | 8 | | Lending | list_lending_pools, get_lending_position, supply_assets, withdraw_assets, borrow_assets, repay_debt, close_position | 7 |

Example — AI Agent Workflow

User: "Swap 100 USDC to STRK and stake half on Karnot"

Agent:
  1. get_swap_quote(amount: "100", from: "USDC", to: "STRK")   → 500 STRK
  2. swap_tokens(amount: "100", from: "USDC", to: "STRK")       → txHash: 0x...
  3. stake_tokens(amount: "250", validator: "karnot", token: "STRK") → txHash: 0x...

MCP Configuration

Add to your AI assistant's MCP config (Cursor, Claude, etc.):

{
	"mcpServers": {
		"starkfi": {
			"command": "npx",
			"args": ["-y", "starkfi", "mcp-start"]
		}
	}
}

For the complete tool registry and schemas, see MCP Documentation.

Agent Skills

StarkFi ships with 10 agent skills — structured instruction sets that teach AI coding assistants how to use StarkFi without custom prompting.

| Category | Skills | | ---------------- | ------------------------------------------------------------ | | Auth | authenticate-wallet | | Wallet Data | balance, portfolio | | Transactions | send, trade, multi-swap, batch, staking, lending | | Utility | config |

# Install skills for your AI assistant
npx skills add ahmetenesdur/starkfi

See Skills Documentation for details.

Quick Start

Prerequisites

• Node.js v18+
• StarkFi Auth Server running (required for Privy email OTP and Paymaster proxy)

1. Authenticate

npx starkfi auth login [email protected]
npx starkfi auth verify [email protected] <OTP_CODE>

2. Deploy Account

npx starkfi deploy

3. Check Balance

npx starkfi balance

4. Start Trading

npx starkfi trade 10 STRK ETH --simulate    # Preview first
npx starkfi trade 10 STRK ETH               # Execute

Command Reference

Session & Wallet

| Command | Description | | --------------------------------------------------------- | -------------------------------- | | auth login <email> | Start email OTP authentication | | auth verify <email> <code> | Complete authentication | | auth logout | Terminate session | | status | Check auth status and API health | | address | Display Starknet address | | deploy | Deploy smart account on-chain | | balance [--token <symbol>] [--json] | Query token balances | | send <amount> <token> <recipient> [--simulate] [--json] | Transfer tokens | | portfolio [--json] | Full DeFi portfolio |

Trading (Fibrous)

| Command | Description | | ------------------------------------------------------------------- | --------------------------- | | trade <amount> <from> <to> [--slippage <%>] [--simulate] [--json] | Swap tokens | | multi-swap "<pairs>" [--slippage <%>] [--simulate] [--json] | Multi-pair swap (2-3 pairs) |

Batching (Multicall)

| Command | Description | | --------------------------------------------------------------------------- | ---------------------------- | | batch [--simulate] --swap "..." --stake "..." --supply "..." --send "..." | Atomic multicall (min 2 ops) |

Staking

| Command | Description | | ----------------------------------------------------------------------------- | ---------------------- | | validators [--json] | List active validators | | pools <validator> [--json] | Show delegation pools | | stake <amount> --validator <name> [--token <symbol>] [--simulate] | Stake tokens | | stake-status [validator] [--json] | Staking dashboard | | rewards --validator <name> [--token <symbol>] <--claim\|--compound> | Manage rewards | | unstake <intent\|exit> --validator <name> [--token <symbol>] [--amount <n>] | Unstake (2-step) |

Lending (Vesu V2)

| Command | Description | | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------- | | lend-pools [name] | List lending pools | | lend-supply <amount> -p <pool> -t <token> | Supply assets | | lend-withdraw <amount> -p <pool> -t <token> | Withdraw assets | | lend-borrow -p <pool> --collateral-amount <n> --collateral-token <t> --borrow-amount <n> --borrow-token <t> [--use-supplied] | Borrow | | lend-repay <amount> -p <pool> -t <token> --collateral-token <t> | Repay debt | | lend-status -p <pool> --collateral-token <t> [--borrow-token <t>] | Position status | | lend-close -p <pool> --collateral-token <t> --borrow-token <t> | Close position atomically |

Configuration

| Command | Description | | --------------------------------------- | ------------------------------ | | config list | Show current configuration | | config set-rpc <url> | Set custom RPC endpoint | | config get-rpc | Show current RPC | | config set-network <mainnet\|sepolia> | Switch network | | config set-gas-token <token\|reset> | Set gas payment token | | config set-gasfree <on\|off> | Toggle developer-sponsored gas | | tx-status <hash> | Check transaction status |

Auth Server

StarkFi includes a dedicated authentication server (server/) built for secure, non-custodial wallet management.

Route Groups

| Route | Purpose | | ------------ | ------------------------------------------------- | | /auth | Email OTP login and verification via Privy | | /wallet | Wallet creation and address retrieval | | /sign | Transaction signing via Privy TEE (non-custodial) | | /paymaster | Paymaster proxy for gas abstraction |

Security

• CORS with configurable allowlist (ALLOWED_ORIGINS)
• Secure headers via hono/secure-headers
• Body size limit (1MB)
• Request ID tracking for observability
• Graceful shutdown (SIGTERM/SIGINT with 5s force-kill)

See server/README.md for setup instructions.

Tech Stack

| Layer | Technology | | --------------- | -------------------------------------------------------------------------------- | | Core SDK | Starkzap v1.0.0 | | CLI | Commander.js v14.0.3 | | MCP | @modelcontextprotocol/sdk v1.27.1 | | Schema | Zod v4.3.6 | | Auth Server | Hono v4.12.2 + Privy TEE | | DEX Routing | Fibrous Aggregator | | Lending | Vesu V2 Protocol | | Gas | AVNU Paymaster |

Error Handling

StarkFi implements a robust error handling system with a custom StarkfiError class and 26 specific error codes organized by domain:

| Domain | Error Codes | | -------------- | --------------------------------------------------------------------------------- | | Auth | SESSION_EXPIRED, SESSION_NOT_FOUND, AUTH_FAILED, UNAUTHORIZED | | Wallet | WALLET_NOT_FOUND, WALLET_NOT_DEPLOYED, INSUFFICIENT_BALANCE | | Network | NETWORK_ERROR, RPC_ERROR, API_ERROR, TX_FAILED, TX_REVERTED | | Validation | INVALID_ADDRESS, INVALID_AMOUNT, INVALID_TOKEN, INVALID_CONFIG | | DeFi | SWAP_FAILED, STAKING_FAILED, LENDING_FAILED, POOL_NOT_FOUND | | System | CONFIG_ERROR, SDK_ERROR, UNKNOWN_ERROR, SIMULATION_FAILED, BATCH_FAILED |

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.

Development

Setup

git clone https://github.com/ahmetenesdur/starkfi.git
cd starkfi
pnpm install

Build

pnpm build           # Compile TypeScript → dist/

Dev Mode

pnpm dev -- --help   # Run with tsx (hot-reload)

Lint & Format

pnpm lint            # ESLint
pnpm format          # Prettier

Auth Server

cd server
pnpm install
cp .env.example .env    # Configure environment
pnpm dev

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository and create a feature branch
2. Install dependencies: pnpm install
3. Make your changes following the existing code style (TypeScript strict mode, ESLint + Prettier)
4. Build and verify: pnpm build && pnpm lint
5. Submit a pull request with a clear description

For bug reports and feature requests, please open an issue.

License

MIT — ahmetenesdur