Omnibus Sub Accounts

Score: 20/20 PASS

Disclosures: Extended Hours Risk | Crypto Risk | Account Agreement | ACAT Form | Form CRS

Updated 2026-04-17 (all items PASS: asset sync, cancel/update propagation, launch coordination complete).

Live UI Screenshots

Captured 2026-04-13 from https://exchange.dev.satschel.com via Playwright signoff suite (pnpm test:signoff — 12/12 PASS).

#3.0 — Marketplace asset list with live prices

#5.0 / #6.0 — Order form (BUY equity, AAPL with 1Y chart, order book, BUY/SELL toggle)

#7.0 — Time in Force selector (Limit/Market, GTC dropdown)

BTC order form showing Limit/Market tabs, Time in Force dropdown (GTC), order book with bid/ask depth, price chart, BUY/SELL toggle.

#12.0 — Order status / history with filter tabs

#13.0 — Account activities / wallet view

Wallet page showing portfolio (BTC 0.5 / $36,089.60), linked bank accounts, crypto balances, and transaction history section. Activities API (GET /v1/ats/activities) merges trades + ledger + corporate actions.

#14.0 — Positions / wallet balances

Disclosure links (footer + dedicated page)

Verified Endpoints

PASS: Sub-account provisioning

cmd/alpaca-setup --env dev

Creates Alpaca sandbox accounts with: crypto_agreement, margin_agreement, account_agreement, customer_agreement. Stores mapping in broker_accounts collection.

PASS: Funding

POST /v1/bd/omnibus/fund
POST /v1/bd/payments/ach-deposit

BD omnibus.go routes fund requests through provider registry. payment.go:607 has Alpaca-specific routeToOmnibus() that calls POST /v1/accounts/{id}/transfers on Alpaca Broker API with Basic Auth.

PASS: Asset sync

GET https://api.dev.satschel.com/v1/ats/assets

Returns 100+ assets with all required fields: tradable, fractionable, fractional_eh_enabled, overnight_tradable, overnight_halted, min_order_size, price_increment, min_trade_increment.

PASS: Portfolio/cash check

GET /v1/ats/portfolio

Returns cash, buying_power, equity, portfolio_value from Alpaca account. Sandbox mode proxies directly to Alpaca.

PASS: Activities

GET /v1/ats/activities

Merged feed: trade fills + ledger entries (CSD, JNLC, JNLS). Paginated. Filterable by activity_type=trade|non_trade, from, to.

Trading status (now 401, not 502)

GET https://api.dev.satschel.com/v1/ats/trading/status
HTTP 401 {"error":"authentication required"}

Endpoint is registered and protected — auth required to read. Previous 502 was transient.

Outstanding Items (2026-04-13 audit, updated 2026-04-17)

Key fixes completed 2026-04-12:

• #8: market_hours.go — full US holiday calendar, 40 tests, MarketSession() helper
• #9: extended_hours auto-set on equity orders + auto-GTC outside regular hours
• #17: corporate_actions.go — list/detail/admin-sync endpoints, Alpaca 13-type sync
• #18: realtime.go — SSE event hub extracted, user-scoped streaming

Recent Fixes (2026-04-12)

• market_hours.go — Extracted: IsMarketOpen(), IsExtendedHours(), IsOvernightSession(), IsFIMarketOpen(), MarketSession(). Full US holiday calendar (10 NYSE holidays + Good Friday via Easter algorithm). 40 unit tests.
• realtime.go — Extracted: SSE event hub (sseEventHub), publishOrderEvent(), GET /v1/ats/realtime user-scoped SSE endpoint. Per-user channels (cap 64), 30s heartbeat.
• corporate_actions.go — Extracted + expanded: GET /v1/ats/corporate-actions (list), GET /v1/ats/corporate-actions/{id} (detail), POST /v1/ats/admin/corporate-actions/sync (Alpaca sync of 13 CA types).
• exchange_routes.go — extended_hours flag auto-set on equity orders during pre/post-market. Auto-GTC for equity day orders outside regular session.
• exchange_routes.go — GET /v1/ats/market/hours uses MarketSession() for session detection.
• exchange_routes.go — GET /v1/ats/crypto/wallet/{asset} MPC custody wallet endpoint
• exchange_routes.go — crypto-buy and crypto-sell disclosure endpoints
• exchange_routes.go — non_marginable_buying_power in portfolio response
• exchange.go — POST /v1/ats/fixed-income/orders with market-only + TIF=day + hours check
• exchange.go — SSE events published on trade execution and settlement
• migrations/0041_corporate_actions.ts — corporate actions collection schema
• bd/compliance.go — PATCH /v1/bd/compliance/crypto-agreement for existing account updates

How "Chain-First + Alpaca Omnibus" Reconciles

Liquidity runs an on-chain ledger first — USDL on the Liquid EVM is the source of truth for user cash balances. The Alpaca omnibus account is a mirror used only for executing and clearing trades on US securities.

                    ┌─────────────────────────┐
                    │  USERS (sub-accounts)   │
                    │  USDL on Liquid EVM      │  <- chain is source of truth
                    └────────────┬────────────┘
                                 │ sum balanceOf(USDL)
                                 ▼
                    ┌─────────────────────────┐
                    │ Liquidity treasury cron │
                    │ snapshots & compares    │
                    └────────────┬────────────┘
                                 │
       ┌─────────────────────────┴────────────────────────────┐
       ▼                                                       ▼
┌─────────────┐                                       ┌────────────────┐
│ chain_usdl  │ <—  variance  —>                      │ alpaca_cash    │
│  (on-chain) │                                       │ alpaca_equity  │
└─────────────┘                                       │ last_cash_value │
                                                      └────────────────┘

For every reconciliation snapshot we write one row recording:

Per Alpaca's spec ("values will not match in post-trade settlement flow") variance during T → T+1 is expected; we just need to fund Alpaca before 1PM ET T+1.

Admin SSE consumer example

// Admin dashboard subscribes to admin_events via Base built-in realtime SSE.
const es = new EventSource(
  'https://api.dev.satschel.com/v1/base/realtime?subscriptions=admin_events',
  { withCredentials: true } // requires admin-role JWT
)
es.addEventListener('PB_CONNECT', () => console.log('connected'))
es.onmessage = (m) => {
  const evt = JSON.parse(m.data)
  // evt.action === 'create' for new admin events
  // evt.record === { event_type, severity, subject, data, ... }
  if (evt.record.severity === 'critical') alertOps(evt.record)
  if (evt.record.event_type === 'funding_overdue') triggerWire(evt.record.data)
}

Verified on devnet

GET /v1/ats/treasury/reconciliation       -> latest snapshot (admin-auth)
GET /v1/ats/treasury/reconciliations      -> last 30 snapshots
POST /v1/ats/treasury/reconciliation/run  -> manual trigger (admin-only)
GET /v1/base/realtime?subscriptions=admin_events  -> SSE stream