feat: dynamic CCXT credentials + single-page New Account wizard

Fixes inability to configure wallet-based exchanges like Hyperliquid:
CcxtBroker previously hardcoded apiKey + secret + password fields, but
each CCXT exchange declares its own requiredCredentials map (10 standard
fields including walletAddress, privateKey, uid, twofa, etc.).

Backend
- CcxtBroker.configSchema accepts all 10 CCXT credential fields, with
  legacy `apiSecret` aliased to `secret` for back-compat
- Constructor passes all set fields through to ccxt[exchange]() generically
- init() validates via the exchange's own checkRequiredCredentials() and
  reports which fields are missing
- New endpoints: GET /ccxt/exchanges (list all CCXT-supported exchanges)
  and GET /ccxt/exchanges/:name/credentials (read requiredCredentials)
- BrokerRegistryEntry gets a setupGuide field; ccxt/alpaca/ibkr each
  have a multi-paragraph guide explaining what they are, how to get
  credentials, and prerequisites

Frontend
- TradingPage CreateWizard refactored from two-step to single-page form
  (consistent with EditDialog and other config dialogs); deleted
  StepIndicator and the sensitive/non-sensitive field split that put
  Hyperliquid's walletAddress and privateKey on different pages
- Selecting a platform shows the broker's setupGuide as a description
  block before the configuration fields
- For CCXT: exchange dropdown is populated dynamically from
  /ccxt/exchanges, and credential fields are loaded based on the
  selected exchange via /ccxt/exchanges/:name/credentials
