Market Overview

Live Stock Prices

Pull real-time closing prices, volume, bid/ask, day changes, and 52-week ranges directly into your app or website. Covers all JSE Main and Junior Market stocks.

Historical Data

Access daily price history for any stock. Perfect for backtesting strategies, building charts, or running analysis.

Financial Statements

Retrieve income statements, balance sheets, and key financial ratios. Extracted directly from quarterly and annual filings.

Ownership & Directors

See top shareholders, board of directors, cross-holdings between companies, and institutional ownership data.

Search & Lookup

Search stocks by name or symbol. Look up individual stocks or get full market snapshots in a single call.

PE Ratios & Documents

Get calculated PE ratios for all stocks and access filed PDF documents including annual reports and financial statements.

Pass your API key in the X-API-Key header with every request.

GET /api/v1/public/stock/NCBFG

Loading...

Personal API Tokens

Loading...

# Get your portfolios
curl https://stacksja.com/api/v2/user/portfolios   -H "Authorization: Bearer stk_your_token_here"

# Get your alerts
curl https://stacksja.com/api/v2/user/alerts   -H "Authorization: Bearer stk_your_token_here"

# Get your watchlists
curl https://stacksja.com/api/v2/user/watchlists   -H "Authorization: Bearer stk_your_token_here"

Endpoints

Getting Started

Authentication

All API requests require an API key. Pass your key in the X-API-Key header with every request.

curl https://stacksja.com/api/v1/public/stocks \
  -H "X-API-Key: pk_your_key_here"

SSE streaming endpoints use an api_key query parameter instead of the header.

Don’t have a key? Apply for a free API key — approvals are typically same-day.

Quick Start

Here are the most common use cases to get you started:

GET /stocks

GET /stock/NCBFG

GET /quote?name=grace → resolves to GK

GET /stream?api_key=pk_your_key

GET /stock/NCBFG/trades

GET /stock/NCBFG/orderbook

Symbol resolution: All /stock/{symbol} endpoints support fuzzy matching. You can pass a ticker symbol (GK) or a company name (grace) and the API will resolve it.

Market Data

Returns all stocks for the latest trading day with current prices. Use this to build a market overview or stock screener.

Parameters

Example

curl "https://stacksja.com/api/v1/public/stocks?market=main" \
  -H "X-API-Key: pk_your_key"

Response

{
  "trade_date": "2026-03-12",
  "count": 42,
  "market_status": "open",
  "data_type": "intraday",
  "price_label": "Intraday prices as of 1:30 PM",
  "stocks": [
    {
      "symbol": "GK",
      "market": "main",
      "trade_date": "2026-03-12",
      "closing_price": "125.00",
      "last_traded_price": "126.50",
      "price_change": "1.50",
      "change_percent": "1.21",
      "volume": "45000",
      "company_name": "GraceKennedy"
    }
  ]
}

market_status is open during JSE trading hours (Mon-Fri 9:30 AM - 1:30 PM Jamaica time, excluding holidays). data_type is intraday when market is open, closing after close.

Get detailed data for a single stock including bid/ask, ranges, and dividend info. Supports fuzzy symbol matching (e.g. “grace” resolves to GK).

Parameters

Example

curl "https://stacksja.com/api/v1/public/stock/NCBFG" \
  -H "X-API-Key: pk_your_key"

Response

{
  "symbol": "NCBFG",
  "company_name": "NCB Financial Group",
  "market": "main",
  "trade_date": "2026-03-12",
  "closing_price": "42.84",
  "last_traded_price": "42.84",
  "price_change": "-0.01",
  "change_percent": -0.02,
  "volume": "2,598,715",
  "closing_bid": "42.50",
  "closing_ask": "42.84",
  "todays_range": "42.50 - 44.98",
  "week_range_52": "33.00 - 51.00",
  "total_prev_yr_div": "1.20",
  "total_current_yr_div": "0.50",
  "market_status": "closed",
  "data_type": "closing",
  "last_updated": "2026-03-12T14:30:00",
  "price_label": "Closing Price"
}

Quick price quote resolved by name or symbol. Useful for chatbots, voice assistants, or any interface where users type a company name instead of a ticker.

Parameters

Example

curl "https://stacksja.com/api/v1/public/quote?name=grace" \
  -H "X-API-Key: pk_your_key"

Returns the same data as /stock/{{symbol}} but accepts free-text input. Great for natural language lookups.

