Complete API Reference for AI Tools

Comprehensive documentation for Claude, ChatGPT, GitHub Copilot, and other AI coding assistants

For AI Tools: Copy this page or reference it at /ai-integration.html

Quick Start

Base URL: Use the current domain (e.g., if viewing at example.com, use example.com)
WebSocket URL: ws://[current-domain] or wss://[current-domain] for HTTPS
Authentication: API key required (contact for access)
Response Format: JSON
Rate Limits: 300 requests/minute (cached responses don't count)

Authentication

Include your API key in the request headers:

Authorization: Bearer YOUR_API_KEY

REST API Endpoints

Stock Quotes

GET /api/quote/{symbol}

Get real-time quote for a single stock symbol

GET /api/quote/AAPL

Response

{
  "symbol": "AAPL",
  "price": 195.83,
  "change": 2.15,
  "changesPercentage": 1.11,
  "dayLow": 193.67,
  "dayHigh": 196.38,
  "yearLow": 164.08,
  "yearHigh": 199.62,
  "volume": 58935235,
  "previousClose": 193.68,
  "open": 194.50
}

POST /api/quotes/bulk

Get quotes for multiple symbols in one request

POST /api/quotes/bulk
Content-Type: application/json

{
  "symbols": ["AAPL", "MSFT", "GOOGL", "TSLA"]
}

Response

[
  {
    "symbol": "AAPL",
    "price": 195.83,
    "change": 2.15,
    "changesPercentage": 1.11
  },
  {
    "symbol": "MSFT",
    "price": 430.82,
    "change": -1.23,
    "changesPercentage": -0.28
  }
  // ... more symbols
]

GET /api/quotes

Get quotes for all tracked symbols

GET /api/quotes

Market Movers

GET /api/market-gainers

Get top gaining stocks of the day

GET /api/market-losers

Get top losing stocks of the day

GET /api/market-actives

Get most actively traded stocks

Economic Data (FRED)

GET /api/fred/series/{seriesId}

Get economic data series from Federal Reserve (FRED)

GET /api/fred/series/GDP
GET /api/fred/series/UNRATE
GET /api/fred/series/CPIAUCSL

GET /api/fred/search?text={query}

Search for FRED series by keyword

GET /api/fred/search?text=inflation

Search & Discovery

GET /api/stock-screener

Screen stocks based on multiple criteria

GET /api/stock-screener?marketCapMoreThan=1000000000§or=Technology&limit=50

Parameters:

marketCapMoreThan, marketCapLowerThan, priceMoreThan, priceLowerThan,
volumeLowerThan, volumeMoreThan, sector, industry, country, exchange, limit

GET /api/search-cik?query={query}

Search companies by CIK (Central Index Key)

GET /api/search-cik?query=0000320193

GET /api/search-cusip?cusip={cusip}

Search companies by CUSIP number

GET /api/search-cusip?cusip=037833100

GET /api/search-isin?isin={isin}

Search companies by ISIN

GET /api/search-isin?isin=US0378331005

GET /api/available-traded

Get list of all available traded symbols

Extended Company Information

GET /api/key-executives/{symbol}

Get company key executives (CEO, CFO, etc.)

GET /api/key-executives/AAPL

GET /api/company-outlook/{symbol}

Get comprehensive company outlook including all data

GET /api/company-outlook/AAPL

GET /api/shares-float/{symbol}

Get shares float data

GET /api/shares-float/AAPL

Financial Analysis

GET /api/ratios/{symbol}

Get comprehensive financial ratios

GET /api/ratios/AAPL

Includes: P/E, P/B, P/S, PEG, debt ratios, profitability ratios, liquidity ratios, etc.

GET /api/ratios-ttm/{symbol}

Get trailing twelve months financial ratios

GET /api/ratios-ttm/AAPL

GET /api/enterprise-values/{symbol}

Get enterprise value calculations

GET /api/enterprise-values/AAPL

GET /api/rating/{symbol}

Get company rating and recommendation

GET /api/rating/AAPL

GET /api/dcf/{symbol}

Get discounted cash flow valuation

GET /api/dcf/AAPL

Market Performance & Sectors

GET /api/sectors-performance

Get current performance of all market sectors

GET /api/sectors-performance

GET /api/historical-sectors-performance

Get historical sectors performance data

ETFs & Mutual Funds

GET /api/etf-list

Get complete list of all ETFs

GET /api/etf-sector-weightings/{symbol}

Get ETF sector allocation breakdown

GET /api/etf-sector-weightings/SPY

GET /api/etf-country-weightings/{symbol}

Get ETF country allocation breakdown

GET /api/etf-country-weightings/VTI

GET /api/mutual-fund-list

Get complete list of all mutual funds

Calendar Events

GET /api/ipo-calendar

Get upcoming initial public offerings (IPOs)

GET /api/dividend-calendar

Get upcoming dividend payments

GET /api/splits-calendar

Get upcoming stock splits

GET /api/economic-calendar

Get upcoming economic events and data releases

Market Status & Economic Data

GET /api/is-market-open

Check if the US stock market is open

Response:

{
  "isOpen": true,
  "session": "regular",
  "timezone": "America/New_York"
}

GET /api/market-hours

Get market trading hours for different exchanges

GET /api/treasury-rates

Get current US Treasury bond rates

Alternative Data

GET /api/esg-data/{symbol}

Get Environmental, Social, and Governance (ESG) ratings

GET /api/esg-data/AAPL

GET /api/social-sentiment-trending

Get trending social sentiment data

GET /api/delisted-companies

Get list of recently delisted companies

GET /api/symbol-changes

Get recent ticker symbol changes

Pre/Post Market Data

GET /api/pre-post-market/{symbol}

Get pre-market and after-hours trading data

GET /api/pre-post-market/AAPL

GET /api/pre-post-market-trade/{symbol}

Get detailed pre/post market trades

Additional Endpoints

GET /api/market-news

Get latest financial market news

GET /api/crypto-quotes

Get cryptocurrency quotes

GET /api/sp500-constituents

Get list of S&P 500 companies

Bulk Operations

POST /api/batch-eod-prices

Get batch end-of-day prices for multiple symbols

POST /api/batch-eod-prices
Content-Type: application/json

{
  "date": "2024-01-15",
  "symbols": ["AAPL", "MSFT", "GOOGL"]
}

GET /api/profile-bulk

Get all company profiles in bulk (large dataset)

GET /api/income-statement-bulk?year={year}&period={period}

Get bulk income statements

GET /api/income-statement-bulk?year=2023&period=annual

Stock Analysis & Screening

GET /api/stock-screener

Filter stocks by market cap, price, volume, sector, and other criteria

GET /api/stock-peers/{symbol}

Get companies similar to the specified stock

GET /api/etf-constituents/{symbol}

Get all holdings within an ETF

GET /api/delisted-companies

List companies that have been delisted from exchanges

GET /api/stock-grade/{symbol}

Get analyst grades and ratings for a stock

GET /api/analyst-estimates/{symbol}

Get analyst earnings and revenue estimates

GET /api/analyst-recommendations/{symbol}

Get analyst buy/hold/sell recommendations (grades)

GET /api/grades-consensus/{symbol}

Get consensus analyst grades summary

GET /api/grades-historical/{symbol}

Get historical analyst grades changes

GET /api/grades-news/{symbol}?page=0&limit=10

Get latest news about analyst grade changes

GET /api/earnings-surprises/{symbol}

Get historical earnings surprises vs estimates

GET /api/earnings-confirmed/{symbol}

Get confirmed earnings announcement dates

SEC Filings & Regulatory

GET /api/sec-filings/{symbol}

Get all SEC filings (10-K, 10-Q, 8-K, etc.) for a company

GET /api/rss-sec-filings/{symbol}

Get RSS feed of latest SEC filings

GET /api/insider-trades/{symbol}

Get insider buying and selling activity

GET /api/insider-trades-rss

Get RSS feed of all insider trading activity

GET /api/fail-to-deliver/{symbol}

Get fail to deliver data from SEC

GET /api/cik-mapper

Map company names to CIK identifiers

GET /api/search-cik

Search for CIK by company name

GET /api/cusip-mapper/{cusip}

Convert CUSIP to company information

GET /api/isin-mapper/{isin}

Convert ISIN to company information

Company Management

GET /api/key-executives/{symbol}

Get list of key executives and their roles

GET /api/executive-compensation/{symbol}

Get detailed executive compensation data

GET /api/compensation-benchmark/{symbol}

Compare executive compensation to industry peers

GET /api/company-notes/{symbol}

Get analyst notes and commentary

GET /api/historical-employee-count/{symbol}

Get historical employee count trends

GET /api/employee-count/{symbol}

Get current number of employees

Ownership & Holdings

GET /api/ownership-by-shares/{symbol}

Get ownership breakdown by number of shares held

GET /api/institutional-ownership/{symbol}

Get institutional investor holdings

GET /api/mutual-fund-ownership/{symbol}

Get mutual fund holdings in the stock

GET /api/etf-ownership/{symbol}

Get ETF holdings in the stock

GET /api/institutional-holders-list

List all institutional investment firms

GET /api/institutional-ownership-weightings/{symbol}

Get portfolio weightings for institutional holders

GET /api/sec-rss-feeds

Get list of available SEC RSS feed endpoints

GET /api/cik-list

Get complete list of all CIK identifiers

Calendar & Events

GET /api/economic-calendar

Get upcoming economic events and indicators

GET /api/historical-economic-data/{indicator}

Get historical data for economic indicators

GET /api/ipo-calendar

Get upcoming IPO listings

GET /api/ipo-calendar-prospectus

Get IPO prospectus document links

GET /api/ipo-calendar-confirmed

Get confirmed IPO dates and details

GET /api/earnings-calendar

Get upcoming earnings announcements

GET /api/historical-earnings-calendar/{symbol}

Get historical earnings dates for a company

GET /api/stock-split-calendar

Get upcoming stock splits

GET /api/historical-stock-split/{symbol}

Get historical stock splits for a company

GET /api/dividend-calendar

Get upcoming dividend payments

GET /api/historical-dividend/{symbol}

Get historical dividend payments

ETF & Fund Analysis

GET /api/fund-holdings/{symbol}

Get current holdings of a mutual fund or ETF

GET /api/fund-holdings-date/{symbol}

Get fund holdings for a specific date

GET /api/portfolio-holdings/{cik}

Get portfolio holdings using CIK identifier

GET /api/etf-info/{symbol}

Get detailed ETF information and metrics

GET /api/etf-expense-ratio/{symbol}

Get ETF expense ratio and fees

GET /api/etf-sector-weightings/{symbol}

Get ETF holdings by sector allocation

GET /api/etf-country-weightings/{symbol}

Get ETF holdings by country allocation

GET /api/etf-list

Get complete list of all available ETFs

GET /api/available-etfs

Get list of ETFs with available data

Market Lists & Indices

GET /api/index-list

Get list of all market indices

GET /api/available-indices

Get indices with available data

GET /api/sp500-list

Get all S&P 500 component stocks

GET /api/nasdaq-list

Get all NASDAQ listed companies

GET /api/dowjones-list

Get all Dow Jones 30 components

GET /api/commodity-list

Get list of tradeable commodities

GET /api/available-commodities

Get commodities with available data

GET /api/euronext-list

Get all Euronext listed companies

GET /api/tsx-list

Get all Toronto Stock Exchange companies

GET /api/crypto-list

Get list of all cryptocurrencies

GET /api/available-cryptocurrencies

Get cryptocurrencies with available data

GET /api/forex-list

Get list of forex currency pairs

GET /api/available-forex

Get forex pairs with available data

WebSocket Real-time Data

Important: WebSocket only streams Trade messages (actual executed trades), not Quote messages (bid/ask). This ensures stable, accurate prices without jumps from wide spreads.

Connection Setup

// Get WebSocket URL based on current protocol
const wsProtocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
const wsUrl = wsProtocol + '//' + window.location.host;
const ws = new WebSocket(wsUrl);

ws.on('open', () => {
    console.log('Connected to DataBeast WebSocket');
});

ws.on('message', (data) => {
    const message = JSON.parse(data);
    
    switch(message.type) {
        case 'connected':
            console.log('Connection confirmed');
            break;
        case 'stockUpdate':
            handleStockUpdate(message.data);
            break;
        case 'subscribed':
            console.log('Subscribed to:', message.tickers);
            break;
    }
});

Subscribe to Symbols

// Subscribe to single symbol
ws.send(JSON.stringify({
    type: 'subscribe',
    ticker: 'AAPL'
}));

// Subscribe to multiple symbols
ws.send(JSON.stringify({
    type: 'subscribe',
    tickers: ['AAPL', 'MSFT', 'GOOGL', 'TSLA']
}));

Stock Update Message Format

{
    "type": "stockUpdate",
    "data": {
        "s": "AAPL",           // Symbol
        "p": 195.83,           // Current price (last trade)
        "c": 2.15,             // Change from previous close
        "cp": 1.11,            // Change percentage
        "v": 58935235,         // Volume
        "t": 1703123456789,    // Timestamp
        "type": "T"            // Trade message type
    }
}

Complete WebSocket Example

// React Component Example
import React, { useEffect, useState } from 'react';

function LiveStockPrices({ symbols }) {
    const [prices, setPrices] = useState({});
    
    useEffect(() => {
        const wsProtocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
        const ws = new WebSocket(wsProtocol + '//' + window.location.host);
        
        ws.onopen = () => {
            // Subscribe to symbols
            ws.send(JSON.stringify({
                type: 'subscribe',
                tickers: symbols
            }));
        };
        
        ws.onmessage = (event) => {
            const message = JSON.parse(event.data);
            
            if (message.type === 'stockUpdate') {
                const { data } = message;
                setPrices(prev => ({
                    ...prev,
                    [data.s]: {
                        price: data.p,
                        change: data.c,
                        changePercent: data.cp,
                        volume: data.v
                    }
                }));
            }
        };
        
        return () => ws.close();
    }, [symbols]);
    
    return (
        <div>
            {Object.entries(prices).map(([symbol, data]) => (
                <div key={symbol}>
                    <h3>{symbol}</h3>
                    <p>Price: ${data.price.toFixed(2)}</p>
                    <p style={{color: data.change >= 0 ? 'green' : 'red'}}>
                        {data.change >= 0 ? '+' : ''}{data.change.toFixed(2)} 
                        ({data.changePercent.toFixed(2)}%)
                    </p>
                    <p>Volume: {data.volume.toLocaleString()}</p>
                </div>
            ))}
        </div>
    );
}

Code Examples

Fetching Stock Data

// Note: When using relative URLs, the requests will be made to the current domain

// Fetch single quote
async function getQuote(symbol) {
    const response = await fetch(`/api/quote/${symbol}`);
    return response.json();
}

// Fetch multiple quotes
async function getBulkQuotes(symbols) {
    const response = await fetch('/api/quotes/bulk', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({ symbols })
    });
    return response.json();
}

