{
  "markdown": "# FibX\n\nA command-line tool and MCP server for DeFi operations on **Base, HyperEVM, and Monad**, powered by [Fibrous](https://fibrous.finance) aggregation. Sign with your own wallet over WalletConnect, with a [Privy](https://privy.io) server wallet, or with an imported key — every path bounded by a signing policy that lives on your machine.\n\n[![npm version](https://badge.fury.io/js/fibx.svg)](https://badge.fury.io/js/fibx)\n\n## Features\n\n- **Multi-Chain Support**: Base, HyperEVM, and Monad\n- **Portfolio**: Cross-chain portfolio overview with USD valuations and DeFi positions\n- **Token Swaps**: Optimal routing via Fibrous aggregation with auto-slippage\n- **Transfers**: Send ETH or any ERC-20 token\n- **Aave V3**: Supply, borrow, repay, withdraw, and browse markets on Base\n- **MCP Server**: Built-in AI agent integration for Cursor, Claude Desktop, and Antigravity (19 tools)\n- **The FibX app, in the chat**: in hosts that render [MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps) UI such as Claude Desktop, `open_fibx` shows the wallet, balances, signing policy and a swap form with the Fibrous route inline — the model opens it, and you press Simulate and Swap\n- **Agent Skills**: Prompt-based AI skills via [fibx-skills](https://github.com/Fibrous-Finance/fibx-skills)\n- **Your own wallet**: Pair over WalletConnect and approve every transaction on your phone\n- **Privy Server Wallets**: Server-side signing — the CLI receives signed transaction payloads or signatures, not Privy app credentials or raw keys\n- **Private Key Import**: Use an existing wallet with AES-256-GCM encrypted local storage\n- **Local signing policy**: A file you own — native value cap per chain, allowed chains, allowed destinations, expiry — enforced before every signature on all three paths (Privy adds its own server-side policy on top)\n- **Preflight Checks**: Transaction flows validate or estimate execution where the underlying RPC supports it\n- **Dry‑Run Mode**: `--simulate` previews write operations without broadcasting; gas estimates are included where available\n- **JSON Output**: `--json` flag for scripting and pipelines\n- **Zero-Dependency Install**: Single-file bundle via tsup — `npx fibx` runs near-instantly\n\n## Supported Chains\n\n| Chain    | Native Token | Aave V3 |\n| -------- | ------------ | ------- |\n| Base     | ETH          | ✅      |\n| HyperEVM | HYPE         | —       |\n| Monad    | MON          | —       |\n\n## Installation\n\nRun directly with `npx` (no install needed):\n\n```bash\nnpx fibx status\n```\n\nOr install globally:\n\n```bash\nnpm install -g fibx\n```\n\n## Requirements\n\n- Node.js >= 18\n- A running [fibx-server](https://github.com/Fibrous-Finance/fibx-server) instance (required for Privy wallet operations; not needed for private key imports)\n\n## Quick Start — First Swap in 3 Minutes\n\n### Step 1: Get a Price Quote (no auth needed)\n\nTry FibX instantly — no sign-up, no wallet, no keys:\n\n```bash\nnpx fibx quote 0.01 ETH USDC              # Check price on Base\nnpx fibx quote 100 USDC DAI --chain base   # Compare pairs\nnpx fibx quote 0.5 MON USDC --chain monad  # Check Monad prices\n```\n\n### Step 2: Authenticate (pick one)\n\n**Option A — Email Login** (Privy Server Wallet, no keys to manage):\n\n```bash\nnpx fibx auth login you@email.com          # Sends OTP to your email\nnpx fibx auth verify you@email.com 123456  # Verify & create wallet\n```\n\n**Option B — Import Private Key** (use an existing wallet):\n\n```bash\nnpx fibx auth import                       # Paste your key (encrypted at rest)\n```\n\n### Step 3: Execute\n\n```bash\nnpx fibx trade 0.01 ETH USDC               # Execute the swap\nnpx fibx balance                            # Check your balances\n```\n\nThat's it. Three steps from zero to first swap.\n\n## Usage\n\n### Choosing how FibX signs\n\nRun `fibx auth setup` and it will ask. The three paths differ on one thing:\n\n| Path           | Key held by     | Runs while you are away | Bounded by               |\n| -------------- | --------------- | ----------------------- | ------------------------ |\n| `auth connect` | your own wallet | no                      | you, on your phone       |\n| `auth login`   | Privy           | yes                     | Privy's signing policy   |\n| `auth import`  | this machine    | yes                     | the local policy you set |\n\nKeeping your own wallet _and_ having FibX act unattended needs ERC-7715, which\nwallets do not yet expose over WalletConnect. `fibx auth setup` explains the\nclosest options.\n\n> **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.\n\n### Connect your own wallet\n\n```bash\nnpx fibx auth connect\n```\n\nPairs FibX with a wallet you already have — MetaMask, Rabby, Rainbow, Phantom —\nover WalletConnect. A QR code appears in the terminal; scan it with your phone.\nEvery transaction is then approved in your wallet, so the keys never leave it.\n\nThe chain you trade on must already be in your wallet, and it is approved when\nyou pair. If you try to sign on a chain the session does not carry, FibX stops\nbefore contacting the wallet and names the chain: add it in your wallet, then run\n`npx fibx auth connect` again so the new chain is included.\n\nWith `--json`, output is NDJSON — one JSON document per line, not one document\nfor the whole run: the pairing URI prints first as `{\"uri\":\"wc:...\"}` so a\nscript can act on it while it waits, then the result prints as its own compact\nJSON line once the wallet approves.\n\n`npx fibx auth logout` ends the connection on both sides: it tells your wallet to\ndrop the session, so FibX stops appearing in its connected-apps list, and removes\nthe pairing keys from disk along with the session.\n\nA shared WalletConnect project id ships in the published bundle, so this works\nwith no setup. It is public by necessity — a CLI has no origin to allowlist — so\nits only real exposure is quota consumed by third parties. If pairing starts\nfailing on quota, create a free project at\n[cloud.reown.com](https://cloud.reown.com) and set `FIBX_WC_PROJECT_ID` to your\nown id.\n\n`auth login` (email OTP) and `auth import` (private key) are unchanged and remain\navailable.\n\n### Signing policy\n\n`fibx policy` bounds what FibX is allowed to sign, on top of whichever path\nfrom the table above holds the key — a client-side cap evaluated before every\nlocal-key, Privy, or WalletConnect transaction:\n\n```bash\nnpx fibx policy show                    # Print the active policy\n\nnpx fibx policy set base.maxValue 0.05\nnpx fibx policy set allowedChains base,monad\nnpx fibx policy set base.allowedDestinations 0xYourColdWallet,0xTheRouter\nnpx fibx policy set expiry 2026-12-31   # UTC midnight starting that day\n\nnpx fibx policy clear base.maxValue     # Remove one rule\nnpx fibx policy clear                   # Remove the whole policy (asks first)\n```\n\nA local policy guarding a local key is advisory: anything that can read the\nkey can edit the policy, so this is worth nothing against malware. What it\ndoes bound is the agent — a model that misbehaves, or a prompt injection\ntelling it to.\n\nKnow what each rule bounds, because they are not the same:\n\n- `maxValue` caps the **native** value of a single transaction — ETH on Base,\n  HYPE on HyperEVM, MON on Monad. It does not bound tokens. An ERC-20 transfer\n  reaches the policy as a call to the token's contract carrying `value: 0`, so\n  the amount is invisible to it: `base.maxValue 0.05` places no limit on\n  `fibx send 50000 USDC 0xsomewhere`, on the token side of a trade, or on an\n  Aave borrow. A token-value cap needs decimals and a token registry, and is\n  not in this release.\n- `allowedDestinations` is the rule that bounds tokens, by bounding where\n  anything may go. It is the one to set if the worry is an agent moving your\n  holdings somewhere. Note that allowlisting a token's contract so a trade can\n  approve it also permits transfers of that token.\n- `allowedChains` and `expiry` do exactly what they say. A lapsed or\n  unparseable policy refuses everything rather than permitting it.\n\n### Global Options\n\n| Option               | Description                                | Default |\n| -------------------- | ------------------------------------------ | ------- |\n| `-c, --chain <name>` | Target chain (`base`, `hyperevm`, `monad`) | `base`  |\n| `--json`             | Output results as JSON                     | `false` |\n\n### Balance\n\n```bash\nnpx fibx balance\nnpx fibx balance --chain hyperevm\n```\n\n### Portfolio\n\nConsolidated cross-chain portfolio view with USD valuations:\n\n```bash\nnpx fibx portfolio           # Table output across all chains\nnpx fibx portfolio --json    # Structured JSON for scripting\n```\n\nShows all token holdings across Base, HyperEVM, and Monad with USD values. Includes DeFi positions (Aave V3 collateral/debt) and total portfolio net worth. Token prices are sourced live from Fibrous.\n\n### Send\n\n```bash\nnpx fibx send 0.001 0xRecipient           # Send native token on Base (ETH)\nnpx fibx send 10 0xRecipient USDC         # Send ERC-20 on Base\nnpx fibx send 1 0xRecipient --chain monad # Send MON on Monad\nnpx fibx send 0.1 0xRecipient --simulate  # Preview without sending\n```\n\n### Quote\n\nGet swap prices without authentication:\n\n```bash\nnpx fibx quote 0.01 ETH USDC                  # Price check on Base\nnpx fibx quote 1 MON USDC --chain monad         # Check Monad prices\nnpx fibx quote 0.1 ETH USDC --json             # JSON output for scripts\n```\n\n> **No wallet or authentication required.** Use `quote` to explore prices, then `trade` to execute.\n\n### Swap\n\n```bash\nnpx fibx trade <amount> <from> <to>\nnpx fibx trade 0.0001 ETH USDC\nnpx fibx trade 20 USDC DAI\nnpx fibx trade 1 MON USDC --chain monad\nnpx fibx trade 0.1 ETH USDC --simulate   # Preview without broadcasting\n```\n\nOptions: `--slippage <n>` (default: 0.5%), `--approve-max`, `--simulate`, `--json`\n\n> **Note:** The `trade` command automatically detects **Wrap** (Native -> Wrapped) and **Unwrap** (Wrapped -> Native) operations and executes them directly via contract calls, bypassing aggregator routing to save gas.\n\n### Transaction Status\n\n```bash\nnpx fibx tx-status <hash>\nnpx fibx tx-status 0x123...abc --chain monad\n```\n\n### Wallet Info\n\n```bash\nnpx fibx address    # Print active wallet address\nnpx fibx wallets    # Show active wallet details\n```\n\n### Aave V3 (Base)\n\n```bash\nnpx fibx aave status               # Account health\nnpx fibx aave markets              # List all active reserves with APY & TVL\nnpx fibx aave supply 1 ETH         # Auto-wraps ETH -> WETH and supplies\nnpx fibx aave supply 100 USDC      # Supply ERC-20\nnpx fibx aave borrow 50 USDC       # Borrow\nnpx fibx aave repay 50 USDC        # Repay\nnpx fibx aave repay max ETH        # Auto-wraps ETH and repays full WETH debt\nnpx fibx aave withdraw max ETH     # Withdraws WETH and auto-unwraps to ETH\nnpx fibx aave supply 1 ETH --simulate  # Preview without broadcasting\n```\n\n> **Note:** `supply`, `repay`, and `withdraw` support automatic **ETH <-> WETH** wrapping/unwrapping on Base.\n\n### Configuration\n\nSet custom RPC URLs to avoid rate limits on public endpoints:\n\n```bash\nnpx fibx config set-rpc base https://mainnet.base.org\nnpx fibx config get-rpc base\nnpx fibx config reset-rpc base   # Reset single chain to default\nnpx fibx config reset-rpc        # Reset all chains to default\nnpx fibx config list\n```\n\n> **Hot-reload:** Config changes are picked up automatically — no need to restart the CLI or MCP server.\n\n## AI Agent Integration\n\n### MCP Server\n\nfibx includes a built-in [MCP](https://modelcontextprotocol.io) server for AI editors like Cursor, Claude Desktop, and Antigravity. See [MCP.md](https://github.com/Fibrous-Finance/fibx/blob/main/MCP.md) for setup and available tools.\n\n```bash\nnpx fibx mcp-start\n```\n\nThe MCP server exposes **19 tools**: the FibX app (`open_fibx`, `list_tokens`), read-only queries, three transactional tools, and session and policy management. All write operations support a `simulate=true` preview that does not broadcast; gas estimates are returned only where available.\n\nIn a host that renders MCP Apps UI — Claude Desktop today — `open_fibx` is the entry point: ask about your wallet, a balance, a price or a swap and the whole app opens inline, pre-filled from the conversation. It executes nothing on its own; Simulate and Swap are buttons you press. In a text-only host the same call returns a JSON snapshot the model can summarise, and the headless tools do the rest.\n\n### Agent Skills\n\nFor prompt-based agent integration (Claude Code, Cursor, etc.), see the [fibx-skills](https://github.com/Fibrous-Finance/fibx-skills) repository.\n\n## Security\n\nLetting an AI agent operate a wallet requires controls outside the model.\nfibx combines signing-layer policies, server-side validation, client hints, and\nexplicit previews. These controls reduce risk, but the server credentials, MCP\nclient configuration, and deployment policy remain part of the trust boundary:\n\n| Layer                | What it does                                                                                                                                                                                                                                      |\n| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Privy signing policy | The default policy allowlists configured chains, caps each transaction's native-token `value`, and denies key export. Privy evaluates the policy at signing time; fibx-server credentials and any custom policy remain critical trust boundaries. |\n| fibx-server schemas  | `/sign/*` accepts only the exact transaction shape the CLI produces — unknown fields, contract creation, and unserved chains are rejected before reaching Privy.                                                                                  |\n| MCP tool annotations | Every transactional tool advertises `destructiveHint: true`; compatible clients may use that hint to request confirmation, depending on client behavior and configuration.                                                                        |\n| Simulation           | `--simulate` previews write operations without broadcasting. Some paths also return a gas estimate; others return operation metadata only.                                                                                                        |\n| Local key storage    | Imported private keys are encrypted at rest with AES-256-GCM using a per-machine key stored `0600` in the OS config directory.                                                                                                                    |\n\nWallet policy limits are configured per deployment — see the\n[fibx-server wallet policy docs](https://github.com/Fibrous-Finance/fibx-server#wallet-policy-privy-signing-layer).\n\n> **Note:** policies are attached when a wallet is created. Wallets provisioned\n> before policies were introduced keep signing without them until migrated.\n\n## Architecture\n\nThis repository is the CLI and MCP server. Three sibling repositories complete\nthe stack:\n\n| Repository                                                                | Role                                                                                                             |\n| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |\n| **fibx** (this repo)                                                      | CLI + stdio MCP server, shipped as a single dependency-free bundle                                               |\n| [fibx-server](https://github.com/Fibrous-Finance/fibx-server)             | Hono backend that proxies Privy — holds the app secret so the CLI never does, and owns the wallet signing policy |\n| [fibx-skills](https://github.com/Fibrous-Finance/fibx-skills)             | Prompt-based Agent Skills for Claude Code, Cursor, and other skill-aware agents                                  |\n| [fibx-telegram-bot](https://github.com/Fibrous-Finance/fibx-telegram-bot) | Telegram bot that drives this CLI over MCP, with one process and separate config paths per active user           |\n\n```\nsrc/\n├── commands/           # CLI commands (auth, policy, trade, send, aave, config)\n├── mcp/                # Modular MCP server\n│   ├── server.ts       # Entry point + MCP_INSTRUCTIONS\n│   ├── ui.ts           # The ui://fibx/app.html resource (the built widget, inlined)\n│   ├── tools/          # Tool registrations (app, auth, wallet, trade, defi, policy)\n│   └── handlers/       # Tool implementations\n├── services/           # Business logic (chain, fibrous, auth, policy, walletconnect, defi, portfolio)\n└── lib/                # Shared utilities (errors, fetch, format, crypto)\nui/\n├── src/                # The FibX app widget — Preact, one document, no network\n└── dev-host/           # A local MCP Apps host for the widget: fixtures, or a bridge to the real server\n```\n\nThe widget is built by Vite into a single HTML document and embedded in\n`dist/index.js` by tsup, so the published package is still one file with no\nruntime dependencies.\n\n## Development\n\n```bash\npnpm install\npnpm dev          # run the CLI from source\npnpm test         # vitest unit tests\npnpm typecheck    # tsc --noEmit\npnpm lint         # eslint\npnpm format:check # prettier\npnpm build        # vite (the app widget) then tsup, to dist/\npnpm dev:ui       # the app widget in a local host, against fixtures — no wallet needed\n```\n\n`pnpm dev:ui:bridge` runs the same host against the real MCP server; a Swap\nthere is a real swap.\n\n## Related Links\n\n- [Fibrous Finance](https://fibrous.finance) — DEX aggregator powering swaps\n- [FibX agent docs](https://docs.fibrous.finance/fibx-agent)\n- [npm package](https://www.npmjs.com/package/fibx)\n- [MCP registry listing](https://registry.modelcontextprotocol.io) — `finance.fibrous/fibx`\n\n## License\n\n[MIT](https://opensource.org/licenses/MIT)\n",
  "bytes": 18413,
  "sha": "2bd75b8442254133a837e5ca0bb2da443b82ebbfb0cc6990b81d6f67814f650d",
  "repo_slug": "fibrous-finance/fibx",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_finance_fibrous_fibx_27168d8f/readme"
}