Search stocks by ticker or company name. Returns matching symbols with company names.

Parameters

Example

curl "https://stacksja.com/api/v1/public/search?q=bank" \
  -H "X-API-Key: pk_your_key"

Response

{
  "query": "bank",
  "count": 3,
  "results": [
    { "symbol": "NCBFG", "company_name": "NCB Financial Group" },
    { "symbol": "BIL", "company_name": "Barita Investments" },
    { "symbol": "JMMBGL", "company_name": "JMMB Group" }
  ]
}

Historical closing prices for a stock. Use this for price charts and trend analysis.

Parameters

Example

curl "https://stacksja.com/api/v1/public/stock/NCBFG/history?limit=5" \
  -H "X-API-Key: pk_your_key"

Response

{
  "symbol": "NCBFG",
  "count": 5,
  "history": [
    {
      "trade_date": "2026-03-12",
      "closing_price": "42.84",
      "price_change": "-0.01",
      "change_percent": -0.02,
      "volume": "2,598,715"
    }
  ]
}

History is ordered most recent first. Use limit=365 for a full year of data.

Price-to-Earnings ratios for all companies with financial data. Uses trailing 12-month EPS calculated from the most recent quarterly or annual filings.

Example

curl "https://stacksja.com/api/v1/public/pe-ratios" \
  -H "X-API-Key: pk_your_key"

Response

{
  "count": 46,
  "pe_ratios": [
    {
      "symbol": "SML",
      "company_name": "Stanley Motta",
      "pe_ratio": 1.45,
      "ttm_eps": 3.95,
      "shares_outstanding": 22951646
    }
  ]
}

Sorted by P/E ratio ascending (lowest first). ttm_eps = Trailing Twelve Months Earnings Per Share. Only includes companies with confirmed financial data.

Server-Sent Events (SSE) stream for real-time price updates across all stocks. Pushes events whenever a stock price changes during market hours.

Parameters

Example

curl -N "https://stacksja.com/api/v1/public/stream?api_key=pk_your_key"

Event Format

event: price_update
data: {"symbol":"GK","price":"126.50","change":"+1.50","change_pct":"+1.21%","volume":"45000","time":"2026-03-12T13:45:00"}

The connection stays open indefinitely. SSE connections are not rate limited. Use /stream/{{symbol}} to filter to a single stock.

SSE stream filtered to a single stock. Only receives updates for the specified symbol.

Parameters

Example

curl -N "https://stacksja.com/api/v1/public/stream/NCBFG?api_key=pk_your_key"

Trading Activity

Get all intraday trades for a single stock. Each trade includes execution time, price, quantity, and computed value. Summary includes VWAP, high, and low.

Parameters

Example

curl "https://stacksja.com/api/v1/public/stock/NCBFG/trades" \
  -H "X-API-Key: pk_your_key"

Response

{
  "trade_date": "2026-03-12",
  "symbol": "NCBFG",
  "count": 111,
  "total_shares": 2598715,
  "total_value": 111319766.62,
  "vwap": 42.8365,
  "high": 44.98,
  "low": 42.5,
  "trades": [
    {
      "time": "9:56:44 AM",
      "price": 44.3,
      "quantity": 50,
      "value": 2215.0
    }
  ]
}

Trades are ordered most recent first. VWAP (Volume Weighted Average Price) = total value ÷ total shares. Data is sourced from JTrader and captured throughout the trading day.

Get all intraday trades across every symbol for a given date. Returns trades grouped by symbol, each with per-symbol summaries and individual trade records. This is the “full tape” for the day.

Parameters

Example

curl "https://stacksja.com/api/v1/public/trades?market=main" \
  -H "X-API-Key: pk_your_key"

Response

{
  "trade_date": "2026-03-12",
  "symbols": 103,
  "total_trades": 1618,
  "total_shares": 5400000,
  "total_value": 162718901.19,
  "data": [
    {
      "symbol": "NCBFG",
      "market": "Main Market",
      "trade_count": 111,
      "total_shares": 2598715,
      "total_value": 111319766.62,
      "vwap": 42.8365,
      "high": 44.98,
      "low": 42.5,
      "trades": [ ... ]
    }
  ]
}

Each symbol in data includes its own VWAP, high/low, and full list of individual trades. Response can be large — use market filter to reduce payload size.

Order Book