// Get market movers
async function getMarketMovers() {
    const [gainers, losers, actives] = await Promise.all([
        fetch('/api/market-gainers').then(r => r.json()),
        fetch('/api/market-losers').then(r => r.json()),
        fetch('/api/market-actives').then(r => r.json())
    ]);
    
    return { gainers, losers, actives };
}

// Usage examples
const appleQuote = await getQuote('AAPL');
console.log(`Apple: $${appleQuote.price} (${appleQuote.changesPercentage}%)`);

const techStocks = await getBulkQuotes(['AAPL', 'MSFT', 'GOOGL', 'AMZN']);
techStocks.forEach(stock => {
    console.log(`${stock.symbol}: $${stock.price}`);
});

cURL Commands for Testing

# Replace [domain] with your actual domain (e.g., localhost:3000, example.com)

# Get single quote
curl http://[domain]/api/quote/AAPL

# Get company profile
curl http://[domain]/api/company-profile/AAPL

# Get market gainers
curl http://[domain]/api/market-gainers

# Post bulk quotes
curl -X POST http://[domain]/api/quotes/bulk \
     -H "Content-Type: application/json" \
     -d '{"symbols": ["AAPL", "MSFT", "GOOGL"]}'

AI Assistant Prompts

Example Prompts for Building with DataBeast

