Documentation

Getting Started

Prerequisites

Finny requires Node.js 18+ installed on your system. Python 3 and yfinance are needed for backtesting with real market data.

Installation

Install Finny globally via npm:

npm i -g finny

First Run

Launch the interactive CLI:

finny

On first run, Finny will guide you through setting up your API key and preferred AI provider. You can also run /init inside the CLI to reinitialize your configuration at any time.

Agent Modes

Finny operates in three distinct modes. Press Tab to cycle between them.

Commands Reference

Type these slash commands directly into the Finny CLI.

Strategy Templates

Start from a proven foundation. Templates provide complete, backtestable strategies you can customize.

For a deeper template reference, see Strategy Templates.

Backtesting

Run /backtest to simulate your strategy against historical market data. Finny uses yfinance to fetch real OHLCV data for any supported ticker.

For the focused backtesting guide, see Backtesting Trading Strategies.

Performance Metrics

Data Source

Historical data is pulled from Yahoo Finance via the yfinance Python library. Ensure Python 3 and yfinance are installed for backtesting to work.

Cloud Storage

Finny integrates with Convex for cloud-based strategy storage. Your algorithms are automatically saved and versioned so you can access them across devices.

Brokerage Connections

Link a brokerage to run your strategies against real (or paper) markets. Credentials stay on your machine — they're written to a local auth file and never leave the CLI.

For the focused broker workflow guide, see Brokerage Workflows.

Supported Brokerages

Connecting a Brokerage

There's no /connect command — accounts are added from the TUI. Open /portfolio and choose Add account, or open /settings → Paper Trading tab. Pick the broker from the segmented control and fill in the dialog.

Alpaca

Fields prompted in the Add Account dialog:

Label       my-alpaca-paper
Key ID      ********************************
Secret      ****************************************
Endpoint    https://paper-api.alpaca.markets   # or live URL

Or set via environment variables (read at runtime if no saved account is selected):

export ALPACA_API_KEY_ID="..."
export ALPACA_API_SECRET_KEY="..."
export ALPACA_ENDPOINT="https://paper-api.alpaca.markets"
export ALPACA_PAPER="true"

Requires alpaca-py>=0.30, which Finny installs into its managed Python venv on first use.

Binance

Fields prompted in the Add Account dialog:

Label        my-binance-testnet
API key      ********************************
API secret   ****************************************

No endpoint field — testnet is hardcoded in the UI today. Environment variable fallback:

export BINANCE_API_KEY="..."
export BINANCE_API_SECRET="..."
export BINANCE_TESTNET="true"

Powered by ccxt>=4 with set_sandbox_mode(True) for testnet routing.

Where Credentials Live

All saved accounts are written to a single XDG auth file:

~/.local/share/finny/auth.json   (mode 0600, plaintext JSON)

Each entry is keyed by provider — e.g. alpaca-paper-…, binance-testnet-… — and stores key, secret, label, and (for Alpaca) endpoint. There is no OS keychain integration today; the file is plaintext with restrictive permissions, so treat your machine as the trust boundary.

How Strategies Use a Connection

Generated strategies are plain Python files that receive a broker instance from Finny — you don't import or instantiate it yourself. The same strategy runs unchanged against Alpaca or Binance.

def run(broker):
    if not broker.market_is_open("BTC/USD"):
        return

    bar = broker.fetch_bar("BTC/USD", interval="1h")
    cash = broker.cash()

    if bar.close > bar.open and broker.position("BTC/USD") == 0:
        broker.buy("BTC/USD", notional=cash * 0.1)

Available methods on the injected broker:

Managing Connections

All management lives in /settings → Paper Trading:

• List every saved account, with its broker and label.
• Remove an account with the per-row Remove button — credentials are wiped from auth.json.
• Reset the managed Python environment if backtest / live runs start failing after a dependency change.

Connections are validated implicitly — the broker SDK is exercised when the account is added, so invalid keys fail fast.

API Keys (BYOK)

Finny supports Bring Your Own Key. Connect your preferred AI provider during setup or via /init.

Supported Providers

Product Positioning

Finny is built for traders and developers searching for AI backtesting, trading strategy generation, and terminal-native market automation. It should not be described as a generic budgeting app, advisor marketplace, or personal finance chatbot.

Relevant search intent

Differentiation

FAQ

Troubleshooting

pip install yfinance

Common Issues