Get the full buy and sell order queue for a stock. Returns individual orders on each side sorted by rank, plus summary totals showing buy/sell split.

Parameters

Example

curl "https://stacksja.com/api/v1/public/stock/NCBFG/orderbook" \
  -H "X-API-Key: pk_your_key"

Response

{
  "trade_date": "2026-03-12",
  "symbol": "NCBFG",
  "buy_orders": [
    { "rank": 1, "quantity": 200, "price": 44.9, "value": 8980.0 },
    { "rank": 2, "quantity": 5000, "price": 44.85, "value": 224250.0 }
  ],
  "sell_orders": [
    { "rank": 1, "quantity": 99837, "price": 44.98, "value": 4490668.26 }
  ],
  "summary": {
    "buy_order_count": 113,
    "sell_order_count": 30,
    "total_buy_quantity": 577643,
    "total_sell_quantity": 466244,
    "total_buy_value": 23936561.9,
    "total_sell_value": 27246953.36,
    "buy_percentage": 46.8,
    "sell_percentage": 53.2
  }
}

Returns "summary": null when no order data exists for the symbol/date. Buy orders are sorted by rank (best price first). Orders are captured from JTrader throughout the trading day.

Get buy and sell order queues for every symbol on a given date. Same structure as the single-stock endpoint, but returns all symbols at once.

Parameters

Example

curl "https://stacksja.com/api/v1/public/orderbook?market=main" \
  -H "X-API-Key: pk_your_key"

Response

{
  "trade_date": "2026-03-12",
  "symbols": 116,
  "total_orders": 5703,
  "data": [
    {
      "symbol": "NCBFG",
      "market": "Main Market",
      "buy_orders": [ ... ],
      "sell_orders": [ ... ],
      "summary": {
        "buy_order_count": 113, "sell_order_count": 30,
        "total_buy_value": 23936561.9, "total_sell_value": 27246953.36,
        "buy_percentage": 46.8, "sell_percentage": 53.2
      }
    }
  ]
}

Response can be large (5,000+ orders across 100+ symbols). Use the market filter to reduce payload.

Historical order book snapshots showing how buy/sell pressure, spread, and sentiment have changed over time. Useful for tracking accumulation or distribution patterns.

Parameters

Example

curl "https://stacksja.com/api/v1/public/stock/NCBFG/orderbook/history" \
  -H "X-API-Key: pk_your_key"

Response

{
  "symbol": "NCBFG",
  "count": 6,
  "history": [
    {
      "trade_date": "2026-03-12",
      "buy_orders": 113,
      "sell_orders": 30,
      "total_buy_value": 23936561.9,
      "total_sell_value": 27246953.36,
      "buy_pct": 46.8,
      "sell_pct": 53.2,
      "best_bid": 44.9,
      "best_ask": 44.97,
      "spread_pct": 0.16,
      "imbalance_score": 0.107,
      "imbalance_label": "Balanced"
    }
  ]
}

Ordered most recent first. Imbalance labels: Strong Buy (>0.4), Bullish (>0.15), Balanced (-0.15 to 0.15), Bearish (<-0.15), Strong Sell (<-0.4).

Computed order book analysis: buy/sell pressure ratio, bid-ask spread, imbalance score, support/resistance levels, and depth data for charting.

Parameters

Example

curl "https://stacksja.com/api/v1/public/stock/NCBFG/orderbook/analysis" \
  -H "X-API-Key: pk_your_key"

Response

{
  "trade_date": "2026-03-12",
  "symbol": "NCBFG",
  "analysis": {
    "pressure": {
      "total_buy_value": 23936561.9,
      "total_sell_value": 27246953.36,
      "buy_pct": 46.8, "sell_pct": 53.2,
      "ratio": 0.88
    },
    "spread": {
      "best_bid": 44.9, "best_ask": 44.97,
      "spread": 0.07, "spread_pct": 0.16,
      "midpoint": 44.935
    },
    "queue_summary": {
      "buy_orders": 113, "sell_orders": 30,
      "total_buy_qty": 577643, "total_sell_qty": 466244,
      "avg_buy_size": 5112, "avg_sell_size": 15541
    },
    "imbalance": {
      "score": 0.107,
      "label": "Balanced"
    },
    "support": [
      { "price": 42.41, "qty": 107669, "value": 4566242.29, "orders": 2 }
    ],
    "resistance": [
      { "price": 94.99, "qty": 63295, "value": 6012392.05, "orders": 1 }
    ],
    "depth": {
      "buy": [{ "price": 44.9, "qty": 200, "value": 8980.0, "cumulative": 8980.0 }],
      "sell": [{ "price": 44.98, "qty": 99837, "value": 4490668.26, "cumulative": 4490668.26 }]
    }
  }
}