For Claude/ChatGPT: Copy these prompts and modify for your needs:

# Create a Real-time Stock Dashboard
"Using the DataBeast API on the current domain, create a React dashboard that:
1. Displays real-time stock prices using WebSocket connection
2. Shows price changes with green/red indicators
3. Subscribes to tech stocks: AAPL, MSFT, GOOGL, AMZN, TSLA
4. Updates automatically when new trades occur
5. Includes volume and percentage change

Use relative URLs for all API calls and determine WebSocket URL from window.location."

# Build a Market Analysis Tool
"Create a JavaScript application using DataBeast API that:
1. Fetches market gainers and losers from /api/market-gainers and /api/market-losers
2. Gets company profiles for top 5 gainers using /api/company-profile/{symbol}
3. Analyzes sector distribution of movers
4. Outputs a summary report

Use fetch() with relative URLs for all API endpoints."

# Create Stock Screener Application
"Build a stock screening tool that:
1. Uses /api/stock-screener with filters for market cap, price, volume, and sector
2. Fetches detailed ratios using /api/ratios/{symbol} for filtered results
3. Calculates DCF valuation using /api/dcf/{symbol}
4. Displays results in a sortable table with key metrics
5. Allows export of screened stocks to CSV"

# Build ESG Portfolio Analyzer
"Create an ESG-focused portfolio analyzer that:
1. Takes a list of stock symbols as input
2. Fetches ESG ratings from /api/esg-data/{symbol} for each stock
3. Gets financial ratios from /api/ratios-ttm/{symbol}
4. Calculates portfolio-weighted ESG scores
5. Identifies high ESG-rated stocks with good financial metrics
6. Uses /api/sectors-performance to show sector allocation"

