AlpacaTradingAgent

AlpacaTradingAgent is an open-source Next.js trading dashboard and multi-agent market analysis playground. It combines a streaming NDJSON pipeline, Alpaca-style paper trading flows, and mock-first JSON data so you can build and test fintech UIs without API keys—then optionally connect OpenAI, Alpaca, Finnhub, FRED, and CoinDesk.

Table of contents

• Features
• Tech stack
• Requirements
• Quick start
• Environment variables
• REST API routes
• Project structure
• Deployment
• Contributing
• Disclaimer

Features

• Trading desk UI — three-column layout: live pipeline rail, chart and research panels, execution stack (orders, account snapshot, trade signal, event log).
• Multi-agent pipeline — market, sentiment, news, fundamentals, macro, debates, risk, and final decision; core logic in src/lib/engine/pipeline.ts, signal parsing in src/lib/engine/signal.ts.
• Streaming analysis — POST /api/analyze returns NDJSON for progressive UI updates and auditing.
• Paper trading & dry-run — safe defaults; real Alpaca order POST only when ALPACA_ENABLE_ORDER_API=true.
• TypeScript end-to-end — Zod validation, Vitest tests, ESLint via next lint.

Tech stack

Area	Technologies
Framework	Next.js 14 (App Router), React 18
Styling & UI	Tailwind CSS, Radix UI, Framer Motion
Charts	Recharts
Testing	Vitest

Keywords people use to find this kind of project: Next.js trading app, Alpaca API, paper trading dashboard, algorithmic trading UI, mock market data, NDJSON streaming API, fintech frontend, stock chart React.

Requirements

• Node.js 20.x (LTS recommended)
• npm 9+ or compatible package manager

Quick start

git clone https://github.com/Rezzecup/AlpacaTradingAgent.git
cd AlpacaTradingAgent
npm install
cp .env.example .env.local
# Optional: add API keys in .env.local for live Alpaca, OpenAI, Finnhub, FRED
npm run dev

Open http://localhost:3000.

npm run build    # production build (includes typecheck + lint)
npm run start    # production server
npm run lint
npm test

Environment variables (Alpaca, OpenAI, Finnhub, FRED)

Copy .env.example to .env.local. All variables below are optional for mock-only mode.

Variable	Purpose
OPENAI_API_KEY	Live LLM / analyst synthesis
ALPACA_API_KEY / ALPACA_SECRET_KEY	Live Alpaca account & market data
ALPACA_USE_PAPER	Paper vs live when using Alpaca keys
ALPACA_ENABLE_ORDER_API	Set true only if you intend real broker POST on /api/paper-order
FINNHUB_API_KEY	Live news in /api/news
FRED_API_KEY	Live macro series in /api/macro (e.g. DGS10)
COINDESK_API_KEY	Optional crypto-related data
PORT	Next.js listen port

See .env.example for FORGE_DB_API_URL and DATABASE_URL. Do not commit .env or .env.local.

REST API routes (Next.js App Router)

Route	Description
GET /api/health	Environment keys and feature flags
GET /api/config	Merged trading configuration
POST /api/analyze	Run pipeline; NDJSON stream
GET /api/account	Portfolio-style account snapshot
GET /api/chart	OHLC bars for charts
GET /api/quote	Symbol quote
GET /api/market	Market session / clock helpers
GET /api/news	News feed (Finnhub or mock)
GET /api/macro	Macro context (FRED + mocks)
POST /api/paper-order	Paper / dry-run orders
GET /api/tools	Tool and mock catalog
GET /api/mocks	Mock index
GET /api/mock-dataset	Load fixture JSON by id

Inspect payloads via /api/tools and the in-app mock browser.

Project structure

src/app/         # Next.js App Router pages & route handlers
src/components/  # Dashboard and shared UI
src/lib/         # Pipeline engine, services, config, mocks
src/mocks/data/  # JSON fixtures for offline / demo mode
src/types/       # Shared TypeScript types

Disclaimer

This software is for education and UI / workflow testing only. It is not financial, investment, or trading advice. Mock and synthetic data may not reflect real markets. You are responsible for compliance, risk, and any use of live broker or market APIs (including Alpaca).