Support = top 5 buy price levels by value (where demand clusters). Resistance = top 5 sell price levels. Depth data includes cumulative values for building depth charts. Returns "analysis": null when no data exists.

Fundamentals

Financial statements (income statement, balance sheet, cash flow) extracted from JSE filings. Returns the most recent quarterly and annual reports with current and comparative period data.

Parameters

Example

curl "https://stacksja.com/api/v1/public/stock/GK/financials" \
  -H "X-API-Key: pk_your_key"

Response

{
  "symbol": "GK",
  "company_name": "GraceKennedy",
  "count": 4,
  "valuation": { ... },
  "financials": [
    {
      "fiscal_year": 2025,
      "period_type": "Q3",
      "statement_type": "unaudited",
      "currency": "JMD",
      "periods": {
        "current": {
          "revenue": 44872273000.0,
          "operating_profit": 2931590000.0,
          "net_income": 1967432000.0,
          "eps_basic": 1.89,
          "eps_diluted": 1.87,
          "total_assets": 258200606000.0,
          "total_equity": 94000000000.0,
          "total_liabilities": 164000000000.0,
          "cash_and_equivalents": 21711167000.0,
          "finance_costs": -522429000.0,
          "tax_expense": -870558000.0
        },
        "comparative": { /* same fields for prior year period */ }
      }
    }
  ]
}

Financial data is extracted from JSE filings using AI and verified. periods.comparative contains the same period from the prior year. Values are in the company's reporting currency (usually JMD).

Board of directors and key executives for a company.

Parameters

Example

curl "https://stacksja.com/api/v1/public/stock/GK/directors" \
  -H "X-API-Key: pk_your_key"

Response

{
  "symbol": "GK",
  "company_name": "GraceKennedy",
  "directors": [
    {
      "id": 1,
      "name": "Prof. Gordon V. Shirley",
      "title": "Chairman",
      "director_type": "chairman",
      "appointed_date": "",
      "bio": ""
    },
    {
      "id": 2,
      "name": "Frank James",
      "title": "Group CEO",
      "director_type": "executive"
    }
  ]
}

director_type values: chairman, executive, non-executive, independent.

JSE regulatory filings and documents for a company (annual reports, quarterly statements, etc.).

Parameters

Example

curl "https://stacksja.com/api/v1/public/stock/GK/documents" \
  -H "X-API-Key: pk_your_key"

Response

{
  "symbol": "GK",
  "company_name": "GraceKennedy",
  "count": 5,
  "documents": [
    {
      "id": 42,
      "title": "Q3 2025 Unaudited Financial Statements",
      "document_type": "financial_statement",
      "fiscal_year": 2025,
      "period_type": "Q3",
      "filing_date": "2025-11-15",
      "pdf_url": "/api/v1/public/documents/42/pdf"
    }
  ]
}

Use the pdf_url to download the original document. PDF downloads do not require authentication.

Download the PDF for a specific document. Returns the raw PDF file. No authentication required.

Parameters

Example

curl "https://stacksja.com/api/v1/public/documents/42/pdf" \
  -o statement.pdf

Returns Content-Type: application/pdf. This is the only endpoint that does not require an API key.

Update director information (title, bio, appointed date, etc.). Requires authentication.

Parameters

Request Body (JSON)

All fields are optional — only include the fields you want to update.

Dividends

List dividend declarations. Filter by upcoming dividends, year, or symbol.

Parameters

Example

curl "https://stacksja.com/api/v1/dividends?upcoming=true" \
  -H "X-API-Key: pk_your_key"

Response

{
  "total": 15,
  "dividends": [
    {
      "id": 7,
      "symbol": "KPREIT",
      "amount_per_share": 0.000566,
      "currency": "USD",
      "dividend_type": "interim",
      "declaration_date": "2026-02-24",
      "record_date": "2026-04-02",
      "ex_dividend_date": "2026-04-02",
      "payment_date": "2026-04-24",
      "notes": "Amended dividend of US$0.000566 per share.",
      "source_url": "https://www.jamstockex.com/..."
    }
  ]
}

