Alpaca Trading API
Account, position, order, activity, portfolio-history, market-clock, and exchange-calendar state.
Separate paper and live endpoints
Technical overview / Vibe Trader
Document: VT-TRD-01Revision: 1.0 Implemented architecture
Vibe Trader AI Integration Architecture
An implementation architecture that combines brokerage state, live market context, model reasoning, deterministic risk controls, and traceable execution.
01
AI Integration Architecture
Logical boundaries and authoritative services
Vibe Trader AI integration architecture Implemented architecture
Vibe Trader Interface
Portfolio, agents, watchlists, market news, decisions, and AI advisor
Investor workspaceAgent configurationDecision review
Orchestration & Translation Layer
Builds market context, requests model targets, applies deterministic controls, and translates approved targets into orders
Context assemblyModel coordinationRisk enforcementOrder translation
AI Model
Produces news assessments, portfolio targets, reasoning, and advisory analysis from supplied context
GeminiOpenAIApproved model endpoints
Alpaca Services
Authoritative brokerage execution, account state, positions, market data, clock, calendar, and news
Trading APIMarket Data / IEXNews APIPaper & live accounts
Application Records
Durable configuration, assessments, decisions, account mappings, and performance snapshots
AgentsWatchlistsSentimentDecision history
Execution boundary. The model proposes analysis and target allocations. Deterministic controls authorize execution, Alpaca owns brokerage state, and application records preserve the audit trail.
02
Data sources & services
External inputs, model boundary, and derived context
Alpaca Market Data
IEX stock snapshots, bars, latest quotes, market movers, most-active names, and corporate actions.
Single and multi-symbol retrieval
Alpaca News
Recent market headlines, summaries, sources, symbols, and publication timestamps for research context.
Deduplicated before assessment
AI Model
Gemini is used by the current implementation for news assessment, target allocation, reasoning, and advisor responses.
Model boundary also supports approved endpoints
Application Records
Agent configuration, watchlists, news assessments, ticker sentiment, decisions, and account-value snapshots.
Scoped durable state and audit history
Derived Market Signals
Trend, relative strength, ATR, liquidity, spread, market regime, exposure, and position-risk calculations.
Computed by deterministic application logic
03
Agent decision lifecycle
From scheduled market context to recorded broker outcome
- 01
Schedule
A protected minute-level tick confirms the activity switch, broker clock, and extended-hours window; outside that window agents only record equity snapshots.
- 02
Score news
Once per tick and shared by every agent, Alpaca headlines are ingested, scored for sentiment and impact, and rolled up into time-decayed per-symbol sentiment.
- 03
Acquire
For each active agent: candidate discovery, account state, agent-owned positions and resting orders, quotes, bars, market screens, corporate actions, and the scored news already stored.
- 04
Enrich
Within the same pass the system computes trend across horizons, relative strength, volatility, tradability, spread, event risk, and a debounced risk-on / risk-off regime.
- 05
Protect
Before the model is consulted, code-only stop logic exits positions on ATR, trailing, break-even, and time conditions, and applies the daily loss circuit breaker.
- 06
Propose
The AI model receives the bounded context and returns a target portfolio: symbols, desired weights, rationale, supporting news references, and stale orders to cancel.
- 07
Constrain
Deterministic rules clamp or reject targets that breach eligibility, minimum hold, cooldowns, sizing, cash, exposure, concentration, or loss limits, and may backfill or park exposure.
- 08
Translate
The difference between approved targets and the agent's own book becomes sized orders, sells before buys, within no-churn and turnover limits and verified ownership.
- 09
Execute
Surviving orders are submitted to the matching Alpaca paper or live account as market or marketable-limit orders; responses and failures are captured.
- 10
Record
Decision reasoning, controls applied, broker references, realized results, and account value snapshots remain available for review.
04
Orchestration component network
Detailed flow inside the Vibe Trader control plane
Agent decision network Policy-bound execution
Scheduled Tick & Session Gate
A protected minute-level endpoint confirms the activity switch, broker clock, and extended-hours window before any agent runs; outside the window only equity snapshots are taken
Market clockExchange calendarActivity switch
News Ingestion & Scoring
Once per tick, shared across all agents: Alpaca headlines are ingested, scored by a model for sentiment and impact, then rolled up into time-decayed per-symbol sentiment
Deduplicated headlinesImpact floorTicker rollup
Per-Agent Context Assembly
For each active agent: candidate discovery, account state, agent-owned positions and orders, quotes, bars, market screens, corporate actions, scored news, and stale-order cleanup
Portfolio statePrice seriesMarket screenEquity snapshot
Signal, Regime & Entry Gates
Computed within context assembly: multi-horizon trend, relative strength, ATR and volatility, tradability, bid/ask spread, event risk, and a debounced risk-on / risk-off regime
Trend scoreRelative strengthATRRisk-on / risk-off
Protective Exits (Pre-Model)
Before the model is consulted, code-only stop logic exits positions and applies the daily loss circuit breaker, so protection never depends on model output
ATR & trailing stopsBreak-even stopTime stopDrawdown breaker
Target Portfolio Proposal
The model receives the bounded context and returns desired symbol weights with a reason and supporting news references, plus stale orders to cancel — never executable trades
Target weightsReasoningNews referencesOrder cancellations
Exposure Shaping & Clamping
Deterministic policy overrides the proposal: eligibility, minimum hold, cooldowns, per-symbol and sector caps, cash floor, and exposure backfill or risk-off parking
Sector capsCash floorCooldownsRisk-off parking
Order Diff & Translation
Approved weights are differenced against the agent's own book and sized into orders, sells before buys, within no-churn and turnover limits and verified ownership
No-churn bandTurnover budgetPosition sizingOrder ownership
Broker Execution
Only surviving orders are submitted to the agent's Alpaca paper or live account as market or marketable-limit orders according to session state
Market / marketable limitPaper & live routingBroker validation
Decision Record & Statistics
Every proposal, clamp, skip, failure, and fill is written with its reasoning and broker reference, then realized results and account value snapshots are recomputed
Decision traceRealized P&LEquity snapshots
Execution boundary. Protective exits run before the model is consulted, and proposed weights cannot bypass eligibility, sizing, exposure, drawdown, session, ownership, or broker validation controls.
05
Responsibility & trust boundaries
Authority by system component
ComponentResponsible forCannot do directly
Vibe Trader interface
Responsible for
User intent, portfolio presentation, agent settings, watchlists, and decision review
Cannot do directly
Does not hold broker secrets or submit orders directly
AI model
Responsible for
News interpretation, contextual reasoning, target-weight proposals, and advisor narrative
Cannot do directly
Cannot bypass controls, modify records, or call Alpaca directly
Orchestration & risk
Responsible for
Context assembly, eligibility, policy, sizing, target clamping, order translation, and execution sequencing
Cannot do directly
Does not invent market prices or replace the broker's accepted state
Alpaca
Responsible for
Broker account state, positions, orders, fills, market clock, market data, and source news
Cannot do directly
Does not define Vibe Trader strategy or application policy
Application records
Responsible for
Configuration, assessments, sentiment rollups, decision history, and performance snapshots
Cannot do directly
Does not supersede current broker positions or fill status
06
Risk & operational controls
Deterministic safeguards around model output
Credential isolation
Broker secrets are encrypted at rest and resolved only within server execution boundaries.
No credentials in browser state
Paper / live separation
Paper and live accounts use distinct Alpaca endpoints; live credentials require an explicit enablement switch.
Mode-specific routing
Market & portfolio gates
Price, liquidity, bid/ask spread, volatility, symbol, sector, exposure, concurrent-position, and cash limits are enforced in code.
Model output remains advisory
Loss controls
Daily soft stops, hard drawdown limits, ATR-based stops, trailing protection, and time-based exits constrain the active book.
Fail-closed enforcement
Session awareness
The exchange clock and calendar govern regular, pre-market, after-hours, and closed-session behavior.
Order type follows session state
Order ownership
Each agent acts only on its own positions and resting orders, preserving other agents and human-managed holdings.
Scoped cancellation and exit
Failure behavior: missing credentials, closed sessions, rejected symbols, invalid model output, risk-limit breaches, and broker failures stop or constrain the operation and are recorded rather than silently bypassed.
07
Persistent application records
Configuration, intelligence, decisions, and performance history
User settings
Encrypted Alpaca paper/live credentials, default mode, and live-trading enablement
Accounts & membership
Workspace ownership and access scope used to isolate portfolio context
Agents
Strategy configuration, risk tolerance, universe, budgets, operating mode, and cumulative statistics
Watchlist
User-scoped symbols included in monitoring and research context
News items
Deduplicated Alpaca headlines, summaries, sources, symbols, and timestamps
News assessments
Model-derived sentiment, impact, watch conditions, suggested action, rationale, and model identifier
Ticker sentiment
Time-decayed per-symbol sentiment rollups weighted by recency and assessed impact
Agent decisions
Proposals, controls, order intent, broker results, status, reasoning, and realized outcomes
Value snapshots
Timestamped equity, cash, and position-value measurements for agent performance