# Create Calendar Event Dashboard
"Build a financial calendar dashboard that:
1. Fetches upcoming events from /api/ipo-calendar, /api/dividend-calendar, /api/splits-calendar
2. Shows economic events from /api/economic-calendar
3. Displays events in a calendar view
4. Allows filtering by event type and date range
5. Gets company details for IPOs using /api/company-profile/{symbol}"

# Market Status Monitor
"Create a market status monitoring service that:
1. Checks /api/is-market-open every minute
2. Fetches /api/treasury-rates when market opens
3. Gets pre-market data from /api/pre-post-market/{symbol} for watchlist
4. Monitors /api/social-sentiment-trending for unusual activity
5. Sends notifications for market open/close and significant events"

Important Notes

Caching: Responses are cached for performance. Quote data cached for 1 minute, company profiles for 24 hours.
Rate Limiting: 300 requests/minute. Cached responses don't count against limit.
WebSocket Data: Only Trade messages (type 'T') are streamed. This provides actual executed prices, not bid/ask quotes.
Authentication: API key required for production use. Contact for access.
CORS: Enabled for all origins, suitable for browser-based applications.
Errors: All errors return JSON with 'error' field and appropriate HTTP status code.

Error Response Format

{
    "error": "Symbol not found",
    "message": "The requested symbol INVALID does not exist",
    "statusCode": 404
}