dividend_type: interim, final, or special. currency: JMD or USD. Key dates: ex_dividend_date is when you must own the stock by, payment_date is when you get paid.

Get dividends within a date range, useful for building a dividend calendar.

Parameters

Example

curl "https://stacksja.com/api/v1/dividends/calendar?start_date=2026-03-01&end_date=2026-04-30" \
  -H "X-API-Key: pk_your_key"

Returns dividends that have any key date (declaration, record, ex-dividend, or payment) falling within the specified range.

Get all dividend history for a specific stock.

Parameters

Example

curl "https://stacksja.com/api/v1/stocks/NCBFG/dividends" \
  -H "X-API-Key: pk_your_key"

Response

{
  "symbol": "NCBFG",
  "dividends": [
    {
      "id": 11,
      "symbol": "NCBFG",
      "amount_per_share": 0.5,
      "currency": "JMD",
      "dividend_type": "interim",
      "declaration_date": "2026-02-12",
      "record_date": "2026-03-02",
      "ex_dividend_date": "2026-03-02",
      "payment_date": "2026-03-16",
      "notes": "Interim dividend of $0.50 per ordinary stock unit.",
      "source_url": "https://www.jamstockex.com/..."
    }
  ]
}

Reference

Error Codes

All errors return a JSON object with a detail field explaining the error.

Error Response Format

{
  "detail": "Stock 'FAKE' not found. Try /api/v1/public/quote?name=First+Rock for multi-word names."
}

Rate Limits

If you exceed the rate limit, you'll receive a 429 response. Wait 60 seconds before retrying. Need higher limits? Contact us.

Access your portfolios, alerts, watchlists, and chart notes from external apps, scripts, or AI tools.

Base URL: https://stacksja.com/api/v2/user

Create a personal token on the Developers page to get started.

Authentication

The User API uses personal access tokens (not API keys). Create one on the Developers page.

Include your token in the Authorization header:

curl "https://stacksja.com/api/v2/user/me" \
  -H "Authorization: Bearer stk_your_token_here"

Token format: stk_ followed by 64 hex characters. Tokens are hashed server-side — if you lose it, generate a new one.

Get your user profile.

curl "https://stacksja.com/api/v2/user/me" \
  -H "Authorization: Bearer stk_your_token"

Response

{
  "username": "gordon",
  "email": "gordon@example.com",
  "created_at": "2026-01-15T10:30:00"
}

Get all your portfolios with holdings enriched with current market data, gain/loss calculations, and day changes.

curl "https://stacksja.com/api/v2/user/portfolios" \
  -H "Authorization: Bearer stk_your_token"

Response

[
  {
    "id": 1,
    "name": "Long Term",
    "total_value": 125430.50,
    "total_invested": 98000.00,
    "total_gain": 27430.50,
    "total_gain_pct": 27.99,
    "holdings": [
      {
        "symbol": "GK",
        "shares": 500,
        "buy_price": 65.00,
        "current_price": 70.13,
        "market_value": 35065.00,
        "gain_loss": 2565.00,
        "gain_loss_pct": 7.89,
        "day_change_pct": -0.43
      }
    ]
  }
]

Use /portfolios/{id} to get a single portfolio by ID.

Get all your price alerts with their current status.

curl "https://stacksja.com/api/v2/user/alerts" \
  -H "Authorization: Bearer stk_your_token"

Response

{
  "alerts": [
    {
      "symbol": "LEARN",
      "condition": "above",
      "target_price": 0.30,
      "triggered": false
    }
  ]
}

Create alerts with POST /alerts (body: {symbol, condition, target_price}). Delete with DELETE /alerts/{id}.

Get your watchlists with current prices for each stock.

curl "https://stacksja.com/api/v2/user/watchlists" \
  -H "Authorization: Bearer stk_your_token"

Get your favorite/starred stocks with current market data.

curl "https://stacksja.com/api/v2/user/favorites" \
  -H "Authorization: Bearer stk_your_token"

Get all your chart annotations. Filter by symbol with /chart-notes/{symbol}.

curl "https://stacksja.com/api/v2/user/chart-notes" \
  -H "Authorization: Bearer stk_your_token"

{
  "notes": [
    {
      "symbol": "LEARN",
      "trade_date": "2026-03-09",
      "note": "Bought 500 shares",
      "color": "green"
    }
  ]
}

💡 What Can You Build?

Need an API key? Apply for free access