Installation and Setup - Fibrous Documentation

Requirements

Node.js v18 or higher
npm (included with Node.js)
A running fibx-server instance only if you use Privy-managed wallet operations

No global installation is needed. All commands use npx fibx@latest, which always fetches the latest version (currently v0.5.1).

Installation Options

Run FibX directly with npx:

npx fibx@latest status

Or install it globally:

npm install -g fibx

Installing Agent Skills

To add fibx skills to your AI agent, use the Vercel Skills CLI:

npx skills add Fibrous-Finance/fibx-skills

This installs the pre-built skill definitions from the fibx-skills repository into your agent’s skill registry. No separate installation of fibx is needed — all skills execute via npx fibx@latest.

Verify Your Environment

node --version   # Must be v18.0.0 or higher
npm --version

Authentication

FibX requires an active session before performing any wallet operation (balance, send, trade, aave). Two authentication methods are available:

Private Key Import (Recommended)

If you already have a wallet with a private key, this is the fastest way to get started. The key is encrypted and stored in a local session file for the duration of the session. This mode does not require fibx-server.

Your private key will be stored locally in an encrypted session file. Only use this method on a trusted device.

# Interactive prompt — paste your private key when asked
npx fibx@latest auth import

# Confirm the session is active
npx fibx@latest status

This is ideal for developers and agents that already manage their own wallets. The imported key is used directly for signing transactions — no external server holds your key.

Email OTP (Alternative — Privy Server Wallets)

If you do not have a private key or prefer a managed wallet, you can authenticate via email OTP. This creates a server-managed wallet through Privy, where the private key is held securely on Privy’s infrastructure and never exposed to the client. This mode requires fibx-server to be running and reachable.

# Step 1: Request an OTP code
npx fibx@latest auth login user@example.com

# Step 2: Enter the code received via email
npx fibx@latest auth verify user@example.com 123456

# Step 3: Confirm the session is active
npx fibx@latest status

Session Management

# Check current session status
npx fibx@latest status

# Get the active wallet address
npx fibx@latest address

# End the session
npx fibx@latest auth logout

Global Options

These flags apply to all commands:

Flag	Description	Default
`-c, --chain`	Target chain: `base`, `citrea`, `hyperevm`, `monad`	`base`
`--json`	Output results as JSON (useful for scripting)	`false`
`--simulate`	Estimate gas and simulate execution without sending a transaction	`false`

Chain Selection

If no --chain flag is provided, all commands default to Base.

# Explicit chain selection
npx fibx@latest balance --chain citrea
npx fibx@latest trade 1 MON USDC --chain monad

# Default: Base
npx fibx@latest balance

First Transaction

After authenticating, run through a complete workflow to verify everything is working:

Check your balance

npx fibx@latest balance

Execute a swap

npx fibx@latest trade 0.001 ETH USDC

The CLI will find the optimal route via Fibrous, simulate the transaction, handle token approvals, and execute.

Verify the transaction

npx fibx@latest tx-status <transaction-hash>

This returns the on-chain status, gas used, and a block explorer link.

Dry-Run Mode

Use --simulate to estimate gas and validate execution without broadcasting a transaction.

npx fibx@latest send 0.1 0xRecipient --simulate
npx fibx@latest trade 0.1 ETH USDC --simulate
npx fibx@latest aave supply 1 ETH --simulate

​Requirements

​Installation Options

​Installing Agent Skills

​Verify Your Environment

​Authentication

​Private Key Import (Recommended)

​Email OTP (Alternative — Privy Server Wallets)

​Session Management

​Global Options

​Chain Selection

​First Transaction

​Dry-Run Mode

Requirements

Installation Options

Installing Agent Skills

Verify Your Environment

Authentication

Private Key Import (Recommended)

Email OTP (Alternative — Privy Server Wallets)

Session Management

Global Options

Chain Selection

First Transaction

Dry-Run Mode