Complete Endpoint Reference

All Available Endpoints Summary

Stock Quotes & Prices

GET /api/quote/{symbol} - Real-time quote
POST /api/quotes/bulk - Multiple quotes
GET /api/quotes - All tracked quotes
GET /api/crypto-quotes - Cryptocurrency quotes
GET /api/crypto-quote/{symbol} - Single crypto quote
GET /api/quote-short/{symbol} - Abbreviated quote
GET /api/full-quote/{symbol} - Extended quote data
GET /api/otc-real-time/{symbol} - OTC real-time prices
GET /api/pre-post-market/{symbol} - Pre/post market data

Financial Statements

GET /api/income-statement/{symbol}?period={annual|quarter}
GET /api/balance-sheet/{symbol}?period={annual|quarter}
GET /api/cash-flow/{symbol}?period={annual|quarter}
GET /api/financial-growth/{symbol}
GET /api/financial-growth-quarterly/{symbol}

Financial Analysis

GET /api/key-metrics/{symbol} - Key metrics
GET /api/key-metrics-ttm/{symbol} - TTM metrics
GET /api/ratios/{symbol} - Financial ratios
GET /api/ratios-ttm/{symbol} - TTM ratios
GET /api/enterprise-values/{symbol} - Enterprise value
GET /api/rating/{symbol} - Company rating
GET /api/dcf/{symbol} - DCF valuation
GET /api/financial-score/{symbol} - Financial score

