API Endpoints

Relevant source files

The following files were used as context for generating this wiki page:

• client/src/components/Hero/index.tsx
• client/src/app/portal/page.tsx
• client/src/components/StockSummary/index.tsx
• client/src/components/Navbar/index.tsx
• client/src/components/StockRating/index.tsx
• client/src/components/NewsSection/index.tsx
• client/src/app/quote/[ticker]/page.tsx
• client/src/components/TickerChat/index.tsx
• client/src/components/StockChart/index.tsx
• client/src/components/StockCardMini/index.tsx

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.

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.

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.

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<Object>	An array of historical data points. Each object contains date, open, high, low, close, volume.
forecast_days	number	The number of days to forecast. The client hardcodes this to 5.

Sources: client/src/components/StockChart/index.tsx:106-117

Response Body

The endpoint returns the forecasted data along with confidence intervals.

Field	Type	Description
historical_dates	Array<string>	Dates of the historical data used.
historical_prices	Array<number>	Prices of the historical data used.
forecast_dates	Array<string>	The future dates for the forecast.
forecast_prices	Array<number>	The predicted prices for the forecast dates.
confidence_intervals	Array<Object>	An array of objects, each with lower and upper confidence bounds.
metrics	Object	Model performance metrics like mae and mape.

Sources: client/src/components/StockChart/index.tsx:84-95, 120-127