Brokerages

Supported brokerages

The brokerage picker

finny_brokerage_switch selects the active broker and persists it to brokerage.json. It also auto-switches on asset-class mismatch — ask for an equity strategy while Binance is active and Finny moves the active broker to Alpaca or IBKR, whichever is connected. The TUI brokerage capsule reflects the change within ~1s.

For any canonical symbol, BrokerRegistry.compareForSymbol(symbol) returns every broker's support status, native symbol format, taker fee, and connected accounts — used by the picker to route intelligently.

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. 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. Env-var 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.

Interactive Brokers

Native IBKR support connects to TWS or IB Gateway over a local socket via ib_insync. Paper port 7497, live port 7496 — auto-detected from the mode you pick. Choose a portfolio from the live/paper picker after the connection is established.

Symbol formats:

• Equity — AAPL, SPY
• Crypto — BTC.USD, ETH.USD (PAXOS venue)
• Options — SPY/20260619/500C (underlying/expiry/strike+side)
• Futures (specific) — ES/202612
• Futures (continuous) — ES/CONT (auto-rolls front month)

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.