Batch Swaps on app.fibrous.finance
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------------------- |
| `email` | string | Yes | User's email address |
| `code` | string | Yes | OTP code received via email |
### auth logout
End the active session. Also ends a WalletConnect pairing.
```bash theme={null}
npx fibx@latest auth logout
```
***
## policy — Signing Policy
Read and change the local signing policy: a JSON file the user owns, evaluated
before every signature on all three signing paths. No session is needed.
```bash theme={null}
npx fibx@latest policy show
npx fibx@latest policy set
npx fibx@latest policy clear [rule] [-y]
```
| Rule | Meaning | Example |
| ----------------------------- | ---------------------------------------------------------- | ---------------------------------------- |
| `.maxValue` | Largest native value (ETH / HYPE / MON) in one transaction | `base.maxValue 0.05` |
| `allowedChains` | Chains anything may be signed on (comma-separated) | `allowedChains base,monad` |
| `.allowedDestinations` | Addresses anything may be sent to on that chain | `base.allowedDestinations 0xAbC…,0xDeF…` |
| `expiry` | When the whole policy stops applying (ISO-8601) | `expiry 2026-12-31T00:00:00Z` |
`set` replaces the rule's previous value. `clear` with no rule removes the
whole policy and asks for confirmation; `-y` skips the question. A
transaction outside the policy is refused before any signature is requested,
with `POLICY_BLOCKED` and the rule named.
`maxValue` bounds the native value only. An ERC-20 transfer reaches the
policy with `value: 0`, so the cap never sees the token amount;
`allowedDestinations` is what bounds where tokens may go.
No file means everything is permitted. A file that exists but cannot be
parsed means **everything is refused** until it is fixed or cleared — a
corrupt policy does not fail open.
### Examples
```bash theme={null}
# Cap one transaction's native value on Base
npx fibx@latest policy set base.maxValue 0.05
# Only allow Base and Monad
npx fibx@latest policy set allowedChains base,monad
# Only allow sends to two addresses on Base
npx fibx@latest policy set base.allowedDestinations 0xAbC...,0xDeF...
# Remove the cap
npx fibx@latest policy clear base.maxValue
```
***
## status — Session Status
Check whether a session is active, which signing path it uses, and the
authenticated wallet address.
```bash theme={null}
npx fibx@latest status [--chain ] [--json]
```
***
## address — Wallet Address
Print the active wallet address.
```bash theme={null}
npx fibx@latest address [--json]
```
***
## wallets — Wallet Details
Show the active wallet details for the current session.
```bash theme={null}
npx fibx@latest wallets [--json]
```
***
## portfolio — Cross-Chain Portfolio
View a consolidated portfolio across all supported chains with USD-valued token holdings and DeFi positions.
```bash theme={null}
npx fibx@latest portfolio [--json]
```
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ---------------------------- |
| `json` | flag | No | Output the portfolio as JSON |
### Examples
```bash theme={null}
# Human-readable portfolio summary
npx fibx@latest portfolio
# Structured JSON for automation
npx fibx@latest portfolio --json
```
The portfolio view aggregates holdings across Base, HyperEVM, and Monad. It also includes Aave V3 collateral and debt positions when available.
***
## balance — Check Balances
Fetch native and ERC-20 token balances for the authenticated wallet.
```bash theme={null}
npx fibx@latest balance [--chain ] [--json]
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------ |
| `chain` | string | No | `base`, `hyperevm`, or `monad` |
| `json` | flag | No | Output as JSON |
```bash theme={null}
npx fibx@latest balance
```
```bash theme={null}
npx fibx@latest balance --chain hyperevm
```
```bash theme={null}
npx fibx@latest balance --chain monad
```
***
## send — Transfer Tokens
Send native tokens or ERC-20 tokens to a recipient address. FibX performs a
command-specific preflight before submission.
```bash theme={null}
npx fibx@latest send [token] [--chain ] [--simulate] [--json]
```
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | ----------------------------------------------------------------- |
| `amount` | number | Yes | Amount to send |
| `recipient` | string | Yes | Destination address (`0x...`) |
| `token` | string | No | Token symbol or supported contract address; omit for native token |
| `chain` | string | No | `base`, `hyperevm`, or `monad` |
| `simulate` | flag | No | Preview the transfer without submitting it |
| `json` | flag | No | Output as JSON |
If `token` is omitted, the chain's native token is used (ETH on Base, HYPE on HyperEVM, MON on Monad).
### Examples
```bash theme={null}
# Send native ETH on Base
npx fibx@latest send 0.01 0xRecipient
# Send ERC-20 on Base
npx fibx@latest send 100 0xRecipient USDC
# Send native MON on Monad
npx fibx@latest send 1 0xRecipient --chain monad
# Preview a native transfer
npx fibx@latest send 0.1 0xRecipient --simulate
```
***
## trade: Swap Tokens
Exchange one token for another via Fibrous aggregation. The CLI finds a route,
handles token approvals, estimates the main swap path, and submits it.
```bash theme={null}
npx fibx@latest trade [--chain ] [--slippage ] [--approve-max] [--simulate] [--json]
```
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------------------- |
| `amount` | number | Yes | Amount of the source token to swap |
| `from_token` | string | Yes | Source token symbol or supported contract address |
| `to_token` | string | Yes | Target token symbol or supported contract address |
| `chain` | string | No | `base`, `hyperevm`, or `monad` |
| `slippage` | number | No | Slippage tolerance in percent (default: `0.5`), 0.01–50 |
| `approve-max` | flag | No | Use infinite approval instead of exact amount |
| `simulate` | flag | No | Return a no-broadcast preview of the main swap |
| `json` | flag | No | Output as JSON |
The `trade` command automatically detects **Wrap** (Native → Wrapped) and **Unwrap** (Wrapped → Native) operations and executes them directly via contract calls, bypassing the aggregator routing to save gas.
If the source is an ERC-20 token with insufficient allowance,
`trade --simulate` returns `requiresApproval: true` without submitting an
approval. Because the swap cannot be estimated safely in that state, the
preview omits the gas estimate.
A live routed ERC-20 trade may confirm an approval transaction before
estimating and submitting the swap. If the later swap step fails, that
approval remains on-chain. `--simulate` broadcasts neither transaction.
### Examples
```bash theme={null}
npx fibx@latest trade 0.1 ETH USDC
```
```bash theme={null}
npx fibx@latest trade 1 HYPE USDC --chain hyperevm
```
```bash theme={null}
npx fibx@latest trade 1 MON USDC --chain monad
```
```bash theme={null}
npx fibx@latest trade 0.1 ETH USDC --slippage 1.0
```
```bash theme={null}
npx fibx@latest trade 0.1 ETH USDC --simulate
```
***
## aave — Aave V3 (Base Only)
Manage Aave V3 lending positions on Base. Supply assets to earn yield, borrow against collateral, repay debt, or withdraw.
Aave V3 operations always target **Base**. The global `--chain` option does
not change the Aave network, so omit it for `aave` commands.
```bash theme={null}
npx fibx@latest aave [amount] [token] [--simulate] [--json]
```
| Parameter | Type | Required | Description |
| ---------- | ------ | -------------------------------- | ------------------------------------------------------------ |
| `action` | string | Yes | `status`, `markets`, `supply`, `borrow`, `repay`, `withdraw` |
| `amount` | string | Yes (except `status`, `markets`) | Amount or `max` for full repay/withdraw |
| `token` | string | Yes (except `status`, `markets`) | Token symbol or supported contract address |
| `simulate` | flag | No | Return a request-only, no-broadcast preview |
| `json` | flag | No | Output as JSON |
### Actions
| Action | Description | Example |
| ---------- | -------------------------------------------------------- | --------------------------------------- |
| `status` | Health factor, collateral, debt, and available borrowing | `npx fibx@latest aave status` |
| `markets` | Browse reserves with APY and supply/borrow totals | `npx fibx@latest aave markets` |
| `supply` | Deposit assets; ETH input can auto-wrap to WETH | `npx fibx@latest aave supply 1 ETH` |
| `borrow` | Borrow against collateral; the ETH market returns WETH | `npx fibx@latest aave borrow 50 USDC` |
| `repay` | Repay debt; ETH input can auto-wrap to WETH | `npx fibx@latest aave repay max ETH` |
| `withdraw` | Withdraw assets; ETH input can auto-unwrap WETH to ETH | `npx fibx@latest aave withdraw max ETH` |
### ETH ↔ WETH Auto-Wrap
For the ETH market, `supply` and `repay` can wrap ETH to WETH, while `withdraw`
can unwrap WETH to ETH. Borrowing the ETH market returns WETH; the borrowed
asset is not auto-unwrapped.
```bash theme={null}
npx fibx@latest aave supply 1 ETH # Auto-wraps ETH → WETH and supplies
npx fibx@latest aave supply 100 USDC # Supply ERC-20 directly
npx fibx@latest aave markets # Browse reserves with APY and supply/borrow totals
npx fibx@latest aave borrow 50 USDC # Borrow
npx fibx@latest aave repay 50 USDC # Repay partial USDC debt
npx fibx@latest aave repay max ETH # Auto-wraps ETH and repays full WETH debt
npx fibx@latest aave withdraw max ETH # Withdraws WETH and auto-unwraps to ETH
npx fibx@latest aave supply 1 ETH --simulate # Preview the request only
```
An Aave `--simulate` result summarizes the normalized request without
broadcasting it. It does not perform on-chain validation, simulate the
contract call, or estimate gas.
A live `supply` or `repay` may submit wrap and approval transactions before
the Aave call. An ETH `withdraw` submits the Aave withdrawal before a separate
unwrap transaction; the reported `txHash` is the Aave withdrawal hash. If a
later step fails, earlier transactions remain on-chain. In particular,
`aave withdraw max ETH` unwraps the wallet's entire WETH balance after the
withdrawal, including WETH held before the command.
### Health Factor
Before borrowing, always check `aave status`. The Health Factor indicates liquidation risk:
* **Above 1.5** — Lower liquidation risk, but not risk-free
* **Between 1.1 and 1.5** — Liquidation risk warning
* **Below 1.1** — High liquidation risk, proceed with extreme caution
`max` is supported only for `repay` and `withdraw`; `supply max` and
`borrow max` are rejected. Use `max` when fully repaying debt or withdrawing a
supplied position to avoid dust residuals.
***
## config — RPC Configuration
View and modify local fibx CLI configuration. Used primarily to set custom RPC URLs when hitting rate limits on public endpoints.
```bash theme={null}
npx fibx@latest config [chain] [url]
```
| Subcommand | Description | Example |
| ----------- | ---------------------------------------- | -------------------------------------------------------------- |
| `set-rpc` | Set a custom RPC URL for a chain | `npx fibx@latest config set-rpc base https://mainnet.base.org` |
| `get-rpc` | View the current RPC URL for a chain | `npx fibx@latest config get-rpc base` |
| `reset-rpc` | Reset one chain or all chains to default | `npx fibx@latest config reset-rpc base` |
| `list` | List all custom configurations | `npx fibx@latest config list` |
| Parameter | Type | Required | Description |
| --------- | ------ | --------------- | -------------------------------------------------------------- |
| `chain` | string | Conditional | Required for `set-rpc` and `get-rpc`; optional for `reset-rpc` |
| `url` | string | Yes (`set-rpc`) | Full HTTP(S) RPC endpoint URL |
Configuration is stored in the OS-specific FibX config directory and persists
across sessions. Typical paths are `~/.config/fibx-nodejs/config.json` on
Linux and `~/Library/Preferences/fibx-nodejs/config.json` on macOS.
### Examples
```bash theme={null}
# Handle rate limit on Base
npx fibx@latest config set-rpc base https://mainnet.base.org
# Check configured RPC
npx fibx@latest config get-rpc base
# Reset Base RPC to default
npx fibx@latest config reset-rpc base
# Reset all custom RPCs
npx fibx@latest config reset-rpc
# List all configurations
npx fibx@latest config list
```
***
## tx-status — Transaction Status
Check the on-chain status of a transaction and retrieve the block explorer link.
```bash theme={null}
npx fibx@latest tx-status [--chain ] [--json]
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------ |
| `hash` | string | Yes | Transaction hash (`0x...`) |
| `chain` | string | No | Must match the chain of the original transaction |
| `json` | flag | No | Output as JSON |
Always use the same `--chain` flag that was used for the original transaction. A Base transaction hash will not be found on Monad.
### JSON Output
```json theme={null}
{
"status": "success",
"blockNumber": "12345",
"gasUsed": "21000",
"from": "0x...",
"to": "0x...",
"txHash": "0x...",
"explorer": "https://basescan.org/tx/0x...",
"chain": "base"
}
```
***
## Error Reference
Common errors across all commands:
| Error | Cause | Resolution |
| ---------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `Not authenticated` | No active session | Run `auth setup` (or `auth connect` / `auth login` / `auth import`) first |
| `POLICY_BLOCKED` | The local signing policy refused the transaction | The rule and limit are named; change them with `policy set` or `policy clear` |
| Rejected in wallet | The WalletConnect wallet declined the request | Nothing was sent; retry when ready |
| `Insufficient balance` | Not enough tokens for the operation | Check `balance` and adjust the amount |
| `Simulation failed` | An RPC estimate or contract preflight rejected the request | Verify parameters and token availability |
| `No route found` | No liquidity path exists for the token pair | Try a different pair or check the chain |
| `Slippage exceeded` | Price moved beyond tolerance | Retry or increase slippage with `--slippage` |
| `Session expired` | Privy session timed out (7 days) | Re-authenticate with `auth login` |
| `Invalid address` | Recipient address is malformed | Verify the address starts with `0x` and is valid |
| `Rate limit` | Too many requests in a short period | Retry shortly; set a custom RPC if 429 errors persist |
# What is FibX?
Source: https://docs.fibrous.finance/fibx-agent/index
A command-line tool, MCP server and agent skill framework for executing DeFi operations across multiple chains, powered by Fibrous aggregation.
FibX is a DeFi execution layer for developers and AI agents — token swaps, transfers, balance checks, cross-chain portfolio inspection, and Aave V3 position management — across **Base, HyperEVM, and Monad**. One published package serves three surfaces: `fibx ` for people, `fibx mcp-start` for agents, and, in hosts that render [MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps) UI, **the FibX app** inside the chat.
It combines [Fibrous](https://fibrous.finance) aggregation for optimal swap routing with a choice of how transactions are signed: your own wallet over WalletConnect, a server-managed wallet via [Privy](https://privy.io), or a private key imported onto the machine — every path bounded by a [signing policy](/fibx-agent/signing) that lives in a file you own.
## Core Capabilities
In Claude Desktop and other hosts that render MCP Apps UI, one tool opens the whole app in the chat — wallet, balances, signing policy, and a swap form with the Fibrous route. The model opens it; you press Simulate and Swap.
Consolidated cross-chain portfolio view with USD valuations, token balances, Aave collateral and debt, and total net worth across all supported chains.
Optimal routing via Fibrous aggregation with configurable slippage
(default: 0.5%). Supports the tokens and integrated DEX liquidity available
through Fibrous on each chain.
Send native tokens (ETH, HYPE, MON) or ERC-20 tokens to an address, with command-specific preflight and preview support.
Supply, borrow, repay, withdraw, and browse active markets on Base. ETH supply and repay can auto-wrap, ETH withdraw can auto-unwrap, and borrowing the ETH market returns WETH.
Eleven pre-built skills that allow AI agents to check prices, authenticate, set a signing policy, inspect balances and portfolios, trade, send, manage Aave positions, verify transactions, and configure RPC endpoints — all through natural language.
## How It Works
FibX runs as a CLI tool (`npx fibx@latest`) or as a stdio MCP server (`npx fibx mcp-start`). Both talk to the Fibrous aggregation stack and to the chain RPCs directly. Where a transaction is signed depends on the signing path: on the user's phone over WalletConnect, at Privy through `fibx-server`, or locally with an imported key. In every case the local signing policy is checked before a signature is requested. Transaction paths use command-specific estimates or contract simulations where implemented, but those checks do not guarantee that an on-chain operation will succeed.
```mermaid theme={null}
flowchart LR
A[User, AI agent, or the FibX app] --> B[fibx CLI / MCP server]
B --> P{Local signing policy}
P --> W[Your wallet over WalletConnect]
P --> S[fibx-server → Privy Server Wallets]
P --> K[Imported key, encrypted locally]
W --> F[Fibrous Aggregation API]
S --> F
K --> F
F --> G[Blockchain]
```
## Supported Chains
| Chain | Native Token | CLI Flag | Aave V3 |
| -------- | ------------ | ------------------ | ------- |
| Base | ETH | `--chain base` | Yes |
| HyperEVM | HYPE | `--chain hyperevm` | No |
| Monad | MON | `--chain monad` | No |
Citrea was delisted by Fibrous on 2026-08-10 and withdrawn from FibX in
v0.10.0. `--chain citrea` is refused.
## Security Model
FibX moves real funds. Treat client confirmation, preview output, the signing
policies, and backend credentials as separate controls; none replaces reviewing
the final transaction request.
A JSON file on the user's machine — a native-value cap per chain, an allowed-chain list, an allowed-destination list, and an expiry — evaluated before every signature on all three signing paths. It bounds the native `value` of a transaction, not ERC-20 amounts encoded in calldata; `allowedDestinations` is what bounds where tokens may go. A refusal comes back as `POLICY_BLOCKED` with the rule named. See [Signing paths and the local policy](/fibx-agent/signing).
On the Privy path, new wallets are attached to a default-deny policy whose rules allowlist configured chain IDs and cap the native `value` field, evaluated by Privy at signing time on top of the local policy. Message and typed-data requests also rely on `fibx-server` validation. A custom `WALLET_POLICY_ID` is checked for existence, not compared with the default rule set.
Transactional MCP tools carry the `destructiveHint` annotation. MCP clients may use this metadata to request confirmation, depending on the client and its configuration. The FibX app executes nothing on its own: Simulate and Swap are buttons the user presses.
Over WalletConnect the wallet app approves every transaction and nothing is signed on this machine. In Privy mode, signing returns a signed payload to the CLI; the raw key is not returned, and `fibx-server` with the Privy app secret remains the trust boundary. In private-key mode, FibX encrypts the imported key at rest with AES-256-GCM and signs locally — there the local policy is the only bound.
`--simulate` and `simulate=true` provide no-broadcast previews for supported write paths, but the returned checks are command-specific. Gas estimates are included only where they can be calculated safely, and an Aave action preview does not perform on-chain validation. A preview does not guarantee that later execution will succeed.
The policies are defense in depth on the normal signing path, not a
containment guarantee. The local policy is a file, so it is worth nothing
against something that can already write to the user's disk; the Privy app
credentials authorize both signing and policy administration, so the backend
that holds them is the administrative trust boundary on that path.
## Typical Workflow
A typical wallet workflow follows five steps:
Run `fibx auth setup`. It presents the three paths with their trade-offs — your own wallet over WalletConnect, a Privy server wallet via email OTP, or an imported private key — and creates a session that persists across commands.
Set a signing policy with `fibx policy set`. On the imported-key path this is the only limit there is; on the others it sits in front of the wallet's own approval or Privy's policy.
Query native and ERC-20 token balances on the target chain, or inspect the full cross-chain portfolio with USD valuations.
Review the amount, tokens, destination, chain, and any approval. Use the command-specific preview options where appropriate, then submit the operation on-chain. Over WalletConnect, approve it on your phone.
Check the transaction status and obtain the block explorer link.
## Quick Example
```bash theme={null}
# Check a price first — no wallet, no login required
npx fibx@latest quote 0.01 ETH USDC
# Choose a signing path (interactive)
npx fibx@latest auth setup
# Cap what this wallet may sign on Base
npx fibx@latest policy set base.maxValue 0.05
# Check balance on Base
npx fibx@latest balance
# View your cross-chain portfolio
npx fibx@latest portfolio
# Swap 0.01 ETH for USDC
npx fibx@latest trade 0.01 ETH USDC
# Verify the transaction
npx fibx@latest tx-status 0xabc...def
```
## Three Ways to Use FibX
Run commands directly in your terminal. Ideal for developers who want programmatic access to DeFi operations or need to script workflows.
```bash theme={null}
npx fibx@latest portfolio --json
npx fibx@latest trade 0.05 ETH USDC --chain base --simulate
```
Add `npx fibx mcp-start` to Cursor, Claude Desktop, VS Code, Windsurf or Antigravity and the model gets 19 typed tools. In a host that renders MCP Apps UI — Claude Desktop today — asking about your wallet, a price or a swap opens the FibX app inline, pre-filled from the conversation. See [MCP Configuration](/fibx-agent/mcp-configuration).
```json theme={null}
{ "mcpServers": { "fibx": { "command": "npx", "args": ["-y", "fibx", "mcp-start"] } } }
```
Import the [fibx-skills](https://github.com/Fibrous-Finance/fibx-skills) into your AI agent's skill registry. The agent interprets natural language prompts and maps them to the appropriate CLI commands.
| User Prompt | Skill Triggered |
| ------------------------------- | --------------------- |
| "How much USDC for 0.1 ETH?" | `quote` |
| "Connect my own wallet" | `authenticate-wallet` |
| "Cap this wallet at 0.05 ETH" | `policy` |
| "What's my wallet address?" | `wallet-info` |
| "Swap 0.05 ETH to USDC" | `trade` |
| "Check my balance on Monad" | `balance` |
| "Show me my portfolio" | `portfolio` |
| "Send 10 USDC to 0x123..." | `send` |
| "Supply 100 USDC to Aave" | `aave` |
| "I'm getting rate limit errors" | `config` |
## Telegram Bot
[fibx-telegram-bot](https://github.com/Fibrous-Finance/fibx-telegram-bot) puts the
same execution layer in a chat window. It drives the FibX MCP server, exposing
capabilities such as quotes, swaps, transfers, portfolio, and Aave through
natural language rather than CLI flags.
* **Bring your own model.** Choose OpenAI, Claude or Gemini and supply your own
API key. There is no shared key and no centralized inference billing; keys are
encrypted at rest. `/deletekey` clears the provider configuration and
encrypted key, FibX session/config/cache, pending authentication, and chat
history; price alerts remain active.
* **Per-user runtime state.** Every active user gets a dedicated MCP process and
separate HOME/XDG paths. These processes still run under the same OS account,
so this is application-level separation rather than an OS sandbox.
* **Price alerts.** `/alert ETH above 4000` notifies you once when the price is
reached — no login or AI key required.
## Resources
fibx v0.10.0 — install and version history
Eleven pre-built skills for AI agent integration
Connect FibX to Cursor, Claude Desktop, VS Code, Windsurf, and Antigravity — and open the FibX app in the chat
Your own wallet, Privy, or an imported key — and the local file that bounds all three
Listed as `finance.fibrous/fibx`
Chat-based DeFi execution with your own AI model
# Installation and Setup
Source: https://docs.fibrous.finance/fibx-agent/installation
Requirements, installation, and the three ways to authenticate the fibx CLI.
## Requirements
* **Node.js** v18 or higher
* **npm** (included with Node.js)
* A running [fibx-server](https://github.com/Fibrous-Finance/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.10.0**).
## Installation Options
Run FibX directly with `npx`:
```bash theme={null}
npx fibx@latest status
```
Or install it globally:
```bash theme={null}
npm install -g fibx
```
## Installing Agent Skills
To add fibx skills to your AI agent, use the Vercel Skills CLI:
```bash theme={null}
npx skills add Fibrous-Finance/fibx-skills
```
This installs the pre-built skill definitions from the [fibx-skills repository](https://github.com/Fibrous-Finance/fibx-skills) into your agent's skill registry. No separate installation of `fibx` is needed — all skills execute via `npx fibx@latest`.
## Verify Your Environment
```bash theme={null}
node --version # Must be v18.0.0 or higher
npm --version
```
## Try It Without a Wallet
Before setting anything up, you can check live prices — `quote` needs no session,
wallet, or keys:
```bash theme={null}
npx fibx@latest quote 0.01 ETH USDC
npx fibx@latest quote 1 MON USDC --chain monad
```
## Authentication
Commands that inspect or act on a wallet — including `address`, `wallets`,
`balance`, `portfolio`, `send`, `trade`, `aave status`, and Aave actions — need
an active session. Public or local commands such as `quote`, `status`,
`tx-status`, `config`, `policy`, and `aave markets` can run without one. Three
signing paths are available, and they are peers — `auth setup` presents the
choice with the trade-offs explained. The full comparison is on
[Signing Paths and the Local Policy](/fibx-agent/signing).
```bash theme={null}
npx fibx@latest auth setup
```
### Your Own Wallet (WalletConnect)
Keep your keys in the wallet you already use. The CLI shows a QR code and a
`wc:` URI; scan it with your wallet app and approve the pairing. Every later
transaction is approved on your phone, so this path does not run unattended.
```bash theme={null}
# Shows a QR code and waits for the wallet to approve
npx fibx@latest auth connect
# Confirm the session is active
npx fibx@latest status
```
### Private Key Import
If you already have a wallet with a private key and want FibX to act without
you, this is the most direct path. The key is encrypted at rest with
AES-256-GCM and used to sign locally. This mode does not require `fibx-server`.
With an imported key, the local signing policy is the **only** thing
bounding what this wallet signs. Set one (`fibx policy set base.maxValue
0.05`) before the first transaction, and only use this path on a trusted
device.
```bash theme={null}
# Interactive prompt — paste your private key when asked
npx fibx@latest auth import
# Confirm the session is active
npx fibx@latest status
```
### Email OTP (Privy Server Wallets)
If you do not have a private key or prefer a managed wallet, authenticate via
email OTP. This creates a server-managed wallet through
[Privy](https://privy.io). Signing is requested through `fibx-server`, and the
private key itself is not returned to the CLI. This mode requires `fibx-server`
to be running and reachable.
```bash theme={null}
# 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
```bash theme={null}
# Check current session status
npx fibx@latest status
# Get the active wallet address
npx fibx@latest address
# End the session (also ends a WalletConnect pairing)
npx fibx@latest auth logout
```
## Set a Signing Policy
A file you own, checked before every signature on all three paths. On the
imported-key path it is the only limit there is.
```bash theme={null}
# Cap the native value of one transaction on Base
npx fibx@latest policy set base.maxValue 0.05
# Only allow Base and Monad
npx fibx@latest policy set allowedChains base,monad
# See what is set
npx fibx@latest policy show
```
`maxValue` bounds the native value only — an ERC-20 transfer reaches the
policy with `value: 0`. Use `.allowedDestinations` to bound where
tokens may go. Details on [Signing Paths and the Local Policy](/fibx-agent/signing).
## Common Command Options
These flags are available where shown in the command reference:
| Flag | Description | Default |
| ------------- | ---------------------------------------------------------------- | ------- |
| `-c, --chain` | Target chain: `base`, `hyperevm`, `monad` | `base` |
| `--json` | Output results as JSON (useful for scripting) | `false` |
| `--simulate` | Command-specific preview; behavior varies by command (see below) | `false` |
### Chain Selection
Commands that accept `--chain` default to **Base** unless their reference says
otherwise.
```bash theme={null}
# Explicit chain selection
npx fibx@latest balance --chain hyperevm
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:
```bash theme={null}
npx fibx@latest balance
```
```bash theme={null}
npx fibx@latest trade 0.001 ETH USDC
```
The CLI checks the signing policy, finds a route via Fibrous, handles any required token approval, estimates the swap where supported, and submits it. Over WalletConnect, approve it on your phone.
```bash theme={null}
npx fibx@latest tx-status
```
This returns the on-chain status, gas used, and a block explorer link.
## Preview Behavior
`send --simulate`, `trade --simulate`, and Aave actions with `--simulate` return
a no-broadcast preview. Review the result and the command-specific limitations
before submitting the live operation.
```bash theme={null}
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
```
Preview output varies by path. If an ERC-20 trade needs approval,
`trade --simulate` reports `requiresApproval: true` without submitting the
approval or returning a gas estimate. An Aave preview returns the normalized
request only; it does not perform on-chain validation or estimate gas. Preview
success does not guarantee that later execution will succeed.
# MCP Configuration
Source: https://docs.fibrous.finance/fibx-agent/mcp-configuration
Configure FibX as an MCP server for AI editors — Cursor, Claude Desktop, Antigravity, and other MCP-compatible clients — and open the FibX app in the chat.
FibX includes a built-in [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that exposes DeFi operations as callable tools. AI editors like **Cursor**, **Claude Desktop**, **Antigravity**, and any MCP-compatible client can connect to FibX and execute trades, transfers, and DeFi operations through natural language.
In hosts that render [MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps) UI — Claude Desktop today — the server also serves **the FibX app**: one document showing the wallet, balances, the signing policy, and a swap form with the Fibrous route, opened by the `open_fibx` tool and pre-filled from the conversation. The model opens it; the user presses Simulate and Swap.
## Quick Start
```bash theme={null}
npx fibx mcp-start
```
This starts an MCP server over **stdio** (standard input/output). The server speaks JSON-RPC 2.0 and is designed to be launched by an AI editor, not run manually.
## How It Works
1. Your AI editor spawns `npx fibx mcp-start` as a subprocess.
2. The editor communicates with FibX over **stdin/stdout** using JSON-RPC 2.0 messages.
3. Wallet-dependent tools read the local session file. Run `fibx auth setup` (or `auth connect`, `auth login`, `auth import`) before using those tools, or pair a wallet from inside the app with `connect_wallet`; public tools such as quotes, the token list, the policy, and Aave market discovery do not need a session.
4. Transactional tools execute against live blockchains and carry the MCP `destructiveHint` annotation. A client may use that hint to request confirmation, depending on its behavior and configuration. Every transaction also passes the [local signing policy](/fibx-agent/signing) before a signature is requested.
5. `open_fibx` is bound to the resource `ui://fibx/app.html`. A host that renders MCP Apps shows the app inline and the tool's JSON result seeds it; a host that does not simply gets the JSON — a complete snapshot of chain, session, balances, policy and quote — and the model reads that instead.
`stderr` is used for logging, while `stdout` is reserved for JSON-RPC protocol messages.
## Editor Setup
Add the FibX MCP server to your AI editor. FibX uses **stdio** transport — the editor spawns `npx fibx mcp-start` and communicates over standard input/output.
Open MCP settings with Command + Shift + P and search for "Open MCP settings". Create or edit `.cursor/mcp.json` in your project root:
```json theme={null}
{
"mcpServers": {
"fibx": {
"command": "npx",
"args": ["-y", "fibx", "mcp-start"]
}
}
}
```
Test by asking Cursor: *"What tools do you have available?"* — it should list the FibX MCP server.
Add to your `claude_desktop_config.json`:
```json theme={null}
{
"mcpServers": {
"fibx": {
"command": "npx",
"args": ["-y", "fibx", "mcp-start"]
}
}
}
```
Quit Claude Desktop fully after editing the config (Cmd + Q on macOS — the server process starts at launch and is not restarted by closing a window). Claude Desktop renders the FibX app inline: ask about your wallet, a price or a swap and the app opens in the chat. You can pair a wallet from inside it, or authenticate first with `fibx auth setup`.
Create or edit `.vscode/mcp.json` in your project:
```json theme={null}
{
"mcpServers": {
"fibx": {
"command": "npx",
"args": ["-y", "fibx", "mcp-start"]
}
}
}
```
Reload the window or restart VS Code to activate the MCP server.
Open the MCP configuration in Windsurf settings and add:
```json theme={null}
{
"mcpServers": {
"fibx": {
"command": "npx",
"args": ["-y", "fibx", "mcp-start"]
}
}
}
```
Add to `~/.gemini/antigravity/mcp_config.json`:
```json theme={null}
{
"mcpServers": {
"fibx": {
"command": "npx",
"args": ["-y", "fibx", "mcp-start"]
}
}
}
```
ChatGPT and other tools without MCP support cannot connect to FibX directly. Use one of these alternatives:
* **CLI**: Run `npx fibx@latest` commands directly in your terminal.
* **Agent Skills**: Install [fibx-skills](https://github.com/Fibrous-Finance/fibx-skills) for AI agents that support the Agent Skills format.
* **MCP-capable editor**: Use Cursor, Claude Desktop, VS Code, or Windsurf with the config above.
Wallet operations need a session. Create one with `fibx auth setup` in a terminal, or — over MCP — with `connect_wallet`, which pairs your own wallet by QR. The FibX app offers the same pairing from its Connect button.
## The FibX App
`open_fibx` is the entry point in any host that renders MCP Apps UI. The
server's own instructions tell the model so: a question about the wallet, a
balance, a price or a swap opens the whole app, pre-filled with whatever the
conversation supplied — chain, tokens, amount. Inside it:
* the header shows the chain and the connected address, or a **Connect**
button that pairs a wallet by QR;
* two token boxes with balances, a rate chip, and the Fibrous route;
* one primary button whose label is the state — *Connect wallet*, *Enter an
amount*, *Insufficient ETH balance*, **Simulate**, **Swap**, *Waiting…*,
*Confirmed* — so a swap cannot skip its simulation;
* the signing policy as a collapsible section, editable in place, and a
refusal from it shown with the rule named.
The app executes nothing on its own. A swap leaves it only when the user
presses Swap, after Simulate, and it still passes through the local signing
policy. The model never gets to press the button; what it receives is a
sentence describing the state (*quoted*, *broadcast*, *settled*, *reverted*,
*unresolved*) so it can report honestly.
In a text-only host the same call returns a JSON snapshot the model can
summarise, and the headless tools below do the rest.
## Available Tools
FibX exposes **19 tools**. The reference below groups them by the app,
read-only, transactional, and session behavior.
### The App
| Tool | Description | Auth Required |
| ------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------- |
| `open_fibx` | Open the FibX app — wallet, balances, signing policy and a swap form — pre-filled from `chain`, `from`, `to`, `amount` | No |
| `list_tokens` | List the tokens Fibrous supports on a chain, with address, decimals and USD price where known | No |
### Read-Only
| Tool | Description | Auth Required |
| -------------------- | ------------------------------------------------------------- | ------------- |
| `get_quote` | Get a swap price quote, exchange rate, and route info | No |
| `get_auth_status` | Check session, signing path, and Fibrous API health | No |
| `get_connect_status` | Poll a pairing started by `connect_wallet` | No |
| `get_policy` | Read the local signing policy that bounds every transaction | No |
| `get_tx_status` | Check transaction receipt and status | No |
| `get_aave_markets` | List Aave V3 reserves with APY, supply/borrow totals, and LTV | No |
| `get_balance` | Get native and ERC-20 token balances | Yes |
| `get_portfolio` | Get cross-chain portfolio and DeFi positions | Yes |
| `get_aave_status` | Get Aave V3 position health on Base | Yes |
`get_quote` needs no wallet and no session. An agent can answer "what would 1 ETH get me in USDC?" before the user has authenticated at all — useful as a first interaction.
### Transactional
These tools carry the MCP `destructiveHint` annotation. Clients may use the hint
to request confirmation, but confirmation behavior is client-dependent. All
three accept `simulate=true`; its behavior is specific to each tool.
| Tool | Description |
| ------------- | ------------------------------------------------------- |
| `swap_tokens` | Swap tokens via Fibrous aggregator with optimal routing |
| `send_tokens` | Send native or ERC-20 tokens to a recipient |
| `aave_action` | Supply, borrow, repay, or withdraw on Aave V3 (Base) |
`simulate=true` returns a no-broadcast preview, but the available checks differ
by tool. If a swap needs ERC-20 approval, the preview reports
`requiresApproval: true` without submitting the approval or estimating swap
gas. `aave_action` returns normalized request metadata without on-chain
validation or a gas estimate. A preview does not guarantee that later
execution will succeed.
### Session and Configuration
These change local state rather than chain state. `set_policy_rule`,
`clear_policy_rule`, and `logout` also carry `destructiveHint` — each can
remove a bound that was protecting the wallet, or end the session outright.
| Tool | Description |
| ------------------- | ---------------------------------------------------------------------------- |
| `connect_wallet` | Start a WalletConnect pairing; **replaces the active session** on approval |
| `config_action` | Set or view custom RPC URLs to avoid rate limits |
| `set_policy_rule` | Set one rule on the local signing policy — replaces an existing rule's value |
| `clear_policy_rule` | Remove one policy rule, or the whole policy with `all: true` |
| `logout` | End the WalletConnect pairing and clear the local session |
## Tool Details
### open\_fibx
Open the FibX app. In a host that renders MCP Apps UI this is the entry point
for anything about the wallet, a balance, a quote or a swap.
| Parameter | Type | Required | Description |
| ---------- | ------ | -------- | ----------------------------------------------- |
| `chain` | string | No | `base`, `hyperevm`, or `monad` (default `base`) |
| `from` | string | No | Source token symbol, to pre-fill a swap |
| `to` | string | No | Destination token symbol |
| `amount` | string | No | Amount of the source token |
| `slippage` | number | No | Slippage tolerance in percent (default `0.5`) |
**Output:** `chain`, `auth` (as `get_auth_status` reports it), `balances`
(`null` without a session), `policy`, `terms` (the resolved `from`/`to`/`amount`),
`quote` (the Fibrous route when all three were given) and `quoteError`. A quote
that could not be fetched sets `quoteError` rather than failing the call, so
the app still opens. The app requests one host permission, `clipboardWrite`,
for the Copy link button on the pairing screen.
**Example prompts:** "What's in my wallet?", "How much USDC would 0.01 ETH get me?", "Swap 0.01 ETH to USDC"
### list\_tokens
List the tokens Fibrous supports on a chain. Feeds the app's token picker;
useful headlessly to resolve a symbol before `get_quote` or `swap_tokens`.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------------------- |
| `chain` | string | No | `base`, `hyperevm`, or `monad` (default `base`) |
**Output:** `chain` and `tokens`, each with `symbol`, `name`, `address`,
`decimals`, and `price` where known.
### get\_quote
Get a swap quote without a wallet or session.
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------------- |
| `amount` | string | Yes | Amount of the source token to quote |
| `from_token` | string | Yes | Source token symbol (e.g. `ETH`, `USDC`) |
| `to_token` | string | Yes | Target token symbol (e.g. `USDC`, `DAI`) |
| `chain` | string | No | `base`, `hyperevm`, or `monad` |
| `slippage` | number | No | Slippage tolerance in percent (default: `0.5`) |
**Output:** Routed swaps return `input`, `output`, `rate`, `slippage`, `router`,
`chain`, and a nested `quote` with `outputAmount`, `minReceived`, `usdIn`,
`usdOut`, `priceImpact`, and `route` — the Fibrous route with protocol names,
as the FibX app draws it. Direct native/wrapped-native pairs return `input`,
`output`, `rate`, `operation` (`wrap` or `unwrap`), and `chain`.
### get\_auth\_status
Check whether FibX is authenticated, which signing path is active, and whether the Fibrous API is reachable.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------ |
| `chain` | string | No | `base`, `hyperevm`, or `monad` |
**Output:** Object with `authenticated`, `walletAddress`, `sessionType`
(`walletconnect`, `privy`, or `private-key`), `authType`,
`requiresApprovalPerTransaction` (`true` for a WalletConnect session — the
wallet itself prompts for every transaction), `chain`, `fibrousStatus`
### connect\_wallet
Start a WalletConnect pairing. Returns immediately; show the QR, then poll
with `get_connect_status`. On approval the pairing **replaces** the active
session, whatever path it used.
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------------- |
| none | n/a | n/a | No input required |
**Output:** `uri` (the `wc:` link), `qrDataUri` (a PNG data URI of the QR), `pairingId`
### get\_connect\_status
Poll a pairing started by `connect_wallet` by its `pairingId`. Reports whether
the wallet has approved, and the connected address once it has.
### get\_policy
Read the local signing policy without changing it. No session needed.
**Output:** `state` (`active`, `absent`, or `unreadable`), `rules`, `path`,
`message`. `absent` means nothing limits what this wallet will sign;
`unreadable` means a file exists but could not be parsed, which refuses every
transaction until it is fixed or removed.
**Example prompts:** "What's my current signing policy?" or "Is anything limiting what fibx can sign?"
### get\_balance
Fetch token balances for the active wallet. The native-token entry is returned
even when its balance is zero; ERC-20 entries are limited to non-zero balances.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------ |
| `chain` | string | No | `base`, `hyperevm`, or `monad` |
**Output:** Object with `wallet`, `chain`, and `balances` (e.g. ETH, USDC with amounts)
### get\_portfolio
Get a consolidated portfolio across all supported chains, including USD-valued token holdings and DeFi positions.
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------------- |
| none | n/a | n/a | No input required |
**Output:** Object with total portfolio USD value, per-chain assets, and DeFi position summaries
**Example prompts:** "Show me my portfolio" or "What's my total net worth across all chains?"
### swap\_tokens
Execute a token swap through Fibrous. Handles routing and any required ERC-20
approval.
| Parameter | Type | Required | Description |
| ------------ | ------- | -------- | ----------------------------------------------------- |
| `amount` | string | Yes | Amount of the source token to swap |
| `from_token` | string | Yes | Source token symbol (e.g. `ETH`, `USDC`) |
| `to_token` | string | Yes | Target token symbol (e.g. `USDC`, `DAI`) |
| `chain` | string | No | `base`, `hyperevm`, or `monad` |
| `slippage` | number | No | Slippage tolerance in percent (default 0.5), 0.01–50 |
| `simulate` | boolean | No | Return a no-broadcast preview; gas may be unavailable |
**Execution output:** `txHash`, `amountIn`, `amountOut`, `tokenIn`, `tokenOut`,
`router`, `chain`, and `explorer` when available.
**Preview output:** Direct wrap/unwrap previews return `success`, `mode`,
`operation`, `amountIn`, `tokenIn`, `tokenOut`, and `chain`. Routed previews
also return `amountOut`, `router`, and `requiresApproval`; `estimatedGas` is
included only when the swap can be estimated without first broadcasting an
approval.
A live routed ERC-20 swap may confirm an approval transaction before
estimating and submitting the swap. If the later swap step fails, that
approval remains on-chain. `simulate=true` broadcasts neither transaction.
**Example prompt:** "Swap 0.1 ETH to USDC on Base"
### send\_tokens
Transfer native or ERC-20 tokens.
| Parameter | Type | Required | Description |
| ----------- | ------- | -------- | -------------------------------------------- |
| `amount` | string | Yes | Amount to send |
| `recipient` | string | Yes | Recipient address (0x-prefixed) |
| `token` | string | No | Token symbol (omit for native token) |
| `chain` | string | No | `base`, `hyperevm`, or `monad` |
| `simulate` | boolean | No | Preflight the transfer without submitting it |
**Execution output:** `txHash`, `amount`, `token`, `recipient`, `chain`, and
`explorer` when available.
**Preview output:** Both paths return `success`, `mode`, `amount`, `token`,
`recipient`, and `chain`. Native-token previews also return `estimatedGas`;
ERC-20 previews validate the transfer contract call without a gas field.
**Example prompt:** "Send 50 USDC to 0x1234..."
### get\_tx\_status
Look up a transaction receipt by hash.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------ |
| `hash` | string | Yes | Transaction hash (0x-prefixed) |
| `chain` | string | No | Must match the chain of the original transaction |
**Output:** Object with `hash`, `status`, `blockNumber`, `from`, `to`, `gasUsed`,
`chain`, and `explorer` when available.
### get\_aave\_status
Get Aave V3 account health on Base.
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------------- |
| none | n/a | n/a | No input required |
**Output:** Object with `wallet`, `healthFactor`, `totalCollateralUSD`, `totalDebtUSD`, `availableBorrowsUSD`
### get\_aave\_markets
List Aave V3 reserve markets on Base. No wallet or session is required.
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------------- |
| none | n/a | n/a | No input required |
**Output:** Object with `chain`, `marketCount`, and `markets`. Each market
includes `symbol`, `supplyAPY`, `borrowAPY`, `totalSupply`, `totalBorrow`, `ltv`,
and `isFrozen`.
### aave\_action
Execute an Aave V3 operation on Base. ETH supply and repay can auto-wrap, ETH
withdraw can auto-unwrap, and borrowing the ETH market returns WETH. Use `max`
only for full repay or withdraw.
| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | --------------------------------------------------------------------- |
| `action` | string | Yes | `supply`, `borrow`, `repay`, or `withdraw` |
| `amount` | string | Yes | Amount; `max` is allowed only for repay/withdraw |
| `token` | string | Yes | Token symbol (`ETH`, `USDC`, `DAI`, etc.) |
| `simulate` | boolean | No | Return an action preview without submitting it; does not estimate gas |
**Execution output:** `action`, `amount`, `token`, `txHash`, `chain`, and
`explorer` when available. A repay with no remaining debt instead returns
`status` and no transaction hash.
**Preview output:** `success`, `mode` (`PREVIEW (no TX sent)`), `action`,
`amount`, `token`, `chain`, and `note`. The note states that no on-chain
validation, gas estimate, or transaction was performed.
Live wrap, approval, Aave, and unwrap steps are separate transactions, so an
earlier step remains on-chain if a later one fails. For an ETH withdrawal,
the output transaction hash identifies the Aave withdrawal transaction, not
the separate unwrap transaction. With `action: "withdraw"`, `amount: "max"`,
and `token: "ETH"`, FibX unwraps the wallet's entire post-withdraw WETH
balance, including WETH held before the request.
**Example prompts:** "Supply 0.5 ETH to Aave" or "Repay max USDC on Aave"
### config\_action
Manage custom RPC URLs. Useful when encountering rate limits on public endpoints.
| Parameter | Type | Required | Description |
| --------- | ------ | ----------- | -------------------------------------------- |
| `action` | string | Yes | `set-rpc`, `get-rpc`, `reset-rpc`, or `list` |
| `chain` | string | Conditional | Required for `set-rpc` and `get-rpc` |
| `url` | string | Conditional | Required for `set-rpc` — full RPC endpoint |
**Output:** Object with `action`, `chain`, `url`, or `rpcUrls` depending on the action
**Example prompts:** "I'm getting rate limited on Base, set a custom RPC" or "Reset all RPCs to default"
### set\_policy\_rule
Set one rule on the local signing policy — `expiry`, `allowedChains`,
`.maxValue`, or `.allowedDestinations`. Lists are comma-separated.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------ |
| `rule` | string | Yes | The rule name |
| `value` | string | Yes | The value; comma-separated for lists |
**Output:** `ok`, `rule`, `value`, and the resulting `rules`
Setting a rule that already exists **replaces** its value — a cap can be
widened as easily as it was tightened, which is why this tool carries
`destructiveHint`. `maxValue` bounds only the native value of a transaction;
use `allowedDestinations` to bound where tokens may go.
**Example prompts:** "Cap Base transactions at 0.05 ETH" or "Only allow sending to my own address on Base"
### clear\_policy\_rule
Remove one rule from the local signing policy, or the whole policy.
| Parameter | Type | Required | Description |
| --------- | ------- | -------- | --------------------------------- |
| `rule` | string | One of | The rule to remove |
| `all` | boolean | One of | `true` to remove the whole policy |
**Output:** `ok`, `changed`, `rule`, the remaining `rules`, and a `message`
### logout
End the WalletConnect pairing, if any, and clear the local session.
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------------- |
| none | n/a | n/a | No input required |
## Supported Chains
| Chain | Native Token | Fibrous Network |
| -------- | ------------ | --------------- |
| Base | ETH | base |
| HyperEVM | HYPE | hyperevm |
| Monad | MON | monad |
## Environment Variables
| Variable | Description |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FIBX_API_URL` | Custom fibx-server URL (for Privy wallet operations) |
| `FIBX_SESSION_SECRET` | Custom encryption key for the session file (64-char hex); auto-generated per machine when unset |
| `FIBX_WC_PROJECT_ID` | WalletConnect Cloud project id for `connect_wallet`; a shared id ships in the package, set your own from [cloud.reown.com](https://cloud.reown.com) if pairing fails on quota |
If using Privy authentication, ensure `fibx-server` is running and accessible before starting the MCP server.
## Troubleshooting
| Problem | Solution |
| -------------------------- | ------------------------------------------------------------------------------------------------------ |
| Server will not start | Ensure Node.js 18+ is installed and `npx fibx --version` works |
| "Not authenticated" errors | Run `fibx auth setup` before using wallet-dependent tools, or pair with `connect_wallet` |
| `POLICY_BLOCKED` | The local signing policy refused it and named the rule; change it with `set_policy_rule` or in the app |
| Wallet operations fail | Ensure `fibx-server` is running when using Privy-managed wallets |
| Rate limit errors | Use `config_action` to set a custom RPC URL |
| Editor cannot connect | Verify the MCP config JSON syntax and restart the editor |
| The app does not appear | The host does not render MCP Apps; the model gets `open_fibx`'s JSON snapshot instead |
| The app is out of date | Quit the host fully (`Cmd+Q`) — the server process only starts at app launch |
# Signing Paths and the Local Policy
Source: https://docs.fibrous.finance/fibx-agent/signing
How FibX signs — your own wallet over WalletConnect, a Privy server wallet, or an imported key — and the signing policy file that bounds all three.
Every FibX transaction is signed through one of three paths. They are peers,
not a default with fallbacks, and `fibx auth setup` presents the choice:
| Path | Command | Key held by | Runs while you are away | Bounded by |
| -------------------- | ---------------------------- | ----------------------- | ------------------------------------------------ | --------------------------------------------- |
| Your own wallet | `auth connect` | your wallet app | No — every transaction is approved on your phone | the wallet, plus the local policy |
| Privy server wallet | `auth login` + `auth verify` | Privy, server-side | Yes | Privy's signing policy, plus the local policy |
| Imported private key | `auth import` | this machine, encrypted | Yes | **the local policy alone** |
Keeping your own wallet *and* having FibX act unattended needs ERC-7715, which
wallets do not yet expose over WalletConnect. `fibx auth setup` explains the
closest options.
## Choosing a path
```bash theme={null}
npx fibx@latest auth setup
```
The prompt offers four choices and a cancel:
* **Connect a wallet I already have** — runs `auth connect`.
* **Create a wallet FibX can use on its own** — runs the Privy email flow.
* **Import a private key onto this machine** — runs `auth import`.
* **None of these — I want my own wallet AND unattended operation** — explains
the ERC-7715 gap and the nearest alternatives.
Any of these **replaces** the active session, and ends a WalletConnect pairing
it is replacing.
### Your own wallet, over WalletConnect
```bash theme={null}
npx fibx@latest auth connect
```
The CLI prints a QR code and a `wc:` URI, then waits. Scan the QR with your
wallet app (or paste the URI into it) and approve the pairing. From then on
the wallet prompts for **every** transaction: a `trade` or `send` blocks until
you approve it on your phone, and a rejection there is normal — nothing is
sent. Nothing is signed on the machine running FibX.
`--json` prints `{ "uri": "wc:…" }` instead of the QR, for a host that renders
its own. A shared WalletConnect project id ships in the package; set
`FIBX_WC_PROJECT_ID` to your own from [cloud.reown.com](https://cloud.reown.com)
if pairing starts failing on quota.
### A Privy server wallet, via email OTP
```bash theme={null}
npx fibx@latest auth login user@example.com
npx fibx@latest auth verify user@example.com 123456
```
Creates a server-managed wallet through [Privy](https://privy.io). Signing is
requested through [fibx-server](https://github.com/Fibrous-Finance/fibx-server);
the private key is never returned to the CLI. Privy evaluates its own signing
policy — chain allowlist, native-value cap, key-export denial — at signing
time, on top of the local policy below. Sessions are JWTs with a 7-day expiry.
### An imported private key
```bash theme={null}
npx fibx@latest auth import
```
Interactive: paste the key at the prompt; it cannot be passed as an argument.
The key is encrypted at rest with AES-256-GCM and used to sign locally. This
path runs unattended and needs no server — and **the local policy is the only
thing bounding what it signs**. Set one before the first transaction.
With an imported key, no policy means nothing limits what this wallet will
sign. `fibx policy show` says so in as many words.
## The local signing policy
A JSON file the user owns, stored beside the session as `policy.json` in the
FibX config directory (`~/.config/fibx-nodejs/` on Linux,
`~/Library/Preferences/fibx-nodejs/` on macOS), written with mode `0600`. FibX
evaluates it **before every signature on all three paths** — in a wrapper
around the local-key and Privy signers, and in the WalletConnect provider
before a request reaches the relay.
| Rule | Meaning | Example |
| ----------------------------- | ---------------------------------------------------------- | ---------------------------------------- |
| `.maxValue` | Largest native value (ETH / HYPE / MON) in one transaction | `base.maxValue 0.05` |
| `allowedChains` | Chains anything may be signed on | `allowedChains base,monad` |
| `.allowedDestinations` | Addresses anything may be sent to on that chain | `base.allowedDestinations 0xAbC…,0xDeF…` |
| `expiry` | When the whole policy stops applying (ISO-8601) | `expiry 2026-12-31T00:00:00Z` |
```bash theme={null}
# Show the active policy, or that there is none
npx fibx@latest policy show
# Set one rule — replaces that rule's previous value
npx fibx@latest policy set base.maxValue 0.05
npx fibx@latest policy set allowedChains base,monad
npx fibx@latest policy set base.allowedDestinations 0xAbC...,0xDeF...
# Remove one rule, or the whole policy (asks for confirmation)
npx fibx@latest policy clear base.maxValue
npx fibx@latest policy clear
```
Three states, not two:
* **Absent** — no file. Everything is permitted.
* **Active** — the rules apply. A transaction outside them is refused before
any signature is requested, with `POLICY_BLOCKED` and the rule and limit
named.
* **Unreadable** — a file exists but cannot be parsed. **Everything is
refused** until it is fixed or cleared. This is deliberately distinct from
absent; a corrupt policy must not fail open.
**`maxValue` bounds the native value only.** An ERC-20 transfer reaches the
policy as a call to the token contract with `value: 0`, so the cap never sees
the token amount. `allowedDestinations` is what bounds where tokens may go.
The product argument is that this file is the user's, on the user's machine,
in front of every signing path — including the one where a misbehaving model
is the threat it exists for. It is a file, so it is worth nothing against
something that can already write to the user's disk. Over MCP the same file
is read and edited by `get_policy`, `set_policy_rule` and
`clear_policy_rule`, and the FibX app shows it as a collapsible section.
## Session management
```bash theme={null}
# Which path is active, the address, and Fibrous API health
npx fibx@latest status
# The active wallet address
npx fibx@latest address
# End the session (also ends a WalletConnect pairing)
npx fibx@latest auth logout
```
Sessions live in `session.json` beside the policy. Set `FIBX_SESSION_SECRET`
(64-char hex) to use a custom encryption key instead of the per-machine one,
for CI or Docker.
# Supported Chains
Source: https://docs.fibrous.finance/fibx-agent/supported-chains
Chain-specific reference for FibX — native tokens, CLI flags, feature availability, and block explorers.
FibX supports three EVM-compatible chains. Commands that accept `--chain`
default to **Base**; portfolio spans all supported chains, while Aave always
targets Base.
## Chain Overview
| Chain | Native Token | Chain ID | CLI Flag | Aave V3 |
| -------- | ------------ | -------- | ------------------ | ------- |
| Base | ETH | 8453 | `--chain base` | Yes |
| HyperEVM | HYPE | 999 | `--chain hyperevm` | No |
| Monad | MON | 143 | `--chain monad` | No |
Citrea was delisted by Fibrous on 2026-08-10 and withdrawn from FibX in
v0.10.0. `--chain citrea` is refused, and the portfolio no longer queries it.
## Chain Details
Base is Coinbase's Layer 2 network built on the OP Stack. It is the default
for chain-aware FibX commands and the only chain with Aave V3 support.
| Property | Value |
| ------------ | -------------------------------- |
| Native Token | ETH |
| Chain ID | 8453 |
| CLI Flag | `--chain base` |
| Aave V3 | Yes |
| Explorer | [BaseScan](https://basescan.org) |
```bash theme={null}
# Base-default commands, cross-chain portfolio, and Base-only Aave
npx fibx@latest balance
npx fibx@latest portfolio
npx fibx@latest trade 0.1 ETH USDC
npx fibx@latest aave markets
npx fibx@latest aave supply 100 USDC
```
HyperEVM is the EVM-compatible execution environment within the Hyperliquid ecosystem, enabling smart contract deployment alongside Hyperliquid's high-performance order book.
| Property | Value |
| ------------ | ---------------------------------------- |
| Native Token | HYPE |
| Chain ID | 999 |
| CLI Flag | `--chain hyperevm` |
| Aave V3 | No |
| Explorer | [HyperEVM Scan](https://hyperevmscan.io) |
```bash theme={null}
npx fibx@latest balance --chain hyperevm
npx fibx@latest trade 1 HYPE USDC --chain hyperevm
npx fibx@latest send 0.5 0xRecipient HYPE --chain hyperevm
```
Monad is a high-performance EVM-compatible Layer 1 blockchain designed for parallel transaction execution, delivering high throughput while maintaining full Ethereum compatibility.
| Property | Value |
| ------------ | --------------------------------------- |
| Native Token | MON |
| Chain ID | 143 |
| CLI Flag | `--chain monad` |
| Aave V3 | No |
| Explorer | [Monad Vision](https://monadvision.com) |
```bash theme={null}
npx fibx@latest balance --chain monad
npx fibx@latest trade 1 MON USDC --chain monad
npx fibx@latest send 5 0xRecipient MON --chain monad
```
## Feature Availability by Chain
| Feature | Base | HyperEVM | Monad |
| ------------------- | ---- | -------- | ----- |
| Balance Check | Yes | Yes | Yes |
| Portfolio View | Yes | Yes | Yes |
| Token Transfers | Yes | Yes | Yes |
| Token Swaps | Yes | Yes | Yes |
| Signing Policy Cap | Yes | Yes | Yes |
| Aave V3 | Yes | No | No |
| Aave Markets | Yes | No | No |
| Tx Status | Yes | Yes | Yes |
| Send/Trade Preview | Yes | Yes | Yes |
| Aave Action Preview | Yes | No | No |
| JSON Output | Yes | Yes | Yes |
## Selecting a Chain
Use `--chain` with chain-aware commands such as `quote`, `status`, `balance`,
`send`, `trade`, and `tx-status`. Aave commands always target Base, `portfolio`
queries every supported chain, and `address`/`wallets` are chain-independent.
```bash theme={null}
# Explicit chain selection
npx fibx@latest trade 0.1 ETH USDC --chain base
npx fibx@latest balance --chain monad
# Shorthand with -c
npx fibx@latest balance -c hyperevm
```
# Best Route
Source: https://docs.fibrous.finance/integrate-best-trading/fibrous-sdk/best-route
Returns Best Route via Fibrous
The `getBestRoute` function finds the optimal trading route for a token swap through Fibrous's liquidity pools.
## Function Signature
```typescript theme={null}
/**
* Fetches the best route from the API.
* @param params Route parameters object.
* @returns Route response.
* @throws Error if the chain is not supported.
*/
getBestRoute(
params: getBestRouteParams,
): Promise;
```
### getBestRouteParams Type
```typescript theme={null}
type getBestRouteParams = {
amount: AmountType;
tokenInAddress: string;
tokenOutAddress: string;
chainId: number;
options?: Partial;
integrationData?: IntegrationData;
};
```
### IntegrationData Type
```typescript theme={null}
type IntegrationData = {
integratorAddress: string;
integratorFeePercentageBps?: number; // 0-500, maximum 5%
integratorSurplusPercentageBps?: number; // 0-5000, maximum 50%
};
```
## Parameters
| Parameter | Type | Description |
| ---------------------- | --------------- | ----------------------------------------------------- |
| params.amount | BigNumber | Amount to swap, formatted according to token decimals |
| params.tokenInAddress | string | Token address to swap from |
| params.tokenOutAddress | string | Token address to swap to |
| params.chainId | number | Chain ID where the transaction will take place |
| params.options | RouteOverrides | Optional parameters for route customization |
| params.integrationData | IntegrationData | Optional integrator fee/surplus configuration |
### RouteOverrides Type
```typescript theme={null}
type RouteOverrides = {
reverse: boolean;
direct: boolean;
excludeProtocols: number[];
};
```
* **excludeProtocols**: This is where you list the IDs of the AMMs you don't want to include. For example, if there are certain AMMs you prefer not to use due to high fees or other reasons, you simply put their unique IDs (numbers) in this list.
* Use `supportedProtocols(chainId)` to get a list of supported AMMs and their IDs.
## RouteResponse Type
```typescript theme={null}
type RouteResponse = {
success: true;
inputToken: Token;
inputAmount: string;
outputToken: Token;
outputAmount: string;
estimatedGasUsed: string;
estimatedGasUsedInUsd?: number;
route: FormattedRoute[];
time: number;
bestQuotesByProtocols: string[];
initial?: boolean;
routeSwapType?: RouteSwapType;
integratorAddress?: string;
integratorFeePercentage?: number;
integratorSurplusPercentage?: number;
meta: {
apiVersion: string;
timestamp: string;
};
};
```
## Example Usage
```typescript theme={null}
import { Router as FibrousRouter, getBestRouteParams } from "fibrous-router-sdk";
import { parseUnits } from "ethers";
// Create a new router instance with v2 API
const fibrous = new FibrousRouter({
apiKey: "your-api-key", // optional, required for integrator features
apiVersion: "v2", // optional, v2 is the latest version
});
// Refresh and get supported chains
const chains = await fibrous.refreshSupportedChains();
const chainId = chains.find(chain => chain.chain_name == "hyperevm")?.chain_id;
if (!chainId) {
throw new Error("Chain not supported");
}
// Build route options
const tokens = await fibrous.supportedTokens(chainId);
// Get input token from tokens map
const inputToken = tokens.get("usdc");
if (!inputToken) {
throw new Error("Input token not found");
}
// Get output token by address (for unverified tokens)
const outputToken = await fibrous.getToken(
"0xb8ce59fc3717ada4c02eadf9682a9e934f625ebb",
chainId,
);
if (!outputToken) {
throw new Error("Output token not found");
}
const tokenInAddress = inputToken.address;
const tokenOutAddress = outputToken.address;
const tokenInDecimals = Number(inputToken.decimals);
const inputAmount = BigInt(parseUnits("4", tokenInDecimals)); // 4 USDC
const getBestRouteParams: getBestRouteParams = {
amount: inputAmount,
tokenInAddress: tokenInAddress,
tokenOutAddress: tokenOutAddress,
chainId: chainId,
options: {
reverse: false,
},
};
const route = await fibrous.getBestRoute(getBestRouteParams);
// returns route type (src/types/route.ts)
```
# Execute Batch Swap
Source: https://docs.fibrous.finance/integrate-best-trading/fibrous-sdk/execute-batch-swap
Learn how to execute multiple token swaps in a single transaction using Fibrous Router SDK
# Execute Batch Swap
Slippage is an important concept in trading that can have a significant impact on your trading outcomes. It refers to the difference between the expected price of a trade and the actual price at which the trade is executed. Slippage can occur in various market conditions and for several reasons, and it's crucial for traders to be aware of its potential effects.
Fibrous uses slippage settings to prevent you from losing money; there is no need to increase your slippage when you spot an arbitrage opportunity.
**Fibrous is still in alpha version. Please make sure you have adjusted your slippage properly.**
Generate transaction data for calling the Fibrous Router contract to execute multiple swaps in a single transaction.
## Basic Setup
First, let's set up the router and get the token information:
```typescript theme={null}
import { Router as FibrousRouter } from "fibrous-router-sdk";
import { parseUnits } from "ethers";
const fibrous = new FibrousRouter();
const chains = await fibrous.refreshSupportedChains();
const chainId = chains.find(chain => chain.chain_name == "starknet")?.chain_id;
if (!chainId) {
throw new Error("Chain not supported");
}
// Get the supported tokens for the Starknet chain
const tokens = await fibrous.supportedTokens(chainId);
const ethToken = tokens.get("eth");
const strkToken = tokens.get("strk");
const usdcToken = tokens.get("usdc");
const usdtToken = tokens.get("usdt");
if (!ethToken || !strkToken || !usdcToken || !usdtToken) {
throw new Error("Required tokens not found");
}
const tokenInAddress_1 = ethToken.address;
const tokenInAddress_2 = strkToken.address;
const tokenInAddress_3 = usdcToken.address;
const tokenOutAddress = usdtToken.address;
const tokenInDecimals_1 = ethToken.decimals;
const tokenInDecimals_2 = strkToken.decimals;
const tokenInDecimals_3 = usdcToken.decimals;
const inputAmounts = [
BigInt(parseUnits("0.001", tokenInDecimals_1)), // 0.001 ETH
BigInt(parseUnits("10", tokenInDecimals_2)), // 10 STRK
BigInt(parseUnits("5", tokenInDecimals_3)), // 5 USDC
];
```
## Usage on Backend
For backend implementations on Starknet:
```typescript theme={null}
import { Router as FibrousRouter } from "fibrous-router-sdk";
import { Call } from "starknet";
import { parseUnits } from "ethers";
import { account } from "./account";
const fibrous = new FibrousRouter();
const chainId = fibrous.supportedChains.find(chain => chain.chain_name == "starknet")?.chain_id;
if (!chainId) {
throw new Error("Chain not supported");
}
// Get the supported tokens for the Starknet chain
const tokens = await fibrous.supportedTokens(chainId);
const ethToken = tokens.get("eth");
const strkToken = tokens.get("strk");
const usdcToken = tokens.get("usdc");
const usdtToken = tokens.get("usdt");
if (!ethToken || !strkToken || !usdcToken || !usdtToken) {
throw new Error("Required tokens not found");
}
const tokenInAddress_1 = ethToken.address;
const tokenInAddress_2 = strkToken.address;
const tokenInAddress_3 = usdcToken.address;
const tokenOutAddress = usdtToken.address;
const tokenInDecimals_1 = ethToken.decimals;
const tokenInDecimals_2 = strkToken.decimals;
const tokenInDecimals_3 = usdcToken.decimals;
const inputAmounts = [
BigInt(parseUnits("0.001", tokenInDecimals_1)), // 0.001 ETH
BigInt(parseUnits("10", tokenInDecimals_2)), // 10 STRK
BigInt(parseUnits("5", tokenInDecimals_3)), // 5 USDC
];
const public_key = process.env.STARKNET_PUBLIC_KEY;
const privateKey = process.env.STARKNET_PRIVATE_KEY;
const RPC_URL = process.env.STARKNET_RPC_URL;
const destination = process.env.STARKNET_PUBLIC_KEY; // The address to receive the tokens after the swap is completed (required)
if (!privateKey || !public_key || !RPC_URL || !destination) {
throw new Error("Missing environment variables");
}
// Call the buildTransaction method in order to build the transaction
// slippage: The maximum acceptable slippage of the buyAmount amount.
const slippage = 1; // 1%
const tokenInAddresses = [
tokenInAddress_1,
tokenInAddress_2,
tokenInAddress_3,
];
const tokenOutAddresses = [tokenOutAddress];
const swapCalls = await fibrous.buildBatchTransaction(
inputAmounts,
tokenInAddresses,
tokenOutAddresses,
slippage,
destination,
chainId,
{reverse: false, direct: false, excludeProtocols: []}, // excludeProtocols is array of protocol IDs (numbers)
);
// https://www.starknetjs.com/docs/guides/connect_account
// If this account is based on a Cairo v2 contract (for example OpenZeppelin account 0.7.0 or later), do not forget to add the parameter "1" after the privateKey parameter
const account0 = account(privateKey, public_key, "1", RPC_URL);
const approveCalls: Call[] = [];
for (let i = 0; i < inputAmounts.length; i++) {
const approveCall: Call = await fibrous.buildApproveStarknet(
inputAmounts[i],
tokenInAddresses[i],
);
approveCalls.push(approveCall);
}
// Type guard: Starknet chains return Call[]
if (
Array.isArray(swapCalls) &&
swapCalls.every(
(call) => "contractAddress" in call && "entrypoint" in call,
)
) {
const resp = await account0.execute([...approveCalls, ...swapCalls]);
console.log(`https://voyager.online/tx/${resp.transaction_hash}`);
} else {
console.error("Invalid swap call data for Starknet batch transaction");
}
```
The swap call returns a transaction object with the following structure:
```typescript theme={null}
{
contractAddress:ROUTER_ADDRESS,
entrypoint: "swap",
calldata: calldata,
}
```
## Important Notes
1. All swaps in a batch must succeed for the transaction to be successful
2. Make sure to have sufficient balance for all tokens being swapped
3. Approve all tokens before executing the batch swap
4. Consider gas costs for multiple swaps in a single transaction
5. Monitor the transaction status for all swaps in the batch
6. Handle errors appropriately for each swap in the batch
## Related Topics
* [Execute Swap](/integrate-best-trading/fibrous-sdk/execute-swap)
* [Best Route](/integrate-best-trading/fibrous-sdk/best-route)
* [Supported Tokens](/integrate-best-trading/fibrous-sdk/supported-tokens)
# SDK Overview
Source: https://docs.fibrous.finance/integrate-best-trading/fibrous-sdk/index
Integrate Fibrous into your application with our powerful TypeScript SDK
## Introduction
Fibrous Router SDK is a TypeScript library that provides a simple and efficient way to integrate optimal token swaps into your decentralized applications. Built on top of the Fibrous Router API, it handles all the complexity of finding the best routes and executing swaps across multiple chains.
## Why Use the SDK?
Full TypeScript support with comprehensive type definitions
Single interface for Base, HyperEVM, Citrea, Monad, and Starknet
Simple API that abstracts away complex routing logic
Automatically finds the best swap paths across all DEXs
## Supported Chains
The SDK supports the following blockchain networks:
| Chain | Chain ID |
| ------------ | -------- |
| **Starknet** | SN\_MAIN |
| **Base** | 8453 |
| **Citrea** | 4114 |
| **HyperEVM** | 998 |
| **Monad** | 143 |
## Quick Start
```bash theme={null}
npm install fibrous-router-sdk
```
```typescript theme={null}
import { Router as FibrousRouter } from "fibrous-router-sdk";
const fibrous = new FibrousRouter({
apiVersion: "v2", // optional, v2 is the latest version
});
```
```typescript theme={null}
const chains = await fibrous.refreshSupportedChains();
const chainId = chains.find(chain => chain.chain_name == "base")?.chain_id;
const route = await fibrous.getBestRoute({
amount: inputAmount,
tokenInAddress,
tokenOutAddress,
chainId,
});
```
```typescript theme={null}
const { route, calldata } = await fibrous.buildRouteAndCalldata({
inputAmount,
tokenInAddress,
tokenOutAddress,
slippage: 0.5, // 0.5% slippage
destination: userAddress,
chainId,
});
```
## Key Features
### 🔍 Smart Routing
The SDK automatically finds the optimal route by:
* Aggregating liquidity from multiple DEX protocols
* Splitting large trades across multiple paths
* Minimizing price impact and slippage
* Considering gas costs in route optimization
### Batch Operations
Execute multiple swaps in a single transaction (Starknet):
```typescript theme={null}
const routes = await fibrous.getBestRouteBatch(
amounts,
tokenInAddresses,
tokenOutAddresses,
"starknet"
);
```
### Token Management
Easy access to supported tokens:
```typescript theme={null}
const tokens = await fibrous.supportedTokens(chainId);
const usdc = tokens.get("usdc");
```
### Protocol Flexibility
Exclude specific protocols or use only certain ones:
```typescript theme={null}
const chains = await fibrous.refreshSupportedChains();
const chainId = chains.find(chain => chain.chain_name == "base")?.chain_id;
const route = await fibrous.getBestRoute({
amount,
tokenInAddress: tokenIn,
tokenOutAddress: tokenOut,
chainId,
options: {
excludeProtocols: [1, 2], // Protocol IDs, not names
direct: false
}
});
```
## Complete Example
Here's a complete example of swapping tokens on Base:
```typescript theme={null}
import { Router as FibrousRouter, getBestRouteParams, buildRouteAndCalldataParams } from "fibrous-router-sdk";
import { parseUnits } from "ethers";
async function swapTokens() {
// Initialize router with v2 API
const fibrous = new FibrousRouter({
apiVersion: "v2",
});
// Refresh and get supported chains
const chains = await fibrous.refreshSupportedChains();
const chainId = chains.find(chain => chain.chain_name == "base")?.chain_id;
if (!chainId) {
throw new Error("Chain not supported");
}
// Get supported tokens
const tokens = await fibrous.supportedTokens(chainId);
const eth = tokens.get("eth");
const usdc = tokens.get("usdc");
if (!eth || !usdc) {
throw new Error("Tokens not found");
}
// Prepare swap parameters
const inputAmount = BigInt(parseUnits("1", Number(eth.decimals))); // 1 ETH
const slippage = 0.5; // 0.5%
const userAddress = "0xYourAddress";
// Get best route
const getBestRouteParams: getBestRouteParams = {
amount: inputAmount,
tokenInAddress: eth.address,
tokenOutAddress: usdc.address,
chainId,
};
const route = await fibrous.getBestRoute(getBestRouteParams);
console.log(`Input: ${route.inputAmount} ${eth.symbol}`);
console.log(`Output: ${route.outputAmount} ${usdc.symbol}`);
// Build route and calldata
const buildRouteAndCalldataParams: buildRouteAndCalldataParams = {
inputAmount,
tokenInAddress: eth.address,
tokenOutAddress: usdc.address,
slippage,
destination: userAddress,
chainId,
};
const { route: routeData, calldata } = await fibrous.buildRouteAndCalldata(buildRouteAndCalldataParams);
// Execute with your wallet
// const receipt = await wallet.sendTransaction(tx);
return { route: routeData, calldata };
}
```
## Chain-Specific Examples
```typescript theme={null}
const fibrous = new FibrousRouter({ apiVersion: "v2" });
const chains = await fibrous.refreshSupportedChains();
const chainId = chains.find(chain => chain.chain_name == "base")?.chain_id;
const route = await fibrous.getBestRoute({
amount: BigInt(parseUnits("1", 18)),
tokenInAddress: "0x0000000000000000000000000000000000000000", // ETH
tokenOutAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC
chainId,
});
```
```typescript theme={null}
const fibrous = new FibrousRouter({ apiVersion: "v2" });
const chains = await fibrous.refreshSupportedChains();
const chainId = chains.find(chain => chain.chain_name == "hyperevm")?.chain_id;
const route = await fibrous.getBestRoute({
amount: BigInt(parseUnits("1", 18)),
tokenInAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", // HYPE
tokenOutAddress: "0xb88339cb7199b77e23db6e890353e22632ba630f", // USDC
chainId,
});
```
```typescript theme={null}
const fibrous = new FibrousRouter({ apiVersion: "v2" });
const chains = await fibrous.refreshSupportedChains();
const chainId = chains.find(chain => chain.chain_name == "citrea")?.chain_id;
const route = await fibrous.getBestRoute({
amount: BigInt(parseUnits("1", 18)),
tokenInAddress: "0x0000000000000000000000000000000000000000", // cBTC
tokenOutAddress: "0xE045e6c36cF77FAA2CfB54466D71A3aEF7bbE839", // USDC.e
chainId,
});
```
```typescript theme={null}
const fibrous = new FibrousRouter({ apiVersion: "v2" });
const chains = await fibrous.refreshSupportedChains();
const chainId = chains.find(chain => chain.chain_name == "starknet")?.chain_id;
const route = await fibrous.getBestRoute({
amount: BigInt(parseUnits("1", 18)),
tokenInAddress: "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7", // ETH
tokenOutAddress: "0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8", // USDC
chainId,
});
```
```typescript theme={null}
const fibrous = new FibrousRouter({ apiVersion: "v2" });
const chains = await fibrous.refreshSupportedChains();
const chainId = chains.find(chain => chain.chain_name == "monad")?.chain_id;
const route = await fibrous.getBestRoute({
amount: BigInt(parseUnits("1", 18)),
tokenInAddress: "0x0000000000000000000000000000000000000000", // ETH
tokenOutAddress: "0x754704bc059f8c67012fed69bc8a327a5aafb603", // USDC
chainId,
});
```
## SDK vs API
**Use the SDK when:**
* Building a TypeScript/JavaScript application
* You want type safety and autocomplete
* You need simplified integration
* Working with multiple chains
* You want built-in error handling
**Use the API when:**
* Building in a different language
* You need maximum flexibility
* Building a lightweight integration
* You have custom routing logic
* Working with a single chain
## Requirements
* **Node.js**: Version 18.x or higher
* **Web3 Provider**: ethers.js v6+ or starknet.js v5+
* **TypeScript**: Version 4.5+ (recommended)
## Installation
```bash npm theme={null}
npm install fibrous-router-sdk
```
```bash yarn theme={null}
yarn add fibrous-router-sdk
```
```bash pnpm theme={null}
pnpm add fibrous-router-sdk
```
## Next Steps
Detailed installation and setup instructions
Explore all available SDK methods
Learn how to find optimal swap routes
Build and execute swap transactions
## Resources
* [GitHub Repository](https://github.com/Fibrous-Finance/router-sdk)
* [NPM Package](https://www.npmjs.com/package/fibrous-router-sdk)
* [API Reference](/api-reference/introduction)
* [Discord Community](https://discord.gg/fibrous)
## Support
Need help? We're here for you:
* 💬 [Join our Discord](https://discord.gg/fibrous)
* 📧 [Email Support](mailto:contact@fibrous.finance)
* 🐛 [Report Issues](https://github.com/Fibrous-Finance/router-sdk/issues)
# Installation
Source: https://docs.fibrous.finance/integrate-best-trading/fibrous-sdk/installation
Learn how to install and setup Fibrous Router SDK
# Installation
You can install Fibrous Router SDK using npm, yarn, or pnpm:
Latest stable version: 1.0.1
```bash npm theme={null}
npm install fibrous-router-sdk
```
```bash yarn theme={null}
yarn add fibrous-router-sdk
```
```bash pnpm theme={null}
pnpm add fibrous-router-sdk
```
# Quick Start
Check out the detailed example in the [Fibrous SDK Github Repository](https://github.com/Fibrous-Finance/router-sdk) section for a simple example of how to initialize and use the SDK.
Here's a simple example of how to initialize and use the SDK:
```typescript theme={null}
import { Router as FibrousRouter, getBestRouteParams } from "fibrous-router-sdk";
import { parseUnits } from "ethers";
// Create a new router instance with v2 API
const fibrous = new FibrousRouter({
apiVersion: "v2", // optional, v2 is the latest version
});
// Refresh and get supported chains
const chains = await fibrous.refreshSupportedChains();
const chainId = chains.find(chain => chain.chain_name == "hyperevm")?.chain_id;
if (!chainId) {
throw new Error("Chain not supported");
}
// Build route options
const tokens = await fibrous.supportedTokens(chainId);
// Get input token from tokens map
const inputToken = tokens.get("usdc");
if (!inputToken) {
throw new Error("Input token not found");
}
// Get output token by address (for unverified tokens)
const outputToken = await fibrous.getToken(
"0xb8ce59fc3717ada4c02eadf9682a9e934f625ebb",
chainId,
);
if (!outputToken) {
throw new Error("Output token not found");
}
const tokenInAddress = inputToken.address;
const tokenOutAddress = outputToken.address;
const tokenInDecimals = Number(inputToken.decimals);
const inputAmount = BigInt(parseUnits("4", tokenInDecimals)); // 4 USDC
const getBestRouteParams: getBestRouteParams = {
amount: inputAmount,
tokenInAddress: tokenInAddress,
tokenOutAddress: tokenOutAddress,
chainId: chainId,
options: {
reverse: false,
},
};
const route = await fibrous.getBestRoute(getBestRouteParams);
```
# Requirements
* Node.js version 18.x or higher
* A Web3 provider (like ethers.js) for transaction signing
* Access to supported blockchain networks (Base, Citrea, HyperEVM, Monad, or Starknet)
# Next Steps
After installation, check out these guides to learn more about specific features:
* [Overview](/integrate-best-trading/fibrous-sdk/overview)
* [Supported Tokens](/integrate-best-trading/fibrous-sdk/supported-tokens)
* [Best Route](/integrate-best-trading/fibrous-sdk/best-route)
* [Execute Swap](/integrate-best-trading/fibrous-sdk/execute-swap)
# Overview
Source: https://docs.fibrous.finance/integrate-best-trading/fibrous-sdk/overview
Overview of Fibrous Router SDK main functions compatible with all supported chains v2 API
## Supported Chains
* Starknet
* Base
* Citrea
* HyperEVM
* Monad
```typescript theme={null}
/**
* List of supported chains and their router addresses.
*/
supportedChains: CHAIN_MAP[];
```
## Supported Tokens
Returns the list of Tokens supported by Fibrous
```typescript theme={null}
/**
* Returns the supported token list for a given chain.
* @param chainId Chain ID.
* @returns Map of lowercased symbol -> Token.
*/
supportedTokens(chainId: number): Promise>;
```
## Supported Protocols
Returns the list of Protocols supported by Fibrous
```typescript theme={null}
/**
* Returns supported protocols.
* @param chainId Chain ID.
* @returns Mapping of AMM name -> protocol identifier.
*/
supportedProtocols(chainId: number): Promise>;
```
## Best Route
Returns the best route via Fibrous
```typescript theme={null}
/**
* Fetches the best route from the API.
* @param params Route parameters object.
* @returns Route response.
* @throws Error if the chain is not supported.
*/
getBestRoute(
params: getBestRouteParams,
): Promise;
```
### getBestRouteParams Type
```typescript theme={null}
type getBestRouteParams = {
amount: AmountType;
tokenInAddress: string;
tokenOutAddress: string;
chainId: number;
options?: Partial;
integrationData?: IntegrationData;
};
```
### IntegrationData Type
```typescript theme={null}
type IntegrationData = {
integratorAddress: string;
integratorFeePercentageBps?: number; // 0-500, maximum 5%
integratorSurplusPercentageBps?: number; // 0-5000, maximum 50%
};
```
### RouteOverrides Type
```typescript theme={null}
type RouteOverrides = {
reverse: boolean;
direct: boolean;
excludeProtocols: number[]; // Array of protocol IDs
};
```
## Build Transaction
Returns calldata with best route to transaction via Fibrous
```typescript theme={null}
/**
* Legacy method that builds a route and calldata to prepare a transaction.
* Note: This will be deprecated; prefer `buildRouteAndCalldata`.
* @param params Transaction parameters object.
* @returns Starknet `Call` or EVM calldata/transaction structure.
*/
buildTransaction(
params: buildTransactionParams,
): Promise;
```
### buildTransactionParams Type
```typescript theme={null}
type buildTransactionParams = {
inputAmount: AmountType;
tokenInAddress: string;
tokenOutAddress: string;
slippage: number;
destination: string;
chainId: number;
options?: Partial;
integrationData?: IntegrationData;
};
```
## Build Route and Calldata
```typescript theme={null}
/**
* Returns the best route and executable calldata in a single call.
* @param params Route and calldata parameters object.
* @returns Route and calldata structure (includes Starknet swap call when applicable).
*/
buildRouteAndCalldata(
params: buildRouteAndCalldataParams,
): Promise;
```
### buildRouteAndCalldataParams Type
```typescript theme={null}
type buildRouteAndCalldataParams = {
inputAmount: AmountType;
tokenInAddress: string;
tokenOutAddress: string;
slippage: number;
destination: string;
chainId: number;
options?: Partial;
integrationData?: IntegrationData;
};
```
## Build Approve Starknet
```typescript theme={null}
/**
* Builds Starknet approve call parameters.
* @param amount Amount to approve (will be converted to hex).
* @param tokenAddress ERC-20 token address.
*/
buildApproveStarknet(amount: AmountType, tokenAddress: string): Promise;
```
## Build Approve EVM
```typescript theme={null}
/**
* Performs EVM approve if needed and returns the result.
* @param amount Amount to approve.
* @param tokenAddress ERC-20 token address.
* @param account Wallet/signer used for the transaction.
* @param chainId Chain ID.
* @returns `true` if allowance is sufficient or approve succeeded.
*/
buildApproveEVM(
amount: AmountType,
tokenAddress: string,
account: Wallet,
chainId?: number,
): Promise;
```
## Best Route Batch
```typescript theme={null}
/**
* Fetches best routes in batch for multiple inputs (Starknet and Base for now).
* @param amounts List of input amounts.
* @param tokenInAddresses Input token addresses.
* @param tokenOutAddresses Output token addresses.
* @param chainId Chain ID.
* @param options Optional route parameters.
* @returns List of route responses.
*/
getBestRouteBatch(
amounts: bigint[] | string[] | number[] | BigNumberish[],
tokenInAddresses: string[],
tokenOutAddresses: string[],
chainId: number,
options?: Partial,
): Promise;
```
## Build Batch Transaction
```typescript theme={null}
/**
* Builds calldata/call list for batch transactions (Starknet for now).
* @param inputAmounts Input amounts.
* @param tokenInAddresses Input token addresses.
* @param tokenOutAddresses Output token addresses.
* @param slippage Slippage percentage.
* @param destination Receiver address.
* @param chainId Chain ID.
* @param options Optional parameters.
* @returns Array of Starknet `Call`s or chain-specific payload.
*/
buildBatchTransaction(
inputAmounts: AmountType[],
tokenInAddresses: string[],
tokenOutAddresses: string[],
slippage: number,
destination: string,
chainId: number,
options?: Partial,
): Promise;
```
# Route and Calldata
Source: https://docs.fibrous.finance/integrate-best-trading/fibrous-sdk/route-and-calldata
Learn how to execute token swaps using Fibrous Router SDK
# Route and Calldata
Slippage is an important concept in trading that can have a significant impact on your trading outcomes. It refers to the difference between the expected price of a trade and the actual price at which the trade is executed. Slippage can occur in various market conditions and for several reasons, and it's crucial for traders to be aware of its potential effects.
Fibrous uses slippage settings to prevent you from losing money; there is no need to increase your slippage when you spot an arbitrage opportunity.
**Fibrous is still in alpha version. Please make sure you have adjusted your slippage properly.**
## Usage on EVM Networks (Base, Citrea, HyperEVM, Monad)
Here's how to execute a swap on EVM-compatible networks like Base, Citrea, HyperEVM and Monad:
```typescript theme={null}
import { Router as FibrousRouter, buildRouteAndCalldataParams } from "fibrous-router-sdk";
import { ethers, parseUnits } from "ethers";
import { account } from "./account";
import { humanReadableEvmSwapCallDataLog } from "../utils/humanReadableEvmLog";
import dotenv from "dotenv";
import { monitorTransaction } from "./utils";
dotenv.config();
// RPC URL for the EVM network, you can change this to the RPC URL of your choice
const RPC_URL = process.env.RPC_URL;
// Destination address for the swap (optional)
const destination = process.env.EVM_PUBLIC_KEY;
// Private key of the account that will be used to sign the transaction
const privateKey = process.env.EVM_PRIVATE_KEY;
const fibrous = new FibrousRouter({
apiKey: "your-api-key", // optional, required for integrator features
apiVersion: "v2",
});
if (!privateKey || !RPC_URL || !destination) {
throw new Error("Missing environment variables");
}
// Create a new contract instance
const account0 = account(privateKey, RPC_URL);
const chains = await fibrous.refreshSupportedChains();
const chainId = chains.find(chain => chain.chain_name == "hyperevm")?.chain_id;
if (!chainId) {
throw new Error("Chain not supported");
}
const contractWallet = await fibrous.getContractWAccount(account0 as any, chainId);
const provider = new ethers.JsonRpcProvider(RPC_URL);
// Build route options
const tokens = await fibrous.supportedTokens(chainId);
// const inputToken = await fibrous.getToken(
// "0xb8ce59fc3717ada4c02eadf9682a9e934f625ebb",
// chainId,
// );
const inputToken = tokens.get("usdc");
if (!inputToken) {
throw new Error("Input token not found");
}
const tokenInAddress = inputToken.address;
const outputToken = tokens.get("whype");
// if you want to search for a token that is not verified, you can use the getToken method
// const outputToken = await fibrous.getToken(
// "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", // USDC address
// "base",
// );
if (!outputToken) {
throw new Error("Output token not found");
}
const tokenOutAddress = outputToken.address;
const tokenInDecimals = Number(inputToken.decimals);
const inputAmount = BigInt(parseUnits("2", tokenInDecimals)); // 2 USDC
const isNativeToken =
tokenInAddress == "0x0000000000000000000000000000000000000000";
// Call the buildRouteAndCalldata method in order to build the transaction
// slippage: The maximum acceptable slippage of the buyAmount amount.
const slippage = 0.5; // 0.5%
const { route, calldata } = await fibrous.buildRouteAndCalldata({
inputAmount: inputAmount,
tokenInAddress: tokenInAddress,
tokenOutAddress: tokenOutAddress,
slippage,
destination: destination || account0.address,
chainId: chainId,
});
const approveResponse = await fibrous.buildApproveEVM(
inputAmount,
tokenInAddress,
account0 as any,
chainId,
);
humanReadableEvmSwapCallDataLog(
calldata,
inputToken,
outputToken,
await fibrous.supportedProtocols(chainId),
);
if (approveResponse === true) {
try {
// Type guard: EVM chains return EvmTransactionData
if ("route" in calldata && "swap_parameters" in calldata) {
const feeData = await provider.getFeeData();
if (!feeData.gasPrice) {
console.log("gasPrice not found");
return;
}
let tx;
if (isNativeToken) {
tx = await contractWallet.swap(
calldata.route,
calldata.swap_parameters,
{
value: inputAmount,
gasPrice: feeData.gasPrice * 4n,
},
);
} else {
tx = await contractWallet.swap(
calldata.route,
calldata.swap_parameters,
{
gasPrice: feeData.gasPrice * 2n,
},
);
}
await monitorTransaction(tx);
} else {
console.error("Invalid swap call data for EVM transaction");
}
} catch (e) {
console.error("Error swapping tokens: ", e);
}
} else {
console.error("Error approving tokens");
}
```
## Usage on Starknet
For Starknet, the process is slightly different due to its unique architecture:
```typescript theme={null}
import { Router as FibrousRouter } from "fibrous-router-sdk";
import { Call } from "starknet";
import { parseUnits } from "ethers";
import "dotenv/config";
import { account } from "./account";
import { humanReadableStarknetSwapCallDataLog } from "../utils/humanReadableStarknetLog";
const PUBLIC_KEY = process.env.STARKNET_PUBLIC_KEY;
const PRIVATE_KEY = process.env.STARKNET_PRIVATE_KEY;
const RPC_URL = process.env.STARKNET_RPC_URL;
const DESTINATION = process.env.STARKNET_PUBLIC_KEY; // The address to receive the tokens after the swap is completed (required)
// Create a new router instance
const fibrous = new FibrousRouter({
apiKey: "your-api-key", // optional, required for integrator features
apiVersion: "v2",
});
const chains = await fibrous.refreshSupportedChains();
const chainId = chains.find(chain => chain.chain_name == "starknet")?.chain_id;
if (!chainId) {
throw new Error("Chain not supported");
}
if (!DESTINATION || !PRIVATE_KEY || !RPC_URL || !PUBLIC_KEY) {
throw new Error("Missing environment variables");
}
// Get the supported tokens for the Starknet chain
const tokens = await fibrous.supportedTokens(chainId);
/**
* recommended that use the token address directly
* because there may be more than one token with the same symbol.
*/
const inputToken = await fibrous.getToken(
"0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7", // ETH address
chainId,
);
if (!inputToken) {
throw new Error("Input token not found");
}
const outputToken = tokens.get("strk"); // this search in only the tokens that are verified
// if you want to search for a token that is not verified, you can use the getToken method
// const outputToken = await fibrous.getToken(
// "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d", // STRK address
// "starknet",
// );
if (!outputToken) {
throw new Error("Output token not found");
}
const tokenInAddress = inputToken.address;
const tokenOutAddress = outputToken.address;
const tokenInDecimals = Number(inputToken?.decimals);
if (!tokenInAddress || !tokenOutAddress || !tokenInDecimals) {
throw new Error("Token not found");
}
const inputAmount = BigInt(parseUnits("0.0001", tokenInDecimals)); // 0.0001 ETH
// Call the buildRouteAndCalldata method in order to build the transaction
// slippage: The maximum acceptable slippage of the buyAmount amount.
const slippage = 1; // 1%
const { route, calldata } = await fibrous.buildRouteAndCalldata({
inputAmount: inputAmount,
tokenInAddress: tokenInAddress,
tokenOutAddress: tokenOutAddress,
slippage,
destination: DESTINATION,
chainId: chainId,
options: {
reverse: false,
direct: false,
excludeProtocols: [], // Array of protocol IDs (numbers)
},
});
// https://www.starknetjs.com/docs/guides/connect_account
// If this account is based on a Cairo v2 contract (for example OpenZeppelin account 0.7.0 or later), do not forget to add the parameter "1" after the privateKey parameter
const account0 = account(PRIVATE_KEY, PUBLIC_KEY, "1", RPC_URL);
const approveCall: Call = await fibrous.buildApproveStarknet(
inputAmount,
tokenInAddress,
);
humanReadableStarknetSwapCallDataLog(
calldata,
inputToken,
outputToken,
await fibrous.supportedProtocols(chainId),
);
// Type guard: Starknet chains return Call
if ("contractAddress" in calldata && "entrypoint" in calldata) {
const resp = await account0.execute([approveCall, calldata]);
console.log(`https://voyager.online/tx/${resp.transaction_hash}`);
} else {
console.error("Invalid swap call data for Starknet transaction");
}
```
## Important Notes
1. Always handle errors appropriately in production code
2. Set a reasonable slippage value based on your trading strategy
3. Make sure to have sufficient balance and approved tokens before executing swaps
4. Monitor transaction status and implement proper error handling
5. Consider implementing retry mechanisms for failed transactions
6. Keep private keys secure and never expose them in your code
## Related Topics
* [Best Route](/integrate-best-trading/fibrous-sdk/best-route)
* [Supported Tokens](/integrate-best-trading/fibrous-sdk/supported-tokens)
* [Supported Protocols](/integrate-best-trading/fibrous-sdk/supported-protocols)
# Supported Protocols
Source: https://docs.fibrous.finance/integrate-best-trading/fibrous-sdk/supported-protocols
Fetch a list of protocols supported by Fibrous api
The `supportedProtocols` function returns a list of protocols (AMMs) that are supported by Fibrous on a specific chain.
## Function Signature
```typescript theme={null}
/**
* Returns supported protocols.
* @param chainId Chain ID.
* @returns Mapping of AMM name -> protocol identifier.
*/
supportedProtocols(chainId: number): Promise>;
```
## Example Usage
```typescript theme={null}
import { Router as FibrousRouter } from "fibrous-router-sdk";
const router = new FibrousRouter({
apiVersion: "v2",
});
const chains = await router.refreshSupportedChains();
const chainId = chains.find(chain => chain.chain_name == "hyperevm")?.chain_id;
if (!chainId) {
throw new Error("Chain not supported");
}
const protocols = await router.supportedProtocols(chainId);
```
## Parameters
| Parameter | Type | Description |
| --------- | ------ | ---------------------------------------------------------------------------------- |
| chainId | number | The chain ID to get supported protocols for (e.g., 8453 for Base, 4114 for Citrea) |
## Response
Returns a Promise that resolves to a Record mapping protocol names to their IDs. The response includes:
```typescript theme={null}
type ProtocolId = {
id: number; // Protocol unique identifier
name: string; // Protocol name
logoURI?: string; // Optional protocol logo URL
};
```
## Example Response
```json theme={null}
[
{
"protocol": 1,
"amm_name": "hyperSwapV2",
"display_name": "HyperSwap V2",
"image_url": null,
"type": "v2"
},
{
"protocol": 2,
"amm_name": "hyperSwapV2Stable",
"display_name": "HyperSwap V2 Stable",
"image_url": null,
"type": "stable"
},
{
"protocol": 3,
"amm_name": "hyperSwapV3",
"display_name": "HyperSwap V3",
"image_url": null,
"type": "v3"
},
{
"protocol": 4,
"amm_name": "kittenSwapV2",
"display_name": "KittenSwap V2",
"image_url": null,
"type": "v2"
},
{
"protocol": 5,
"amm_name": "kittenSwapV2Stable",
"display_name": "KittenSwap V2 Stable",
"image_url": null,
"type": "stable"
},
{
"protocol": 6,
"amm_name": "kittenSwapV3",
"display_name": "KittenSwap V3",
"image_url": null,
"type": "v3"
},
{
"protocol": 7,
"amm_name": "laminarV2",
"display_name": "Laminar V2",
"image_url": null,
"type": "v2"
},
{
"protocol": 8,
"amm_name": "laminarV3",
"display_name": "Laminar V3",
"image_url": null,
"type": "v3"
},
{
"protocol": 9,
"amm_name": "ramsesV3",
"display_name": "Ramses V3",
"image_url": null,
"type": "v3"
},
{
"protocol": 10,
"amm_name": "projectX",
"display_name": "Project X",
"image_url": null,
"type": "v3"
}
...
]
```
# Supported Tokens
Source: https://docs.fibrous.finance/integrate-best-trading/fibrous-sdk/supported-tokens
Fetch a list of tokens supported by Fibrous API
The `supportedTokens` function returns a list of tokens supported by Fibrous on a specific chain.
## Function Signature
```typescript theme={null}
/**
* Returns the supported token list for a given chain.
* @param chainId Chain ID.
* @returns Map of lowercased symbol -> Token.
*/
supportedTokens(chainId: number): Promise>;
```
## Example Usage
```typescript theme={null}
import { Router as FibrousRouter } from "fibrous-router-sdk";
const router = new FibrousRouter();
const chains = await router.refreshSupportedChains();
const chainId = chains.find(
(chain) => chain.chain_name == "starknet",
)?.chain_id;
if (!chainId) {
throw new Error("Chain not supported");
}
const tokens = await router.supportedTokens(chainId);
```
## Parameters
| Parameter | Type | Description |
| --------- | ------ | ----------------------------------------------------------- |
| chainId | number | The chain id to get supported tokens for (e.g. 8453, 84532) |
## Response
Returns a Promise that resolves to a Record mapping token symbols to Token objects. Each Token object contains:
```typescript theme={null}
export type Token = {
// Address of the token contract
address: string;
// Name of the token
name: string;
// Symbol of the token
symbol: string;
// Decimal points of the token (can be string from API)
decimals: string;
// Price in USD (can be null or string from API)
price: string | null;
// Image URL for the token icon
image_url?: string;
// Base token flag (can be null)
base?: boolean | null;
// Native token flag (can be null)
native?: boolean | null;
// Verification status
verified?: boolean;
// Token category
category?: string | null;
// Legacy fields for backward compatibility
isBase?: boolean;
isNative?: boolean;
};
```
## Example Response
```json theme={null}
{
"ETH": {
"name": "Ethereum",
"symbol": "ETH",
"address": "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
"decimals": 18,
"price": null,
"image_url": "https://tokens.1inch.io/0x0000000000000000000000000000000000000000.png"
},
"USDC": {
"name": "USD Coin",
"symbol": "USDC",
"address": "0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5eb06f3ecf368a8",
"decimals": 6,
"price": null,
"image_url": "https://tokens.1inch.io/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.png"
}
}
```
# EVM Router - Swap Functions
Source: https://docs.fibrous.finance/integrate-best-trading/fibrous-smart-contracts/evm-router
Comprehensive guide to EVM Router swap functions including swap, swapIntegrator, and swapWithPermit
# EVM Router Swap Functions
EVM Router is the advanced router contract for executing token swaps across multiple protocols on EVM-compatible chains. It supports native token handling, multi-hop swaps, integrator fee/surplus sharing, and permit-based approvals.
## Overview
EVM Router provides three main swap functions:
1. **`swap`** - Standard swap function for normal token exchanges
2. **`swapIntegrator`** - Swap with integrator fee or surplus sharing
3. **`swapWithPermit`** - Swap with ERC-20 permit signature (gasless approval)
All swap functions support:
* **Multi-hop swaps** across different protocols
* **Native token handling** (MONAD ↔ WMONAD conversion)
* **Rate-based amount distribution** for splitting input across multiple swaps
* **Surplus handling** to cap output at expected amount
* **Minimum received protection** to ensure slippage tolerance
***
## Contract ABI
**Router Contract ABI**: The complete Application Binary Interface (ABI) for EVM Router is available on GitHub:
🔗 **[View Router ABI on GitHub](https://github.com/Fibrous-Finance/router-contract-abi/blob/main/routerAbi.json)**
The ABI includes all function signatures, event definitions, and error types needed for integration.
***
## Function: `swap`
Performs a standard token swap using the provided route and swap parameters.
### Signature
```solidity theme={null}
function swap(
RouteParam calldata route,
SwapParams[] calldata swap_parameters
) external payable nonReentrant whenNotPaused returns (uint256)
```
### Parameters
#### `route` (RouteParam)
The route parameters defining the overall swap path.
```solidity theme={null}
struct RouteParam {
address token_in; // Input token address
address token_out; // Output token address
uint256 amount_in; // Amount of input tokens to swap
uint256 amount_out; // Expected output amount (for surplus calculation)
uint256 min_received; // Minimum amount user must receive
address destination; // Recipient address (address(0) = msg.sender)
SwapType swap_type; // Type of swap (ethToToken, tokenToEth, tokenToToken)
}
```
| Field | Type | Description |
| -------------- | ---------- | -------------------------------------------------------------------------------------------------------- |
| `token_in` | `address` | Contract address of the input token to sell |
| `token_out` | `address` | Contract address of the output token to buy |
| `amount_in` | `uint256` | Amount of input tokens to swap (in token's smallest unit) |
| `amount_out` | `uint256` | Expected output amount. Used for surplus calculation - if actual output exceeds this, it's capped |
| `min_received` | `uint256` | Minimum amount of output tokens user must receive. Transaction reverts if actual output \< min\_received |
| `destination` | `address` | Address to receive output tokens. If `address(0)`, uses `msg.sender` |
| `swap_type` | `SwapType` | Enum indicating swap type: `ethToToken` (0), `tokenToEth` (1), `tokenToToken` (2) |
#### `swap_parameters` (SwapParams\[])
Array of swap parameters for each hop in the multi-hop swap.
```solidity theme={null}
struct SwapParams {
address token_in; // Input token for this hop
address token_out; // Output token for this hop
uint32 rate; // Rate percentage (1-1000000, where 1000000 = 100%)
int24 protocol_id; // Protocol identifier (maps to swap handler)
address pool_address; // Pool contract address for this swap
SwapType swap_type; // Swap type for this hop
bytes extra_data; // Protocol-specific extra data
}
```
| Field | Type | Description |
| -------------- | ---------- | ----------------------------------------------------------------------------------------------- |
| `token_in` | `address` | Input token address for this swap hop |
| `token_out` | `address` | Output token address for this swap hop |
| `rate` | `uint32` | Percentage of input amount to use (1-1000000). `amount_in = (previous_amount * rate) / 1000000` |
| `protocol_id` | `int24` | Protocol identifier. Maps to swap handler via `swappers` mapping |
| `pool_address` | `address` | Pool contract address where swap will execute |
| `swap_type` | `SwapType` | Swap type for this hop |
| `extra_data` | `bytes` | Protocol-specific data (e.g., fee tier, tick spacing, hooks config) |
### Returns
* `uint256`: Amount of output tokens received by the destination address
### Behavior
1. **Validation**: Checks that `token_in != token_out`, `amount_in > 0`, `min_received > 0`, and `swap_parameters.length > 0`
2. **Token Transfer**:
* For `tokenToToken` and `tokenToEth`: Transfers `amount_in` from `msg.sender` to contract
* For `ethToToken`: Expects ETH sent with transaction (`msg.value`)
3. **Multi-Hop Execution**:
* For first swap: Uses `route.amount_in` multiplied by first swap's `rate`
* For subsequent swaps: Uses previous swap's output multiplied by current swap's `rate`
* Handles native token conversion (MONAD ↔ WMONAD) if protocol supports it
4. **Surplus Handling**:
* If actual output > `route.amount_out`, caps output at `route.amount_out`
* User receives capped amount, surplus stays in contract
5. **Slippage Protection**:
* Verifies `actual_output >= route.min_received`
* Reverts with `MinReceivedAmountNotReached` if check fails
6. **Token Transfer**: Sends output tokens to `destination` (or `msg.sender` if `destination == address(0)`)
### Example
```solidity theme={null}
// Swap 1 MONAD for USDC via two hops: MONAD -> WMONAD -> USDC
RouteParam memory route = RouteParam({
token_in: address(0x0000000000000000000000000000000000000000), // Native MONAD
token_out: USDC_ADDRESS,
amount_in: 1e18, // 1 MONAD
amount_out: 3000e6, // Expected ~3000 USDC
min_received: 2950e6, // Minimum 2950 USDC (1.67% slippage)
destination: address(0), // Use msg.sender
swap_type: SwapType.ethToToken
});
SwapParams[] memory swaps = new SwapParams[](2);
// First hop: MONAD -> WMONAD
swaps[0] = SwapParams({
token_in: address(0x0000000000000000000000000000000000000000),
token_out: WMONAD_ADDRESS,
rate: 1000000, // 100% of input
protocol_id: UNISWAP_V4_PROTOCOL_ID,
pool_address: MONAD_WMONAD_POOL,
swap_type: SwapType.ethToToken,
extra_data: abi.encode(...) // Pool-specific data
});
// Second hop: WMONAD -> USDC
swaps[1] = SwapParams({
token_in: WMONAD_ADDRESS,
token_out: USDC_ADDRESS,
rate: 1000000, // 100% of previous output
protocol_id: UNISWAP_V3_PROTOCOL_ID,
pool_address: WMONAD_USDC_POOL,
swap_type: SwapType.tokenToToken,
extra_data: abi.encode(...)
});
// Execute swap
uint256 amountOut = router.swap{value: 1e18}(route, swaps);
```
See [EVM Router Events](/integrate-best-trading/fibrous-smart-contracts/evm-router-events) for complete event documentation.
### Errors
| Error | Condition |
| ------------------------------- | ------------------------------------------------- |
| `TokenAddressesAreSame()` | `token_in == token_out` |
| `NoSwapsProvided()` | `swap_parameters.length == 0` |
| `AmountInZero()` | `amount_in == 0` |
| `MinReceivedZero()` | `min_received == 0` |
| `MinReceivedAmountNotReached()` | Actual output \< `min_received` |
| `SwapHandlerNotSet()` | No handler set for `protocol_id` |
| `SwapFailed()` | Delegatecall to swap handler failed |
| `RateZero()` | `rate == 0` in any swap parameter |
| `RateExceedsMaximum()` | `rate > 1000000` in any swap parameter |
| `AmountTooSmallForRate()` | `(amount * rate) / 1000000 == 0` but `amount > 0` |
***
## Function: `swapIntegrator`
Performs a swap with integrator fee or surplus sharing. Integrators can monetize by taking a percentage fee from output or sharing in surplus profits.
### Signature
```solidity theme={null}
function swapIntegrator(
RouteParam calldata route,
SwapParams[] calldata swap_parameters,
bytes memory integrator_data
) external payable nonReentrant whenNotPaused returns (uint256)
```
### Parameters
#### `route` (RouteParam)
Same as `swap` function. See [swap route parameters](#route-routeparam).
#### `swap_parameters` (SwapParams\[])
Same as `swap` function. See [swap parameters](#swap_parameters-swapparams).
#### `integrator_data` (bytes)
Encoded `IntegratorParams` struct:
```solidity theme={null}
struct IntegratorParams {
address integrator_address; // Address to receive integrator fee/surplus
uint16 surplus_percentage; // Surplus share in bips (max 5000 = 50%)
uint16 fee_percentage; // Fee percentage in bips (max 500 = 5%)
}
```
| Field | Type | Description |
| -------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `integrator_address` | `address` | Address to receive integrator fee or surplus share. Must not be `address(0)` |
| `surplus_percentage` | `uint16` | Percentage of surplus to share with integrator (in basis points). Max 5000 (50%). Cannot be used with `fee_percentage` |
| `fee_percentage` | `uint16` | Percentage of output to take as fee (in basis points). Max 500 (5%). Cannot be used with `surplus_percentage` |
**Important**: You cannot use both `fee_percentage` and `surplus_percentage` simultaneously. Choose one monetization model.
### Returns
* `uint256`: Amount of output tokens received by the user (after integrator fee/surplus)
### Behavior
#### Fee-Based Model (`fee_percentage > 0`)
1. Executes swaps normally
2. Calculates total amount received
3. Calculates integrator fee: `fee_amount = (total_received * fee_percentage) / 10000`
4. User receives: `total_received - fee_amount`
5. Integrator receives: `fee_amount`
**Example**:
* Total received: 1000 tokens
* Fee percentage: 100 bips (1%)
* Integrator fee: 10 tokens
* User receives: 990 tokens
#### Surplus-Based Model (`surplus_percentage > 0`)
1. Executes swaps normally
2. Calculates total amount received
3. Calculates surplus: `surplus = max(0, total_received - route.amount_out)`
4. If surplus > 0:
* Integrator share: `(surplus * surplus_percentage) / 10000`
* User receives: `route.amount_out` (capped at expected)
* Integrator receives: integrator share of surplus
5. If surplus == 0:
* User receives: `total_received`
* Integrator receives: 0
**Example**:
* Expected output: 1000 tokens
* Actual received: 1050 tokens
* Surplus: 50 tokens
* Surplus percentage: 2000 bips (20%)
* Integrator share: 10 tokens
* User receives: 1000 tokens (capped)
* Integrator receives: 10 tokens
### min\_received Calculation
**Critical**: When using integrator fees, `min_received` is checked AFTER deducting the fee. This ensures users receive at least `min_received` after all fees.
**Formula**:
```
For fee-based:
user_amount = total_received - fee_amount
Check: user_amount >= min_received
For surplus-based:
user_amount = min(total_received, route.amount_out)
Check: user_amount >= min_received
```
### Example
```solidity theme={null}
// Swap with 1% integrator fee
RouteParam memory route = RouteParam({
token_in: TOKEN_A,
token_out: TOKEN_B,
amount_in: 1000e18,
amount_out: 2000e18,
min_received: 1980e18, // After 1% fee, user gets at least 1980
destination: msg.sender,
swap_type: SwapType.tokenToToken
});
SwapParams[] memory swaps = new SwapParams[](1);
swaps[0] = SwapParams({
token_in: TOKEN_A,
token_out: TOKEN_B,
rate: 1000000,
protocol_id: PROTOCOL_ID,
pool_address: POOL_ADDRESS,
swap_type: SwapType.tokenToToken,
extra_data: abi.encode(...)
});
// Encode integrator parameters
IntegratorParams memory integratorParams = IntegratorParams({
integrator_address: INTEGRATOR_ADDRESS,
surplus_percentage: 0, // Not using surplus
fee_percentage: 100 // 1% fee (100 bips)
});
bytes memory integratorData = abi.encode(integratorParams);
// Execute swap
uint256 userAmount = router.swapIntegrator(route, swaps, integratorData);
```
See [EVM Router Events](/integrate-best-trading/fibrous-smart-contracts/evm-router-events) for complete event documentation, including `IntegratorFeeDistribution` event details.
### Errors
All errors from `swap` function, plus:
| Error | Condition |
| ----------------------------------- | ------------------------------------------------------ |
| `InvalidAddress()` | `integrator_address == address(0)` |
| `CannotTakeBothFeeAndSurplus()` | Both `fee_percentage > 0` and `surplus_percentage > 0` |
| `SurplusPercentageExceedsMaximum()` | `surplus_percentage > 5000` |
| `FeePercentageExceedsMaximum()` | `fee_percentage > 500` |
***
## Function: `swapWithPermit`
Performs a swap using ERC-20 permit signature for gasless token approval. This allows users to approve tokens without a separate transaction.
### Signature
```solidity theme={null}
function swapWithPermit(
RouteParam calldata route,
SwapParams[] calldata swap_parameters,
uint256 deadline,
uint8 v,
bytes32 r,
bytes32 s
) external payable nonReentrant whenNotPaused returns (uint256)
```
### Parameters
#### `route` (RouteParam)
Same as `swap` function. See [swap route parameters](#route-routeparam).
**Note**: `route.token_in` must be an ERC-20 token that supports `permit` (ERC-2612).
#### `swap_parameters` (SwapParams\[])
Same as `swap` function. See [swap parameters](#swap_parameters-swapparams).
#### `deadline` (uint256)
Unix timestamp after which the permit signature expires. Must be `>= block.timestamp`.
#### `v`, `r`, `s` (uint8, bytes32, bytes32)
ECDSA signature components for the permit. Generated by signing:
```solidity theme={null}
keccak256(abi.encodePacked(
"\x19\x01",
DOMAIN_SEPARATOR,
keccak256(abi.encode(
keccak256("Permit(address owner,address spender,uint256 value,uint256 nonce,uint256 deadline)"),
owner,
spender, // EVM Router contract address
value, // route.amount_in
nonce, // Current nonce from token contract
deadline
))
))
```
### Returns
* `uint256`: Amount of output tokens received by the destination address
### Behavior
1. **Permit Validation**: Checks `deadline >= block.timestamp`
2. **Permit Execution**: Calls `IERC20Permit(route.token_in).permit(...)` with signature
3. **Swap Execution**: Executes swap using same logic as `swap` function
### Example
```javascript theme={null}
// Frontend: Generate permit signature
const domain = {
name: 'Token Name',
version: '1',
chainId: CHAIN_ID,
verifyingContract: TOKEN_ADDRESS
};
const types = {
Permit: [
{ name: 'owner', type: 'address' },
{ name: 'spender', type: 'address' },
{ name: 'value', type: 'uint256' },
{ name: 'nonce', type: 'uint256' },
{ name: 'deadline', type: 'uint256' }
]
};
const value = {
owner: userAddress,
spender: EVM_ROUTER_ADDRESS,
value: amountIn,
nonce: await tokenContract.nonces(userAddress),
deadline: Math.floor(Date.now() / 1000) + 3600 // 1 hour
};
const signature = await signer._signTypedData(domain, types, value);
const { r, s, v } = ethers.utils.splitSignature(signature);
// Execute swap with permit
const tx = await router.swapWithPermit(
route,
swapParameters,
value.deadline,
v,
r,
s
);
```
### Errors
All errors from `swap` function, plus:
| Error | Condition |
| ------------------- | ---------------------------- |
| `DeadlineExpired()` | `deadline < block.timestamp` |
***
## Advanced Features
### Native Token Support
EVM Router supports native token swaps through automatic wrapped token conversion.
**How it works**:
* Protocols can support native token pairs (e.g., ETH/TOKEN) or wrapped pairs (e.g., WETH/TOKEN)
* EVM Router automatically converts native ↔ wrapped tokens when needed
* Conversion is controlled by `shouldConvertInput` flag in `extra_data`
**Example Scenarios**:
1. **MONAD → USDC** (using WMONAD/USDC pool):
* User sends MONAD
* Router wraps to WMONAD
* Swaps WMONAD → USDC
2. **WMONAD → USDC** (using MONAD/USDC pool):
* User sends WMONAD
* Router unwraps to MONAD
* Swaps MONAD → USDC
**extra\_data Format** (for protocols with native support):
```solidity theme={null}
(address token0, address token1, uint24 fee, int24 tickSpacing, address hook, bool shouldConvertInput) = abi.decode(extra_data, ...);
```
### Rate-Based Amount Distribution
Each swap in `swap_parameters` has a `rate` field that determines what percentage of input to use.
**Rate Calculation**:
```solidity theme={null}
amount_in_for_swap = (previous_amount * rate) / 1000000
```
**Example**:
* First swap: `rate = 1000000` (100%) → Uses all input
* Second swap: `rate = 500000` (50%) → Uses 50% of first swap's output
* Third swap: `rate = 1000000` (100%) → Uses all of second swap's output
**Use Cases**:
* Splitting input across multiple pools for better execution
* Partial swaps with different protocols
* Complex routing strategies
### Surplus Handling
EVM Router caps output at `route.amount_out` to prevent users from receiving unexpected excess.
**Surplus Calculation**:
```solidity theme={null}
actual_output = balance_after - balance_before
surplus = max(0, actual_output - route.amount_out)
user_receives = min(actual_output, route.amount_out)
```
**Why it matters**:
* Protects against unexpected price improvements
* Ensures predictable output amounts
* Enables integrator surplus sharing
***
## Common Patterns
### Simple Token-to-Token Swap
```solidity theme={null}
RouteParam memory route = RouteParam({
token_in: TOKEN_A,
token_out: TOKEN_B,
amount_in: amount,
amount_out: expectedOut,
min_received: minOut,
destination: address(0),
swap_type: SwapType.tokenToToken
});
SwapParams[] memory swaps = new SwapParams[](1);
swaps[0] = SwapParams({
token_in: TOKEN_A,
token_out: TOKEN_B,
rate: 1000000,
protocol_id: PROTOCOL_ID,
pool_address: POOL,
swap_type: SwapType.tokenToToken,
extra_data: abi.encode(...)
});
router.swap(route, swaps);
```
### Multi-Hop Swap
```solidity theme={null}
// TOKEN_A -> TOKEN_B -> TOKEN_C
SwapParams[] memory swaps = new SwapParams[](2);
// First hop: 100% of input
swaps[0] = SwapParams({
token_in: TOKEN_A,
token_out: TOKEN_B,
rate: 1000000, // 100%
...
});
// Second hop: 100% of first hop output
swaps[1] = SwapParams({
token_in: TOKEN_B,
token_out: TOKEN_C,
rate: 1000000, // 100%
...
});
```
### Integrator Fee Swap
```solidity theme={null}
IntegratorParams memory params = IntegratorParams({
integrator_address: INTEGRATOR,
surplus_percentage: 0,
fee_percentage: 100 // 1%
});
router.swapIntegrator(route, swaps, abi.encode(params));
```
***
## Error Reference
| Error | Description |
| ----------------------------------- | ------------------------------------------------------ |
| `TokenAddressesAreSame()` | Input and output tokens are the same |
| `NoSwapsProvided()` | Empty swap parameters array |
| `AmountInZero()` | Input amount is zero |
| `MinReceivedZero()` | Minimum received is zero |
| `MinReceivedAmountNotReached()` | Actual output less than minimum required |
| `SwapHandlerNotSet()` | No handler configured for protocol ID |
| `SwapFailed()` | Swap execution failed |
| `RateZero()` | Rate is zero |
| `RateExceedsMaximum()` | Rate exceeds 1000000 (100%) |
| `AmountTooSmallForRate()` | Amount too small for rate calculation (precision loss) |
| `InvalidAddress()` | Invalid address (zero address) |
| `CannotTakeBothFeeAndSurplus()` | Both fee and surplus percentages provided |
| `SurplusPercentageExceedsMaximum()` | Surplus percentage > 5000 bips (50%) |
| `FeePercentageExceedsMaximum()` | Fee percentage > 500 bips (5%) |
| `DeadlineExpired()` | Permit deadline has passed |
| `CallFailed()` | External call failed |
***
## Contract Address
EVM Router is deployed on multiple EVM-compatible networks. Check [Contract Addresses](/api-reference/chains-tokens-contracts/contract-addresses) for the latest deployment addresses.
**Contract ABI**: [View on GitHub](https://github.com/Fibrous-Finance/router-contract-abi/blob/main/routerAbi.json)
***
## Related Documentation
* [EVM Router Events](/integrate-best-trading/fibrous-smart-contracts/evm-router-events) - Complete event reference and monitoring guide
* [Integration Guide](/api-reference/integration-guide) - Best practices for integrating with Fibrous API
* [V2 Migration Guide](/api-reference/v2-migration) - Migrating from V1 to V2 API
* [Error Codes](/api-reference/errors) - Complete error reference
# EVM Router - Events
Source: https://docs.fibrous.finance/integrate-best-trading/fibrous-smart-contracts/evm-router-events
Complete reference for all EVM Router contract events
# EVM Router Events
EVM Router emits events for all important contract operations, including swaps, integrator fee distributions, and handler management. These events are essential for tracking contract activity, monitoring integrations, and building analytics.
***
## Event: `Swap`
Emitted whenever a swap is executed successfully, regardless of whether it uses `swap`, `swapIntegrator`, or `swapWithPermit`.
### Signature
```solidity theme={null}
event Swap(
address sender,
uint256 amount_in,
uint256 amount_out,
address token_in,
address token_out,
address destination
);
```
### Parameters
| Parameter | Type | Description |
| ------------- | --------- | --------------------------------------------------------------------------------------------------- |
| `sender` | `address` | Address that executed the swap transaction (`msg.sender`) |
| `amount_in` | `uint256` | Amount of input tokens swapped (in token's smallest unit) |
| `amount_out` | `uint256` | Amount of output tokens received by the destination (after surplus capping, before integrator fees) |
| `token_in` | `address` | Contract address of the input token |
| `token_out` | `address` | Contract address of the output token |
| `destination` | `address` | Address that received the output tokens (or `msg.sender` if `route.destination == address(0)`) |
### When Emitted
* After successful execution of `swap()`
* After successful execution of `swapIntegrator()` (amount\_out is user amount after integrator fee)
* After successful execution of `swapWithPermit()`
### Usage Example
```javascript theme={null}
// Listen for Swap events
router.on("Swap", (sender, amountIn, amountOut, tokenIn, tokenOut, destination, event) => {
console.log(`Swap executed:`);
console.log(` From: ${sender}`);
console.log(` Input: ${amountIn} of ${tokenIn}`);
console.log(` Output: ${amountOut} of ${tokenOut}`);
console.log(` Recipient: ${destination}`);
console.log(` Transaction: ${event.transactionHash}`);
});
// Query past events
const filter = router.filters.Swap(null, null, null, TOKEN_A, TOKEN_B, null);
const events = await router.queryFilter(filter, fromBlock, toBlock);
```
### Important Notes
* **Surplus Handling**: `amount_out` reflects the actual amount sent to destination, which may be capped at `route.amount_out` if surplus exists
* **Integrator Fees**: When using `swapIntegrator` with fee-based model, `amount_out` is the user amount AFTER integrator fee deduction
* **Indexed Fields**: None of the fields are indexed, so filtering requires querying all Swap events and filtering in application code
***
## Event: `IntegratorFeeDistribution`
Emitted when integrator fees or surplus are distributed during a `swapIntegrator` call.
### Signature
```solidity theme={null}
event IntegratorFeeDistribution(
address indexed integrator,
uint256 integrator_amount,
uint256 user_amount
);
```
### Parameters
| Parameter | Type | Description |
| ------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
| `integrator` | `address indexed` | Address of the integrator receiving the fee/surplus share |
| `integrator_amount` | `uint256` | Amount of tokens sent to the integrator |
| `user_amount` | `uint256` | Amount of tokens sent to the user (matches `amount_out` in the corresponding `Swap` event) |
### When Emitted
* Only emitted when `swapIntegrator()` is called
* Emitted when `integrator_amount > 0` (either fee or surplus share)
* Not emitted if integrator parameters are provided but no fee/surplus is distributed
### Usage Example
```javascript theme={null}
// Listen for integrator fee distributions
router.on("IntegratorFeeDistribution", (integrator, integratorAmount, userAmount, event) => {
console.log(`Integrator fee distributed:`);
console.log(` Integrator: ${integrator}`);
console.log(` Integrator received: ${integratorAmount}`);
console.log(` User received: ${userAmount}`);
console.log(` Total: ${integratorAmount + userAmount}`);
});
// Query events for specific integrator
const filter = router.filters.IntegratorFeeDistribution(INTEGRATOR_ADDRESS);
const events = await router.queryFilter(filter, fromBlock, toBlock);
```
### Important Notes
* **Indexed Field**: `integrator` is indexed, allowing efficient filtering by integrator address
* **Fee vs Surplus**: The event doesn't distinguish between fee-based and surplus-based distributions
* **Zero Amounts**: Event is not emitted if `integrator_amount == 0`
* **Correlation**: Always check for a corresponding `Swap` event in the same transaction
***
## Event: `AddHandler`
Emitted when a new swap handler is set for a protocol ID.
### Signature
```solidity theme={null}
event AddHandler(int24 protocol_id, address handler);
```
### Parameters
| Parameter | Type | Description |
| ------------- | --------- | ------------------------------------------------ |
| `protocol_id` | `int24` | Protocol identifier for which the handler is set |
| `handler` | `address` | Address of the swap handler contract |
### When Emitted
* When `setSwapHandler()` is called successfully
* Only emitted by the contract owner
* Emitted once per protocol ID (handler can only be set once)
### Usage Example
```javascript theme={null}
// Listen for handler additions
router.on("AddHandler", (protocolId, handler, event) => {
console.log(`New handler added:`);
console.log(` Protocol ID: ${protocolId}`);
console.log(` Handler address: ${handler}`);
console.log(` Set by: ${event.args[0]}`);
});
// Query all handler additions
const filter = router.filters.AddHandler();
const events = await router.queryFilter(filter, fromBlock, toBlock);
```
### Important Notes
* **One-Time Event**: Handler can only be set once per protocol ID
* **Owner Only**: Only contract owner can trigger this event
* **Handler Removal**: Use `SwapHandlerRemoved` event to track handler removals
***
## Event: `SwapHandlerRemoved`
Emitted when a swap handler is removed for a protocol ID.
### Signature
```solidity theme={null}
event SwapHandlerRemoved(int24 protocol_id);
```
### Parameters
| Parameter | Type | Description |
| ------------- | ------- | ----------------------------------------------------- |
| `protocol_id` | `int24` | Protocol identifier for which the handler was removed |
### When Emitted
* When `removeSwapHandler()` is called successfully
* Only emitted by the contract owner
* Handler address is set to `address(0)` after removal
### Usage Example
```javascript theme={null}
// Listen for handler removals
router.on("SwapHandlerRemoved", (protocolId, event) => {
console.log(`Handler removed:`);
console.log(` Protocol ID: ${protocolId}`);
console.log(` Removed by: ${event.args[0]}`);
});
// Query handler removals
const filter = router.filters.SwapHandlerRemoved();
const events = await router.queryFilter(filter, fromBlock, toBlock);
```
### Important Notes
* **Owner Only**: Only contract owner can trigger this event
* **Handler State**: After removal, `getSwapHandler(protocol_id)` returns `address(0)`
* **Swap Failures**: Swaps using removed handlers will revert with `SwapHandlerNotSet()`
***
## Event: `SetNativeTokenSupport`
Emitted when native token support is enabled or disabled for a protocol.
### Signature
```solidity theme={null}
event SetNativeTokenSupport(int24 protocol_id, bool support);
```
### Parameters
| Parameter | Type | Description |
| ------------- | ------- | ---------------------------------------------------------------- |
| `protocol_id` | `int24` | Protocol identifier for which native token support is configured |
| `support` | `bool` | `true` if native token support is enabled, `false` if disabled |
### When Emitted
* When `setNativeTokenSupport()` is called successfully
* Only emitted by the contract owner
* Controls whether the protocol can handle native token swaps (e.g., MONAD ↔ WMONAD conversion)
### Usage Example
```javascript theme={null}
// Listen for native token support changes
router.on("SetNativeTokenSupport", (protocolId, support, event) => {
console.log(`Native token support updated:`);
console.log(` Protocol ID: ${protocolId}`);
console.log(` Support enabled: ${support}`);
});
// Query native token support changes
const filter = router.filters.SetNativeTokenSupport();
const events = await router.queryFilter(filter, fromBlock, toBlock);
```
### Important Notes
* **Owner Only**: Only contract owner can trigger this event
* **Protocol-Specific**: Each protocol can have independent native token support settings
* **Conversion Logic**: When enabled, router automatically converts native ↔ wrapped tokens as needed
***
## Event Monitoring Best Practices
### 1. Indexed Fields
Only `IntegratorFeeDistribution.integrator` is indexed. For efficient filtering:
```javascript theme={null}
// ✅ Efficient - uses indexed field
const filter = router.filters.IntegratorFeeDistribution(INTEGRATOR_ADDRESS);
// ❌ Inefficient - requires filtering all events
const filter = router.filters.Swap();
const events = await router.queryFilter(filter);
const filtered = events.filter(e => e.args.token_in === TOKEN_A);
```
### 2. Event Correlation
Correlate related events in the same transaction:
```javascript theme={null}
// Get all events from a transaction
const receipt = await provider.getTransactionReceipt(txHash);
const swapEvents = receipt.logs.filter(log => {
try {
return router.interface.parseLog(log).name === 'Swap';
} catch {
return false;
}
});
const integratorEvents = receipt.logs.filter(log => {
try {
return router.interface.parseLog(log).name === 'IntegratorFeeDistribution';
} catch {
return false;
}
});
```
### 3. Error Handling
Always handle event parsing errors:
```javascript theme={null}
try {
const parsed = router.interface.parseLog(log);
// Process event
} catch (error) {
// Not a Router event or invalid log
console.error('Failed to parse log:', error);
}
```
### 4. Block Range Queries
Use appropriate block ranges for event queries:
```javascript theme={null}
// Query recent events (last 1000 blocks)
const latestBlock = await provider.getBlockNumber();
const events = await router.queryFilter(filter, latestBlock - 1000, latestBlock);
// Query specific time range
const fromBlock = await getBlockNumberForTimestamp(startTimestamp);
const toBlock = await getBlockNumberForTimestamp(endTimestamp);
const events = await router.queryFilter(filter, fromBlock, toBlock);
```
### 5. Event Storage
Store event data efficiently:
```javascript theme={null}
// Store minimal event data
const swapData = {
txHash: event.transactionHash,
blockNumber: event.blockNumber,
sender: event.args.sender,
amountIn: event.args.amount_in.toString(),
amountOut: event.args.amount_out.toString(),
tokenIn: event.args.token_in,
tokenOut: event.args.token_out,
timestamp: (await provider.getBlock(event.blockNumber)).timestamp
};
```
***
## Event Indexing and Filtering
### Efficient Filtering Strategies
#### Filter by Token Pair
```javascript theme={null}
// Get all swaps for a specific token pair
const filter = router.filters.Swap();
const events = await router.queryFilter(filter, fromBlock, toBlock);
const tokenPairSwaps = events.filter(event => {
const { token_in, token_out } = event.args;
return (token_in.toLowerCase() === TOKEN_A.toLowerCase() &&
token_out.toLowerCase() === TOKEN_B.toLowerCase()) ||
(token_in.toLowerCase() === TOKEN_B.toLowerCase() &&
token_out.toLowerCase() === TOKEN_A.toLowerCase());
});
```
#### Filter by Integrator
```javascript theme={null}
// Get all integrator distributions for a specific integrator
const filter = router.filters.IntegratorFeeDistribution(INTEGRATOR_ADDRESS);
const events = await router.queryFilter(filter, fromBlock, toBlock);
```
#### Filter by Sender
```javascript theme={null}
// Get all swaps from a specific address
const filter = router.filters.Swap();
const events = await router.queryFilter(filter, fromBlock, toBlock);
const userSwaps = events.filter(event =>
event.args.sender.toLowerCase() === USER_ADDRESS.toLowerCase()
);
```
***
## Event Analytics Examples
### Calculate Total Volume
```javascript theme={null}
async function getTotalVolume(tokenAddress, fromBlock, toBlock) {
const filter = router.filters.Swap();
const events = await router.queryFilter(filter, fromBlock, toBlock);
let totalVolume = BigInt(0);
events.forEach(event => {
const { token_in, token_out, amount_in, amount_out } = event.args;
if (token_in.toLowerCase() === tokenAddress.toLowerCase()) {
totalVolume += BigInt(amount_in);
} else if (token_out.toLowerCase() === tokenAddress.toLowerCase()) {
totalVolume += BigInt(amount_out);
}
});
return totalVolume;
}
```
### Track Integrator Earnings
```javascript theme={null}
async function getIntegratorEarnings(integratorAddress, fromBlock, toBlock) {
const filter = router.filters.IntegratorFeeDistribution(integratorAddress);
const events = await router.queryFilter(filter, fromBlock, toBlock);
let totalEarnings = BigInt(0);
events.forEach(event => {
totalEarnings += BigInt(event.args.integrator_amount);
});
return totalEarnings;
}
```
### Monitor Handler Changes
```javascript theme={null}
async function getHandlerHistory(protocolId, fromBlock, toBlock) {
const addFilter = router.filters.AddHandler(protocolId);
const removeFilter = router.filters.SwapHandlerRemoved(protocolId);
const additions = await router.queryFilter(addFilter, fromBlock, toBlock);
const removals = await router.queryFilter(removeFilter, fromBlock, toBlock);
return {
additions: additions.map(e => ({
handler: e.args.handler,
blockNumber: e.blockNumber,
txHash: e.transactionHash
})),
removals: removals.map(e => ({
blockNumber: e.blockNumber,
txHash: e.transactionHash
}))
};
}
```
***
## Related Documentation
* [EVM Router Swap Functions](/integrate-best-trading/fibrous-smart-contracts/evm-router) - Complete guide to swap functions
* [Integration Guide](/api-reference/integration-guide) - Best practices for integrating with Fibrous API
* [Contract Addresses](/api-reference/chains-tokens-contracts/contract-addresses) - EVM Router deployment addresses
# Starknet
Source: https://docs.fibrous.finance/integrate-best-trading/fibrous-smart-contracts/starknet
Starknet Smart Contracts
### Functions
## constructor
```rust theme={null}
#[constructor]
fn constructor(ref self: ContractState, _owner: ContractAddress)
```
## Paramaters
| name | type | Description |
| ------- | --------------- | -------------------------------- |
| \_owner | ContractAddress | The owner of the router contract |
## swap
```typescript theme={null}
#[external(v0)]
fn swap(ref self: ContractState, route: RouteParam, swap_parameters: Array)
```
## Paramaters
# RouteParam
> @notice RouteParam is a struct that contains the parameters needed to execute a swap
| name | type | description |
| ----------------- | --------------- | ----------------------------------------- |
| **token\_in** | ContractAddress | contract address of token to sell |
| **token\_out** | ContractAddress | contract address of token to buy |
| **amount\_in** | u256 | amount of token to sell |
| **min\_received** | u256 | minimum received amount of user get |
| **destination** | ContractAddress | The receiver address for the output token |
# SwapParams
> @notice SwapParams is a struct that contains the parameters needed to execute a swap
| name | type | description |
| ---------------- | --------------- | ---------------------------------------- |
| **token\_in** | ContractAddress | contract address of token to sell |
| **token\_out** | ContractAddress | contract address of token to buy |
| **rate** | u32 | rate \* 10\*\*4 gives 4 precision points |
| **protocol\_id** | u32 | procotol id |
| **extra\_data** | Array(felt252) | extra data fro route |
## Events
# Swap
```rust theme={null}
#[derive(Drop, starknet::Event)]
struct Swap {
sender: ContractAddress,
token_in: ContractAddress,
token_out: ContractAddress,
amount_in: u256,
amount_out: u256,
to: ContractAddress
}
```
| name | type | description |
| --------------- | --------------- | ----------------------------------------- |
| **sender** | ContractAddress | address that execute the swap |
| **token\_in** | ContractAddress | contract address of token to sold |
| **token\_out** | ContractAddress | contract address of token to bought |
| **amount\_in** | u256 | amount of token to sold |
| **amount\_out** | u256 | amount of token to bought |
| **to** | ContractAddress | The receiver address for the output token |