fibx 0.5.1 → 0.7.0

package/README.md

@@ -11,13 +11,14 @@ A command-line tool for DeFi operations on **Base, Citrea, HyperEVM, and Monad**
 - **Token Swaps**: Optimal routing via Fibrous aggregation with auto-slippage
 - **Transfers**: Send ETH or any ERC-20 token
 - **Aave V3**: Supply, borrow, repay, withdraw, and browse markets on Base
-- **MCP Server**: Built-in AI agent integration for Cursor, Claude Desktop, and Antigravity
+- **MCP Server**: Built-in AI agent integration for Cursor, Claude Desktop, and Antigravity (11 tools, 4 categories)
 - **Agent Skills**: Prompt-based AI skills via [fibx-skills](https://github.com/Fibrous-Finance/fibx-skills)
 - **Privy Server Wallets**: Secure server-side signing — private keys never leave Privy's TEE
-- **Private Key Import**: Use an existing wallet for local execution
+- **Private Key Import**: Use an existing wallet with AES-256-GCM encrypted local storage
 - **Simulation**: All transactions are simulated before execution
 - **Dry‑Run Mode**: `--simulate` flag estimates gas without sending a transaction
 - **JSON Output**: `--json` flag for scripting and pipelines
+- **Zero-Dependency Install**: Single-file bundle via tsup — `npx fibx` runs near-instantly
 
 ## Supported Chains
 
@@ -47,6 +48,42 @@ npm install -g fibx
 - Node.js >= 18
 - A running [fibx-server](https://github.com/ahmetenesdur/fibx-server) instance (required for Privy wallet operations; not needed for private key imports)
 
+## Quick Start — First Swap in 3 Minutes
+
+### Step 1: Get a Price Quote (no auth needed)
+
+Try FibX instantly — no sign-up, no wallet, no keys:
+
+```bash
+npx fibx quote 0.01 ETH USDC              # Check price on Base
+npx fibx quote 100 USDC DAI --chain base   # Compare pairs
+npx fibx quote 0.5 MON USDC --chain monad  # Check Monad prices
+```
+
+### Step 2: Authenticate (pick one)
+
+**Option A — Email Login** (Privy Server Wallet, no keys to manage):
+
+```bash
+npx fibx auth login you@email.com          # Sends OTP to your email
+npx fibx auth verify you@email.com 123456  # Verify & create wallet
+```
+
+**Option B — Import Private Key** (use an existing wallet):
+
+```bash
+npx fibx auth import                       # Paste your key (encrypted at rest)
+```
+
+### Step 3: Execute
+
+```bash
+npx fibx trade 0.01 ETH USDC               # Execute the swap
+npx fibx balance                            # Check your balances
+```
+
+That's it. Three steps from zero to first swap.
+
 ## Usage
 
 ### Authentication
@@ -66,6 +103,8 @@ npx fibx status
 npx fibx auth logout
 ```
 
+> **Security:** When using `auth import`, your private key is encrypted at rest with AES-256-GCM. The encryption key is auto-generated per machine and stored in the OS config directory (e.g. `~/.config/fibx-nodejs/encryption-key` on Linux). You can also set the `FIBX_SESSION_SECRET` environment variable for CI/Docker environments.
+
 ### Global Options
 
 | Option               | Description                                          | Default |
@@ -100,6 +139,18 @@ npx fibx send 1 0xRecipient --chain monad # Send MON on Monad
 npx fibx send 0.1 0xRecipient --simulate  # Estimate gas without sending
 ```
 
+### Quote
+
+Get swap prices without authentication:
+
+```bash
+npx fibx quote 0.01 ETH USDC                  # Price check on Base
+npx fibx quote 100 USDC DAI --chain monad      # Compare pairs
+npx fibx quote 0.1 ETH USDC --json             # JSON output for scripts
+```
+
+> **No wallet or authentication required.** Use `quote` to explore prices, then `trade` to execute.
+
 ### Swap
 
 ```bash
@@ -156,6 +207,8 @@ npx fibx config reset-rpc        # Reset all chains to default
 npx fibx config list
 ```
 
+> **Hot-reload:** Config changes are picked up automatically — no need to restart the CLI or MCP server.
+
 ## AI Agent Integration
 
 ### MCP Server
@@ -166,10 +219,28 @@ fibx includes a built-in [MCP](https://modelcontextprotocol.io) server for AI ed
 npx fibx mcp-start
 ```
 
+The MCP server exposes **11 tools** across 4 categories (Auth & Config, Wallet & Portfolio, Trading, DeFi). All write operations support a `simulate=true` parameter for fee estimation without execution.
+
 ### Agent Skills
 
 For prompt-based agent integration (Claude Code, Cursor, etc.), see the [fibx-skills](https://github.com/Fibrous-Finance/fibx-skills) repository.
 
+## Architecture
+
+```
+fibx/
+├── src/                    # CLI + MCP server (single tsup bundle)
+│   ├── commands/           # CLI commands (auth, trade, send, aave, config)
+│   ├── mcp/                # Modular MCP server
+│   │   ├── server.ts       # Entry point + MCP_INSTRUCTIONS
+│   │   ├── tools/          # Tool registrations (auth, wallet, trade, defi)
+│   │   └── handlers/       # Tool implementations + context helpers
+│   ├── services/           # Business logic (chain, fibrous, auth, defi)
+│   └── lib/                # Shared utilities (errors, fetch, format, crypto)
+├── fibx-server/            # Privy wallet backend (Hono)
+└── fibx-telegram-bot/      # AI-powered Telegram bot
+```
+
 ## Related Links
 
 - [Fibrous Finance](https://fibrous.finance) — DEX aggregator powering swaps