Relevant source files

The following files were used as context for generating this wiki page: - [client/src/components/Hero/index.tsx](https://github.com/asixham/greenline/blob/main/client/src/components/Hero/index.tsx) - [client/src/app/portal/page.tsx](https://github.com/asixham/greenline/blob/main/client/src/app/portal/page.tsx) - [client/src/components/StockSummary/index.tsx](https://github.com/asixham/greenline/blob/main/client/src/components/StockSummary/index.tsx) - [client/src/components/Navbar/index.tsx](https://github.com/asixham/greenline/blob/main/client/src/components/Navbar/index.tsx) - [client/src/components/StockRating/index.tsx](https://github.com/asixham/greenline/blob/main/client/src/components/StockRating/index.tsx) - [client/src/components/NewsSection/index.tsx](https://github.com/asixham/greenline/blob/main/client/src/components/NewsSection/index.tsx) - [client/src/app/quote/[ticker]/page.tsx](https://github.com/asixham/greenline/blob/main/client/src/app/quote/%5Bticker%5D/page.tsx) - [client/src/components/TickerChat/index.tsx](https://github.com/asixham/greenline/blob/main/client/src/components/TickerChat/index.tsx) - [client/src/components/StockChart/index.tsx](https://github.com/asixham/greenline/blob/main/client/src/components/StockChart/index.tsx) - [client/src/components/StockCardMini/index.tsx](https://github.com/asixham/greenline/blob/main/client/src/components/StockCardMini/index.tsx)

# API Endpoints ## Introduction The Greenline application leverages a microservices-style architecture, integrating with multiple external and internal APIs to deliver a comprehensive suite of financial data and analysis tools. The frontend client is responsible for orchestrating calls to these services to populate UI components with real-time market data, news, AI-generated insights, and predictive forecasts. This document outlines the various API endpoints consumed by the client application. The primary external data providers are **Polygon.io** for market and reference data, **Financial Modeling Prep** for stock ratings, and **OpenAI** for generative AI features. Additionally, the application communicates with an internal **Forecasting Service** for price predictions. API keys for these services are managed through environment variables. The following diagram illustrates the high-level interaction between the Greenline client and its various API dependencies. ```mermaid graph TD subgraph Greenline Client A[React Components] end subgraph External APIs B[Polygon.io API] C[Financial Modeling Prep API] D[OpenAI API] end subgraph Internal APIs E[Forecasting Service] end A -->|Market Data, News, Ticker Info| B A -->|Stock Ratings| C A -->|AI Summaries, Chat| D A -->|Price Forecasts| E ``` *Sources: [client/src/components/StockChart/index.tsx:112-117](), [client/src/components/StockSummary/index.tsx:71-77](), [client/src/components/StockRating/index.tsx:40-43](), [client/src/components/Hero/index.tsx:25-27]()* ## External APIs ### Polygon.io API Polygon.io is the primary source for most of the financial data displayed in the application, including stock prices, historical data, news, and company information. The API key is sourced from `process.env.NEXT_PUBLIC_POLYGON_API_KEY`. *Sources: [client/src/components/Hero/index.tsx:23](), [client/src/app/portal/page.tsx:55]()* The following table summarizes the Polygon.io endpoints used throughout the client application. | Feature | HTTP Method | Endpoint | Component(s) Using Endpoint - | Previous Day's Aggregates | `GET` | `/v2/aggs/ticker/{ticker}/prev` | `Hero`, `StockCardMini` - | Aggregate Bars (Time Range) | `GET` | `/v2/aggs/ticker/{ticker}/range/{multiplier}/{timespan}/{from}/{to}` | `StockSummary`, `StockCard`, `StockChart` - | Ticker Search | `GET` | `/v3/reference/tickers?search={query}` | `Navbar` - | Ticker Details | `GET` | `/v3/reference/tickers/{ticker}` | `quote/[ticker]/page`, `StockCardMini` - | General News | `GET` | `/v2/reference/news` | `portal/page`, `NewsSection` - | Market Status | `GET` | `/v1/marketstatus/now` | `portal/page` - | Related Companies | `GET` | `/v1/related-companies/{ticker}` | `quote/[ticker]/page` - *Sources: [client/src/components/Hero/index.tsx:26](), [client/src/components/StockChart/index.tsx:160](), [client/src/components/Navbar/index.tsx:61](), [client/src/app/quote/[ticker]/page.tsx:61](), [client/src/app/portal/page.tsx:56](), [client/src/app/quote/[ticker]/page.tsx:90]()* #### Data Fetch Flow (Stock Chart Example) The sequence diagram below shows the process of fetching historical data for the stock chart. ```mermaid sequenceDiagram participant User participant StockChart as "StockChart Component" participant PolygonAPI as "Polygon.io API" User->>StockChart: Selects time window (e.g., '1M') activate StockChart StockChart->>StockChart: Sets loading state to true StockChart->>PolygonAPI: GET /v2/aggs/ticker/{ticker}/range/... activate PolygonAPI PolygonAPI-->>StockChart: JSON with aggregate data deactivate PolygonAPI StockChart->>StockChart: Transforms data for chart StockChart->>StockChart: Calculates price change StockChart->>StockChart: Sets new data state, loading to false deactivate StockChart StockChart-->>User: Renders updated chart ``` *Sources: [client/src/components/StockChart/index.tsx:166-187]()* ### Financial Modeling Prep API This API is used to fetch detailed stock rating analysis. The API key is hardcoded in the request URL. | Feature | HTTP Method | Endpoint | Component(s) Using Endpoint | |-----------------|-------------|-------------------------------------------------------------------------------|-----------------------------| | Stock Rating | `GET` | `https://financialmodelingprep.com/api/v3/rating/{ticker}` | `StockRating` | The component fetches rating data, including an overall score and recommendation, along with scores for detailed metrics like DCF, ROE, ROA, DE, PE, and PB. *Sources: [client/src/components/StockRating/index.tsx:39-42]()* ### OpenAI API The application uses the OpenAI API to provide two distinct AI-powered features. The client-side code uses the `openai` library and sets the API key from `process.env.NEXT_PUBLIC_OPENAI_API_KEY`. The code explicitly allows browser-side usage, which is noted as dangerous. *Sources: [client/src/components/StockSummary/index.tsx:72-75](), [client/src/components/TickerChat/index.tsx:55-58]()* #### 1. Stock Summary Generation The `StockSummary` component identifies significant price movements from historical data and uses the OpenAI API to generate a concise explanation for each event. * **Model:** `gpt-3.5-turbo` * **Prompt:** A prompt is constructed asking the model to analyze a stock event based on its date, price, and percentage change, and to provide potential reasons for the change. *Sources: [client/src/components/StockSummary/index.tsx:79-84]()* #### 2. Ticker Chat The `TickerChat` component provides an interactive chat experience where the user can "talk" to a stock ticker. * **Model:** `gpt-4o-mini` * **System Prompt:** `"You are the stock ticker {ticker}. You will respond as if you are the ticker itself, providing insights, information, and relevant advice for those that wants to learn about {ticker} and potentially purchase some shares. Keep responses to the point while still being useful. Respond in paragraph format."` * **Functionality:** The component maintains a message history and sends it along with the new user input to the API. It supports streaming responses to display the AI's answer as it's being generated. The following diagram shows the chat interaction flow. ```mermaid sequenceDiagram participant User participant TickerChat as "TickerChat Component" participant OpenAI_API as "OpenAI API" User->>TickerChat: Enters message and sends activate TickerChat TickerChat->>TickerChat: Adds user message to state TickerChat->>TickerChat: Sets loading state TickerChat->>OpenAI_API: POST /chat/completions (stream) activate OpenAI_API Note right of TickerChat: Sends system prompt, message history, and new message OpenAI_API-->>TickerChat: Stream of response chunks TickerChat->>TickerChat: Updates streaming content in UI OpenAI_API-->>TickerChat: End of stream deactivate OpenAI_API TickerChat->>TickerChat: Adds full assistant message to state TickerChat->>TickerChat: Clears loading state deactivate TickerChat ``` *Sources: [client/src/components/TickerChat/index.tsx:29-32, 59-78]()* ## Internal APIs ### Forecasting Service The application includes a feature to forecast future stock prices. This is handled by an internal backend service running locally. #### `POST /forecast/` This endpoint is called by the `StockChart` component to generate a 5-day price forecast. * **URL:** `http://localhost:8000/forecast/` * **Method:** `POST` **Request Body** The request sends historical data to the service. | Field | Type | Description | |-------------------|---------------|---------------------------------------------------------------------------------------------------------| | `historical_data` | `Array