Accounts & Brokers

Every trading account in OpenAlice is a Unified Trading Account (UTA) — a self-contained entity that bundles a broker connection, a git-like operation history, a guard pipeline, and a snapshot scheduler.

AI and the frontend interact with UTAs exclusively. Brokers are internal implementation details.

Configuration

Accounts are defined in data/config/accounts.json:

[
  {
    "id": "alpaca-paper",
    "label": "Alpaca Paper",
    "type": "alpaca",
    "enabled": true,
    "guards": [
      { "type": "max-position-size", "options": { "maxPercentOfEquity": 20 } }
    ],
    "brokerConfig": {
      "apiKey": "your-key",
      "apiSecret": "your-secret",
      "paper": true
    }
  }
]

Field	Description
`id`	Unique identifier, used in `source` parameters and as the `aliceId` prefix
`label`	Display name (optional, defaults to id)
`type`	Broker type: `ccxt`, `alpaca`, or `ibkr`
`enabled`	Set to `false` to skip loading this account
`guards`	Array of guard configs (type + options)
`brokerConfig`	Broker-specific settings (schema varies by type)

Brokers

CCXT (Crypto)

Connects to 100+ crypto exchanges via the CCXT library. Supports Binance, Bybit, OKX, Coinbase, and more.

{
  "type": "ccxt",
  "brokerConfig": {
    "exchange": "bybit",
    "apiKey": "your-key",
    "secret": "your-secret",
    "sandbox": true,
    "demoTrading": false,
    "options": {}
  }
}

Field	Description
`exchange`	CCXT exchange identifier (e.g. `binance`, `bybit`, `okx`, `coinbase`)
`apiKey` / `secret`	Exchange API credentials
`password`	Some exchanges require a passphrase
`sandbox`	Use the exchange's testnet/sandbox environment
`demoTrading`	Enable demo trading mode (exchange-specific)
`options`	Exchange-specific options passed to CCXT constructor

For paper trading, use sandbox: true or demoTrading: true depending on the exchange. Check your exchange's documentation for testnet availability.

Alpaca (US Equities)

Commission-free US equities and ETFs with fractional share support via Alpaca.

{
  "type": "alpaca",
  "brokerConfig": {
    "apiKey": "your-key",
    "apiSecret": "your-secret",
    "paper": true
  }
}

Field	Description
`apiKey` / `apiSecret`	Alpaca API credentials
`paper`	`true` for paper trading, `false` for live

Alpaca paper accounts are free and provide realistic simulation with delayed market data.

IBKR (Interactive Brokers)

Professional-grade trading via TWS (Trader Workstation) or IB Gateway. Supports stocks, options, futures, and bonds.

{
  "type": "ibkr",
  "brokerConfig": {
    "host": "127.0.0.1",
    "port": 7497,
    "clientId": 1
  }
}

Field	Description
`host`	TWS/Gateway host (usually `127.0.0.1`)
`port`	TWS paper: `7497`, TWS live: `7496`, Gateway paper: `4002`, Gateway live: `4001`
`clientId`	Client ID for the API connection (default: `1`)

IBKR requires TWS or IB Gateway running locally. Enable the API in TWS under Configuration > API > Settings.

Contract Identity — aliceId

Every contract in OpenAlice has an aliceId in the format accountId|nativeKey:

alpaca-paper|AAPL          → AAPL on Alpaca paper account
bybit-demo|BTC/USDT:USDT   → BTC perpetual on Bybit demo
ibkr-live|265598            → AAPL by conId on IBKR

The nativeKey part is broker-specific:

Alpaca: ticker symbol (AAPL)
CCXT: unified symbol (BTC/USDT:USDT)
IBKR: conId (numeric contract identifier)

All trading tools accept aliceId to unambiguously identify which contract on which account. Use searchContracts to discover available contracts.

Account Lifecycle

The AccountManager manages UTA lifecycle:

Init — Creates a UTA from config, starts async broker connection
Connect — Broker initializes and verifies credentials
Healthy — Broker responding normally
Degraded — 3+ consecutive failures, still accepting requests
Offline — 6+ failures, auto-recovery starts (exponential backoff)
Disabled — Permanent error (bad credentials), requires manual fix

Health transitions emit events and are visible in the Web UI.

Multiple Accounts

You can run multiple accounts simultaneously — even across different brokers:

[
  { "id": "alpaca-paper", "type": "alpaca", "brokerConfig": { "paper": true, ... } },
  { "id": "bybit-demo", "type": "ccxt", "brokerConfig": { "exchange": "bybit", "sandbox": true, ... } }
]

Each account gets its own UTA with independent git history, guards, and snapshots. Tools that accept a source parameter let you target specific accounts or query all at once.

Runtime Management

Accounts can be added, enabled, or disabled at runtime:

Edit accounts.json and restart, or
Use the Web UI's account management panel (add/remove/enable/disable without restart)

Search Documentation