Quick Start

This guide walks you through your first conversation with Alice, connecting a paper trading account, and placing your first trade. You should have OpenAlice installed and running before continuing.

Your First Conversation

Open localhost:3002. You'll see Alice's chat interface. Try asking something:

What can you tell me about AAPL? Give me a quick overview.

Alice will use her market data tools to pull company profile, key metrics, and recent performance. No trading account needed — research tools work out of the box.

Try a few more:

What are the top gainers in the market today?

Calculate the 50-day and 200-day moving averages for NVDA.

Search the news for anything about the Fed in the last 24 hours.

Connect a Paper Trading Account

To trade, you need a broker account. Start with a paper (simulated) account to learn the workflow risk-free.

Option A: Alpaca Paper Account (US Equities)

Create a free account at alpaca.markets
Go to the Paper Trading section and copy your API key and secret
In the Web UI, go to Settings and add a new account, or edit data/config/accounts.json:

[
  {
    "id": "alpaca-paper",
    "type": "alpaca",
    "enabled": true,
    "guards": [],
    "brokerConfig": {
      "apiKey": "your-api-key",
      "apiSecret": "your-api-secret",
      "paper": true
    }
  }
]

Restart OpenAlice (pnpm dev). Alice will connect to Alpaca automatically.

Option B: CCXT Demo (Crypto)

Most crypto exchanges on CCXT support sandbox/testnet mode. For example, with Bybit:

[
  {
    "id": "bybit-demo",
    "type": "ccxt",
    "enabled": true,
    "guards": [],
    "brokerConfig": {
      "exchange": "bybit",
      "apiKey": "your-testnet-key",
      "secret": "your-testnet-secret",
      "sandbox": true
    }
  }
]

Place Your First Trade

With a paper account connected, ask Alice to place a trade:

Buy 1 share of AAPL at market price.

Alice will walk you through the Trading-as-Git workflow:

Stage — Alice stages a placeOrder operation
Commit — The operation is committed with a message and gets an 8-char hash
Push — You approve, and the order is sent to the broker

You'll see the staged operation and be asked to confirm before anything executes. This approval step is always required — Alice never sends orders without your explicit go-ahead.

After the push, Alice takes a snapshot of your account state and records the trade in the commit history.

Check Your Portfolio

Show me my portfolio and open orders.

Alice will call getPortfolio and getOrders to show your current positions, unrealized P&L, and any pending orders.

Set Up the Heartbeat

The heartbeat lets Alice periodically check markets and notify you if something needs attention:

Enable the heartbeat to check every 30 minutes during market hours.

Alice will configure the heartbeat in data/config/heartbeat.json. When triggered, she reviews market conditions and decides whether to message you:

HEARTBEAT_OK — Nothing to report, stays quiet
CHAT_YES — Something worth mentioning, sends you a message
CHAT_NO — Considered saying something but decided against it

Messages are delivered to whichever channel you last used (Web UI or Telegram).

Next Steps

Architecture Overview — Understand how the pieces fit together
Trading as Git — Deep dive into the stage-commit-push workflow
Accounts & Brokers — Detailed broker setup for CCXT, Alpaca, and IBKR
Brain & Persona — Customize Alice's personality and memory

Search Documentation