- EditDialog also wired with dynamic CCXT credential fetching
- Bump version to 0.9.0-beta.11

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-alice",
-  "version": "0.9.0-beta.10",
+  "version": "0.9.0-beta.11",
   "description": "File-based trading agent engine",
   "type": "module",
   "scripts": {

src/connectors/web/routes/trading-config.ts

@@ -1,11 +1,29 @@
 import { Hono } from 'hono'
+import ccxt from 'ccxt'
 import type { EngineContext } from '../../../core/types.js'
 import {
   readAccountsConfig, writeAccountsConfig,
   accountConfigSchema,
 } from '../../../core/config.js'
 import { createBroker } from '../../../domain/trading/brokers/factory.js'
 import { BROKER_REGISTRY } from '../../../domain/trading/brokers/registry.js'
+import type { BrokerConfigField } from '../../../domain/trading/brokers/types.js'
+
+// ==================== CCXT credential field metadata ====================
+
+/** Map of CCXT standard credential field name → UI display metadata. */
+const CCXT_CREDENTIAL_LABELS: Record<string, { label: string; type: BrokerConfigField['type']; sensitive: boolean; placeholder?: string }> = {
+  apiKey:        { label: 'API Key',        type: 'password', sensitive: true },
+  secret:        { label: 'API Secret',     type: 'password', sensitive: true },
+  uid:           { label: 'User ID',        type: 'text',     sensitive: false },
+  accountId:     { label: 'Account ID',     type: 'text',     sensitive: false },
+  login:         { label: 'Login',          type: 'text',     sensitive: false },
+  password:      { label: 'Passphrase',     type: 'password', sensitive: true, placeholder: 'Required by some exchanges (e.g. OKX)' },
+  twofa:         { label: '2FA Secret',     type: 'password', sensitive: true },
+  privateKey:    { label: 'Private Key',    type: 'password', sensitive: true, placeholder: 'Wallet private key (for Hyperliquid, dYdX, etc.)' },
+  walletAddress: { label: 'Wallet Address', type: 'text',     sensitive: false, placeholder: '0x...' },
+  token:         { label: 'Token',          type: 'password', sensitive: true },
+}
 
 // ==================== Credential helpers ====================
 
@@ -58,6 +76,7 @@ export function createTradingConfigRoutes(ctx: EngineContext) {
       type,
       name: entry.name,
       description: entry.description,
+      setupGuide: entry.setupGuide,
       badge: entry.badge,
       badgeColor: entry.badgeColor,
       fields: entry.configFields,
@@ -67,6 +86,44 @@ export function createTradingConfigRoutes(ctx: EngineContext) {
     return c.json({ brokerTypes })
   })
 
+  // ==================== CCXT dynamic exchange + credential metadata ====================
+
+  /** List all CCXT-supported exchanges (dynamically from the ccxt package). */
+  app.get('/ccxt/exchanges', (c) => {
+    const exchanges = (ccxt as unknown as { exchanges: string[] }).exchanges ?? []
+    return c.json({ exchanges })
+  })
+
+  /** Return the credential fields a given CCXT exchange requires (read from its requiredCredentials map). */
+  app.get('/ccxt/exchanges/:name/credentials', (c) => {
+    const name = c.req.param('name')
+    const exchanges = ccxt as unknown as Record<string, new (opts?: Record<string, unknown>) => { requiredCredentials?: Record<string, boolean> }>
+    const ExchangeClass = exchanges[name]
+    if (!ExchangeClass) return c.json({ error: `Unknown exchange: ${name}` }, 404)
+
+    try {
+      const inst = new ExchangeClass()
+      const required = inst.requiredCredentials ?? {}
+      const fields: BrokerConfigField[] = []
+      for (const [key, needed] of Object.entries(required)) {
+        if (!needed) continue
+        const meta = CCXT_CREDENTIAL_LABELS[key]
+        if (!meta) continue // skip unknown credential names (CCXT may add new ones)
+        fields.push({
+          name: key,
+          type: meta.type,
+          label: meta.label,
+          required: true,
+          sensitive: meta.sensitive,
+          placeholder: meta.placeholder,
+        })
+      }
+      return c.json({ fields })
+    } catch (err) {
+      return c.json({ error: err instanceof Error ? err.message : String(err) }, 500)
+    }
+  })
+
   // ==================== Read all ====================
 
   app.get('/', async (c) => {

src/domain/trading/brokers/ccxt/CcxtBroker.spec.ts

@@ -74,11 +74,11 @@ function makeSwapMarket(base: string, quote: string, symbol?: string): any {
   }
 }
 
-function makeAccount(overrides?: Partial<{ exchange: string; apiKey: string; apiSecret: string }>) {
+function makeAccount(overrides?: Partial<{ exchange: string; apiKey: string; secret: string }>) {
   return new CcxtBroker({
     exchange: overrides?.exchange ?? 'bybit',
     apiKey: overrides?.apiKey ?? 'k',
-    apiSecret: overrides?.apiSecret ?? 's',
+    secret: overrides?.secret ?? 's',
     sandbox: false,
   })
 }
@@ -92,7 +92,7 @@ function setInitialized(acc: CcxtBroker, markets: Record<string, any>) {
 
 describe('CcxtBroker — constructor', () => {
   it('throws for unknown exchange', () => {
-    expect(() => new CcxtBroker({ exchange: 'unknownxyz', apiKey: 'k', apiSecret: 's', sandbox: false })).toThrow(
+    expect(() => new CcxtBroker({ exchange: 'unknownxyz', apiKey: 'k', secret: 's', sandbox: false })).toThrow(
       'Unknown CCXT exchange',
     )
   })
@@ -853,9 +853,9 @@ describe('CcxtBroker — getAccount', () => {
   })
 
   it('throws BrokerError when no API credentials', async () => {
-    const acc = new CcxtBroker({ exchange: 'bybit', apiKey: '', apiSecret: '', sandbox: false })
+    const acc = new CcxtBroker({ exchange: 'bybit', apiKey: '', secret: '', sandbox: false })
 
-    await expect(acc.init()).rejects.toThrow('No API credentials configured')
+    await expect(acc.init()).rejects.toThrow(/requires credentials/)
   })
 })
 

src/domain/trading/brokers/ccxt/CcxtBroker.ts

@@ -25,7 +25,7 @@ import {
   type TpSlParams,
 } from '../types.js'
 import '../../contract-ext.js'
-import type { CcxtBrokerConfig, CcxtMarket, FundingRate, OrderBook, OrderBookLevel } from './ccxt-types.js'
+import { CCXT_CREDENTIAL_FIELDS, type CcxtBrokerConfig, type CcxtMarket, type FundingRate, type OrderBook, type OrderBookLevel } from './ccxt-types.js'
 import { MAX_INIT_RETRIES, INIT_RETRY_BASE_MS } from './ccxt-types.js'
 import {
   ccxtTypeToSecType,
@@ -69,21 +69,27 @@ export class CcxtBroker implements IBroker<CcxtBrokerMeta> {
     sandbox: z.boolean().default(false),
     demoTrading: z.boolean().default(false),
     options: z.record(z.string(), z.unknown()).optional(),
+    // All 10 CCXT standard credential fields, all optional.
+    // Each exchange requires its own subset (read via Exchange.requiredCredentials).
     apiKey: z.string().optional(),
-    apiSecret: z.string().optional(),
+    secret: z.string().optional(),
+    apiSecret: z.string().optional(), // legacy alias for `secret`
+    uid: z.string().optional(),
+    accountId: z.string().optional(),
+    login: z.string().optional(),
     password: z.string().optional(),
+    twofa: z.string().optional(),
+    privateKey: z.string().optional(),
+    walletAddress: z.string().optional(),
+    token: z.string().optional(),
   })
 
+  // Static base fields. Exchange dropdown options + per-exchange credential fields
+  // are fetched dynamically by the frontend (see /api/trading/config/ccxt/* routes).
   static configFields: BrokerConfigField[] = [
-    { name: 'exchange', type: 'select', label: 'Exchange', required: true, options: [
-      'binance', 'bybit', 'okx', 'bitget', 'gate', 'kucoin', 'coinbase',
-      'kraken', 'htx', 'mexc', 'bingx', 'phemex', 'woo', 'hyperliquid',
-    ].map(e => ({ value: e, label: e.charAt(0).toUpperCase() + e.slice(1) })) },
+    { name: 'exchange', type: 'select', label: 'Exchange', required: true, options: [] },
     { name: 'sandbox', type: 'boolean', label: 'Sandbox Mode', default: false },
     { name: 'demoTrading', type: 'boolean', label: 'Demo Trading', default: false },
-    { name: 'apiKey', type: 'password', label: 'API Key', required: true, sensitive: true },
-    { name: 'apiSecret', type: 'password', label: 'API Secret', required: true, sensitive: true },
-    { name: 'password', type: 'password', label: 'Password', placeholder: 'Required by some exchanges (e.g. OKX)', sensitive: true },
   ]
 
   static fromConfig(config: { id: string; label?: string; brokerConfig: Record<string, unknown> }): CcxtBroker {
@@ -95,9 +101,17 @@ export class CcxtBroker implements IBroker<CcxtBrokerMeta> {
       sandbox: bc.sandbox,
       demoTrading: bc.demoTrading,
       options: bc.options,
-      apiKey: bc.apiKey ?? '',
-      apiSecret: bc.apiSecret ?? '',
+      apiKey: bc.apiKey,
+      // Accept both `secret` (CCXT-native) and legacy `apiSecret`
+      secret: bc.secret ?? bc.apiSecret,
+      uid: bc.uid,
+      accountId: bc.accountId,
+      login: bc.login,
       password: bc.password,
+      twofa: bc.twofa,
+      privateKey: bc.privateKey,
+      walletAddress: bc.walletAddress,
+      token: bc.token,
     })
   }
 
@@ -133,12 +147,14 @@ export class CcxtBroker implements IBroker<CcxtBrokerMeta> {
     }
     const mergedOptions = { ...defaultOptions, ...config.options }
 
-    this.exchange = new ExchangeClass({
-      apiKey: config.apiKey,
-      secret: config.apiSecret,
-      password: config.password,
-      options: mergedOptions,
-    })
+    // Pass through all CCXT standard credential fields. CCXT ignores undefined.
+    const cfgRecord = config as unknown as Record<string, unknown>
+    const credentials: Record<string, unknown> = { options: mergedOptions }
+    for (const field of CCXT_CREDENTIAL_FIELDS) {
+      const v = cfgRecord[field]
+      if (v !== undefined) credentials[field] = v
+    }
+    this.exchange = new ExchangeClass(credentials)
 
     if (config.sandbox) {
       this.exchange.setSandboxMode(true)
@@ -164,10 +180,18 @@ export class CcxtBroker implements IBroker<CcxtBrokerMeta> {
   // ---- Lifecycle ----
 
   async init(): Promise<void> {
-    if (!this.exchange.apiKey || !this.exchange.secret) {
+    // Validate credentials per the exchange's own requiredCredentials map.
+    // Hyperliquid needs walletAddress + privateKey; OKX needs apiKey + secret + password; etc.
+    try {
+      this.exchange.checkRequiredCredentials()
+    } catch (err) {
+      const required = Object.entries(this.exchange.requiredCredentials ?? {})
+        .filter(([, needed]) => needed)
+        .map(([k]) => k)
+      const missing = required.filter(k => !(this.exchange as unknown as Record<string, unknown>)[k])
       throw new BrokerError(
         'CONFIG',
-        `No API credentials configured. Set apiKey and apiSecret in accounts.json to enable this account.`,
+        `${this.exchangeName} requires credentials: ${required.join(', ')}. Missing: ${missing.join(', ') || 'unknown'}. (${err instanceof Error ? err.message : String(err)})`,
       )
     }
 

src/domain/trading/brokers/ccxt/ccxt-types.ts

@@ -2,14 +2,30 @@ export interface CcxtBrokerConfig {
   id?: string
   label?: string
   exchange: string
-  apiKey: string
-  apiSecret: string
-  password?: string
   sandbox: boolean
   demoTrading?: boolean
   options?: Record<string, unknown>
+  // CCXT standard credential fields (all optional — each exchange requires a different subset)
+  apiKey?: string
+  secret?: string
+  uid?: string
+  accountId?: string
+  login?: string
+  password?: string
+  twofa?: string
+  privateKey?: string
+  walletAddress?: string
+  token?: string
 }
 
+/** CCXT standard credential field names (matches base Exchange.requiredCredentials map). */
+export const CCXT_CREDENTIAL_FIELDS = [
+  'apiKey', 'secret', 'uid', 'accountId', 'login',
+  'password', 'twofa', 'privateKey', 'walletAddress', 'token',
+] as const
+
+export type CcxtCredentialField = typeof CCXT_CREDENTIAL_FIELDS[number]
+
 export interface CcxtMarket {
   id: string        // exchange-native symbol, e.g. "BTCUSDT"
   symbol: string    // CCXT unified format, e.g. "BTC/USDT:USDT"

src/domain/trading/brokers/registry.ts

@@ -45,6 +45,8 @@ export interface BrokerRegistryEntry {
   subtitleFields: SubtitleField[]
   /** Guard category — determines which guard types are available */
   guardCategory: 'crypto' | 'securities'
+  /** Multi-line setup guide shown in the New Account wizard. Paragraphs separated by `\n\n`. */
+  setupGuide?: string
 }
 
 // ==================== Registry ====================
@@ -64,6 +66,13 @@ export const BROKER_REGISTRY: Record<string, BrokerRegistryEntry> = {
       { field: 'sandbox', label: 'Sandbox' },
     ],
     guardCategory: 'crypto',
+    setupGuide: `CCXT is a unified library that connects to 100+ cryptocurrency exchanges through a single API. After picking a specific exchange below, the form will auto-load the credential fields that exchange requires.
+
+Most exchanges (Binance, Bybit, OKX, etc.) use API key + secret — you can create them in your exchange account's API settings. OKX additionally requires a passphrase you set when creating the key.
+
+Wallet-based exchanges like Hyperliquid use a wallet address + private key instead. For Hyperliquid, you can generate a dedicated API wallet at app.hyperliquid.xyz/API to avoid exposing your main wallet's private key.
+
+Make sure to grant only the permissions you need (read + trade), and never enable withdrawal permissions on automated trading keys.`,
   },
   alpaca: {
     configSchema: AlpacaBroker.configSchema,
@@ -77,6 +86,9 @@ export const BROKER_REGISTRY: Record<string, BrokerRegistryEntry> = {
       { field: 'paper', label: 'Paper Trading', falseLabel: 'Live Trading' },
     ],
     guardCategory: 'securities',
+    setupGuide: `Alpaca is a commission-free US equities broker with a clean REST API. It supports paper trading (free, simulated) and live trading.
+
+Sign up at alpaca.markets, then create API keys from the dashboard. Toggle "Paper" on this form to use the paper trading endpoint with your paper keys, or off for live trading with your live keys (different key sets).`,
   },
   ibkr: {
     configSchema: IbkrBroker.configSchema,
@@ -91,5 +103,14 @@ export const BROKER_REGISTRY: Record<string, BrokerRegistryEntry> = {
       { field: 'port' },
     ],
     guardCategory: 'securities',
+    setupGuide: `Interactive Brokers requires a local TWS (Trader Workstation) or IB Gateway process running on your machine. OpenAlice connects to it over a TCP socket — no API key needed, authentication happens via TWS login.
+
+Before connecting:
+1. Open TWS / IB Gateway and log in to your paper or live account
+2. Enable API access: File → Global Configuration → API → Settings → "Enable ActiveX and Socket Clients"
+3. Note the socket port (paper: 7497, live: 7496)
+4. Add 127.0.0.1 to "Trusted IPs" if running locally
+
+Paper trading requires a separate paper account login in TWS.`,
   },
 }

ui/src/api/trading.ts

@@ -1,5 +1,5 @@
 import { fetchJson } from './client'
-import type { TradingAccount, AccountSummary, AccountInfo, Position, WalletCommitLog, ReconnectResult, AccountConfig, WalletStatus, WalletPushResult, WalletRejectResult, TestConnectionResult, BrokerTypeInfo, UTASnapshotSummary, EquityCurvePoint } from './types'
+import type { TradingAccount, AccountSummary, AccountInfo, Position, WalletCommitLog, ReconnectResult, AccountConfig, WalletStatus, WalletPushResult, WalletRejectResult, TestConnectionResult, BrokerTypeInfo, BrokerConfigField, UTASnapshotSummary, EquityCurvePoint } from './types'
 
 // ==================== Unified Trading API ====================
 
@@ -91,6 +91,14 @@ export const tradingApi = {
     return fetchJson('/api/trading/config/broker-types')
   },
 
+  async getCcxtExchanges(): Promise<{ exchanges: string[] }> {
+    return fetchJson('/api/trading/config/ccxt/exchanges')
+  },
+
+  async getCcxtCredentialFields(exchange: string): Promise<{ fields: BrokerConfigField[] }> {
+    return fetchJson(`/api/trading/config/ccxt/exchanges/${encodeURIComponent(exchange)}/credentials`)
+  },
+
   // ==================== Trading Config CRUD ====================
 
   async loadTradingConfig(): Promise<{ accounts: AccountConfig[] }> {

ui/src/api/types.ts

@@ -332,6 +332,8 @@ export interface BrokerTypeInfo {
   type: string
   name: string
   description: string
+  /** Multi-line setup guide shown in the New Account wizard. Paragraphs separated by `\n\n`. */
+  setupGuide?: string
   badge: string
   badgeColor: string
   fields: BrokerConfigField[]