Market Data

GET /api/market-gainers - Top gainers
GET /api/market-losers - Top losers
GET /api/market-actives - Most active
GET /api/sectors-performance - Sector performance
GET /api/sp500-constituents - S&P 500 list
GET /api/dowjones-constituents - Dow Jones list

Search & Discovery

GET /api/stock-screener - Screen stocks
GET /api/search-cik?query={query} - Search by CIK
GET /api/search-cusip?cusip={cusip} - Search by CUSIP
GET /api/search-isin?isin={isin} - Search by ISIN
GET /api/available-traded - All traded symbols

Calendar Events

GET /api/ipo-calendar - IPO calendar
GET /api/dividend-calendar - Dividend calendar
GET /api/splits-calendar - Splits calendar
GET /api/earning-calendar?from={date}&to={date} - Earnings
GET /api/economic-calendar - Economic events

News & Sentiment

GET /api/news/{symbol} - Company news
GET /api/market-news - Market news
GET /api/social-sentiment/{symbol} - Social sentiment
GET /api/social-sentiment-trending - Trending sentiment
GET /api/press-releases/{symbol} - Press releases

Analyst Data

GET /api/analyst-estimates/{symbol} - Analyst estimates
GET /api/analyst-recommendations/{symbol} - Analyst buy/hold/sell recommendations
GET /api/grades-consensus/{symbol} - Consensus analyst grades
GET /api/grades-historical/{symbol} - Historical grade changes
GET /api/grades-news/{symbol}?page=0&limit=10 - Grade change news
GET /api/price-target/{symbol} - Price targets
GET /api/price-target-consensus/{symbol} - Target consensus

Insider & Institutional

GET /api/insider-trading/{symbol} - Insider trades
GET /api/insider-statistics/{symbol} - Insider stats
GET /api/institutional-holders/{symbol} - Institutions
GET /api/etf-holdings/{symbol} - ETF holdings
GET /api/senate-trading/{symbol} - Senate trades

Alternative Data

GET /api/esg-data/{symbol} - ESG ratings
GET /api/fail-to-deliver/{symbol} - Fail to deliver
GET /api/delisted-companies - Delisted companies
GET /api/symbol-changes - Symbol changes

Market Status

GET /api/is-market-open - Market open status
GET /api/market-hours - Trading hours
GET /api/treasury-rates - Treasury rates

Quick Links

API Explorer Test endpoints in browser

WebSocket Tester Test real-time data

API Metadata List all endpoints

Cache Statistics Monitor performance