# Brokerages

Source: https://finnyai.tech/docs/brokerages

Link a brokerage to run your strategies against real (or paper) markets. Credentials stay on your machine — written to a local auth file, never leaving the CLI.

## Supported brokerages

- **Alpaca** (active) — US equities and USD-quoted crypto. Paper and live endpoints supported. Crypto symbols like `BTC-USDT` are auto-normalized to `BTC/USD`. Taker fee modeled at 0.25%.
- **Binance** (active) — Crypto spot via testnet (mainnet not yet exposed). Quotes default to USDT. Taker fee modeled at 0.1%. No futures.
- **Polymarket** (coming soon).
- **Questrade / Interactive Brokers** (coming soon).

## Connecting a brokerage

There is no `/connect` command — accounts are added from the TUI. Open `/portfolio` and choose **Add account**, or `/settings` → **Paper Trading**.

### Alpaca

Fields prompted in the Add Account dialog:

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

Env-var fallback:

```bash
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`, installed into Finny's managed Python venv on first use.

### Binance

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

Env-var fallback:

```bash
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

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

No OS keychain integration today. The file is plaintext with restrictive permissions — treat your machine as the trust boundary.

## How strategies use a connection

Generated strategies receive a `broker` instance from Finny — you don't import or instantiate it yourself.

```python
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:

- `buy(symbol, qty=None, notional=None)`
- `sell(symbol, qty=None, notional=None)`
- `position(symbol)`
- `cash()`
- `equity()`
- `price(symbol)`
- `fetch_bar(symbol, interval)`
- `market_is_open(symbol)`

## Things worth knowing

- First run installs `alpaca-py` / `ccxt` into `~/.local/share/finny/python-env/` — expect a 30–60s cold start. Resettable from Settings.
- `auth.json` is plaintext (0600, no keychain). Don't sync it. When generating API keys, disable withdrawals and IP-restrict where supported.
- Binance is testnet-only and spot-only in the current UI.
- Alpaca crypto is USD-quoted only; `BTC-USDT` auto-rewrites to `BTC/USD`.