SAHMK
Developers API

API Documentation

Welcome to the SAHMK API. Real-time and historical Saudi stock market data for all 350+ companies on TASI and Nomu — complete reference for endpoints, authentication, streaming, and tools.

Getting Started

Create an account, get your API key, and make your first request. Then move from core REST endpoints to SDKs, automation, and real-time streaming as your product grows.

Start Here

First request

Get a live Saudi stock quote by symbol in minutes.

Build

Core API

Quotes, market data, company data, financials, and events.

Realtime Event Engine

Real-time workflow

Streaming, event webhooks, rules, history, and limits.

Quick Start

  1. Create a free account
  2. Get your API key from the dashboard
  3. Make your first API request
  4. Browse code examples on GitHub

Base URL

text
https://app.sahmk.sa/api/v1

Your First Request

curl -X GET "https://app.sahmk.sa/api/v1/quote/2222/" \
     -H "X-API-Key: YOUR_API_KEY"

Full examples available on GitHub →

Quote path uses a symbol. If you need name/alias resolution, pass it through the optional identifier query param.

Expected Response

json
{
  "symbol": "2222",
  "name_en": "Saudi Arabian Oil Co",
  "price": 25.86,
  "change_percent": 0.7,
  "volume": 9803705,
  "updated_at": "2026-02-10T12:19:22+00:00",
  "is_delayed": false
}

Success: You just fetched live Saudi market data from SAHMK. Next, use the SDK for faster integration, explore core endpoints, or move to WebSocket if you need streaming updates.

Ambiguity note: If an identifier maps to multiple companies, pass the exact exchange symbol to disambiguate.

Use the SDK

Start with Python SDK or CLI for less boilerplate.

Build with REST

Add quotes, market summaries, company data, and historicals.

Go real-time

Upgrade to streaming when polling is no longer enough.

Authentication

All API requests require authentication using an API key. Include your key in the X-API-Key header.

http
X-API-Key: YOUR_API_KEY

API key types:

  • shmk_live_* - Production keys
  • shmk_test_* - Test keys (same data, separate quota)
curl -X GET "https://app.sahmk.sa/api/v1/quote/2222/" \
     -H "X-API-Key: YOUR_API_KEY"

Python SDK & CLI

Start here if you want the fastest path from API key to working integration. The official SDK gives you a cleaner client, while the CLI is useful for testing, demos, and automated tooling.

bash
pip install -U sahmk
export SAHMK_API_KEY="your_api_key"
sahmk quote "Saudi Aramco"

Python SDK:

python
from sahmk import SahmkClient

client = SahmkClient(api_key="YOUR_API_KEY")

directory = client.companies(search="aramco", market="TASI", limit=20, offset=0)
symbol = directory["results"][0]["symbol"]

print(client.quote("أرامكو السعودية"))

If symbol input is uncertain, call client.companies(...) first to discover a valid symbol before quote/company calls.

Use this when: you want less boilerplate than raw REST, typed workflows in Python, or quick command-line access to quotes and market data.

Quote methods accept identifiers (symbol, Arabic/English name, alias). Use symbol when the identifier is ambiguous.

Full examples: github.com/sahmk-sa/sahmk-python • PyPI: pypi.org/project/sahmk

AI & Agents

Use SAHMK inside Claude Desktop, Cursor, and other MCP-compatible clients. For direct agent consumption, use the MCP server for tool calling and/api-docs.mdfor machine-readable API docs.

bash
pip install sahmk-mcp

Package: pypi.org/project/sahmk-mcp · MCP quick start tutorial

Related Tutorials

Connect SAHMK to Claude Desktop or Cursor via MCPUse SAHMK MCP with LM Studio and Local AI Models

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

json
{
  "mcpServers": {
    "sahmk": {
      "command": "sahmk-mcp",
      "env": {
        "SAHMK_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor

Add to your project's .cursor/mcp.json

json
{
  "mcpServers": {
    "sahmk": {
      "command": "sahmk-mcp",
      "env": {
        "SAHMK_API_KEY": "your_api_key_here"
      }
    }
  }
}

Use this when: your team wants SAHMK available inside AI workflows, research assistants, or agentic tools without building extra integration glue first.

Use companies_list for symbol discovery (`search`, `market`, `limit`, `offset`) before quote tools.

Stocks

Get real-time stock quotes and prices for individual or multiple companies.

GET /quote/{symbol}/

Free

Get current price and trading data for a single stock symbol.

Endpoint

https://app.sahmk.sa/api/v1/quote/2222/?identifier=أرامكو

Parameters

(*) Required

ParameterTypeExample
symbol *string2222
identifier stringأرامكو

Use symbol when identifier lookup is ambiguous.

Response

200 OKapplication/json
{
  "symbol": "2222",
  "name": "أرامكو السعودية",
  "name_en": "Saudi Arabian Oil Co",
  "price": 25.86,
  "change": 0.18,
  "change_percent": 0.7,
  "open": 25.6,
  "high": 25.86,
  "low": 25.6,
  "previous_close": 25.68,
  "volume": 9803705,
  "value": 252308343.0,
  "bid": 25.82,
  "ask": 25.86,
  "liquidity": {
    "inflow_value": 184950463.03,
    "inflow_volume": 7182468,
    "inflow_trades": 7261,
    "outflow_value": 67357881.91,
    "outflow_volume": 2621237,
    "outflow_trades": 5028,
    "net_value": 117592581.12
  },
  "updated_at": "2026-02-10T12:19:22+00:00",
  "is_delayed": false
}

Liquidity Fields:

  • inflow_value — Total SAR value of buy orders
  • outflow_value — Total SAR value of sell orders
  • net_value — Net liquidity (inflow - outflow)

GET /quotes/

Starter+

Get quotes for multiple companies in a single request. Requires Starter plan or higher.

Free tier fallback: GET /quote/{symbol}/ for single-company quotes.

Endpoint

https://app.sahmk.sa/api/v1/quotes/?symbols=2222,1120

Parameters

(*) Required

ParameterTypeExample
symbols *string2222,1120
identifiers stringأرامكو، الراجحي

Use either symbols or identifiers, not both.

Response

200 OKapplication/json
{
  "quotes": [
    {
      "symbol": "2222",
      "name": "أرامكو السعودية",
      "name_en": "Saudi Arabian Oil Co",
      "price": 25.86,
      "change": 0.18,
      "change_percent": 0.7,
      "high": 25.90,
      "low": 25.60,
      "volume": 9803705,
      "net_liquidity": 117592581.12,
      "updated_at": "2026-02-10T12:19:22+00:00",
      "is_delayed": false
    },
    {
      "symbol": "1120",
      "name": "الراجحي",
      "name_en": "Al Rajhi Banking & Investment Corp SJSC",
      "price": 108.6,
      "change": 0.2,
      "change_percent": 0.18,
      "high": 109.10,
      "low": 108.20,
      "volume": 4023570,
      "net_liquidity": 45230000.50,
      "updated_at": "2026-02-10T12:18:56+00:00",
      "is_delayed": false
    }
  ],
  "count": 2
}

Need symbols? Use GET /companies/

net_liquidity — Net money flow (buy value - sell value) in SAR.

Quick conventions: use path params for a single resource (for example /quote/{symbol}/) and query params for list filtering (for example /events/?symbol=2222&limit=20). Common HTTP/API errors are centralized in Error Codes.

Market

Get market-wide data including index values, top movers, and sector performance.

Market index query parameter:

  • index is optional on all market endpoints
  • Supported values: TASI, NOMU
  • Default when omitted: TASI
  • Existing URLs without index still work

GET /market/summary/?index=TASI

Free

Get market index value, volume, and market sentiment.

Endpoint

https://app.sahmk.sa/api/v1/market/summary/?index=TASI

Parameters

(*) Required

ParameterTypeExample
index stringTASI

Supported values: TASI, NOMU. Default is TASI.

Response

200 OKapplication/json
{
  "index": "TASI",
  "is_delayed": true,
  "timestamp": "2026-01-28T12:20:00+00:00",
  "index_value": 11458.11,
  "index_change": 76.28,
  "index_change_percent": 0.67,
  "total_volume": 279874553,
  "advancing": 117,
  "declining": 139,
  "unchanged": 14,
  "market_mood": "Bullish"
}

GET /market/gainers/?limit=10&index=TASI

Free

Get top gaining stocks by percentage change.

Endpoint

https://app.sahmk.sa/api/v1/market/gainers/?limit=10&index=TASI

Parameters

(*) Required

ParameterTypeExample
index stringTASI
limit number10

Response

200 OKapplication/json
{
  "index": "TASI",
  "is_delayed": true,
  "gainers": [
    {
      "symbol": "4194",
      "name": "مجموعة منزل التسويق للتجارة",
      "name_en": "Maison Marketing Trade Group",
      "price": 59.5,
      "change": 4.9,
      "change_percent": 8.97,
      "volume": 611349,
      "updated_at": "2026-01-28T12:19:50+00:00"
    }
  ],
  "count": 10
}

GET /market/losers/?limit=10&index=TASI

Free

Get top losing stocks by percentage change.

Endpoint

https://app.sahmk.sa/api/v1/market/losers/?limit=10&index=TASI

Parameters

(*) Required

ParameterTypeExample
index stringTASI
limit number10

Response

200 OKapplication/json
{
  "index": "TASI",
  "is_delayed": true,
  "losers": [
    {
      "symbol": "9639",
      "name": "شركة أنماط التقنية للتجارة",
      "name_en": "Anmat Technology Trading Co",
      "price": 8.2,
      "change": -0.8,
      "change_percent": -8.89,
      "volume": 9206,
      "updated_at": "2026-01-28T12:10:18+00:00"
    }
  ],
  "count": 10
}

GET /market/volume/?limit=10&index=TASI

Free

Get top stocks by trading volume.

Endpoint

https://app.sahmk.sa/api/v1/market/volume/?limit=10&index=TASI

Parameters

(*) Required

ParameterTypeExample
index stringTASI
limit number10

Response

200 OKapplication/json
{
  "index": "TASI",
  "is_delayed": true,
  "stocks": [
    {
      "symbol": "2222",
      "name": "أرامكو السعودية",
      "name_en": "Saudi Arabian Oil Co",
      "price": 25.64,
      "change": 0.38,
      "change_percent": 1.5,
      "volume": 15738067,
      "updated_at": "2026-01-28T12:19:48+00:00"
    }
  ],
  "count": 10
}

GET /market/value/?limit=10&index=TASI

Free

Get top stocks by trading value (SAR).

Endpoint

https://app.sahmk.sa/api/v1/market/value/?limit=10&index=TASI

Parameters

(*) Required

ParameterTypeExample
index stringTASI
limit number10

Response

200 OKapplication/json
{
  "index": "TASI",
  "is_delayed": true,
  "stocks": [
    {
      "symbol": "2222",
      "name": "أرامكو السعودية",
      "name_en": "Saudi Arabian Oil Co",
      "price": 25.64,
      "change": 0.38,
      "change_percent": 1.5,
      "volume": 15738067,
      "value": 402108076.72,
      "updated_at": "2026-01-28T12:19:48+00:00"
    }
  ],
  "count": 10
}

GET /market/sectors/?index=TASI

Free

Get sector performance and statistics.

Endpoint

https://app.sahmk.sa/api/v1/market/sectors/?index=TASI

Parameters

(*) Required

ParameterTypeExample
index stringTASI

Response

200 OKapplication/json
{
  "index": "TASI",
  "is_delayed": true,
  "sectors": [
    {
      "id": "TBNI",
      "name": "Banks",
      "change_percent": 0.45,
      "avg_change_percent": 0.38,
      "volume": 45027873,
      "num_stocks": 10
    }
  ],
  "count": 20
}
View Endpoint-Specific Error (invalid index)
json
{
  "error": {
    "code": "INVALID_INDEX",
    "message": "Invalid index 'XYZ'. Supported values: TASI, NOMU."
  }
}

Company / Symbol APIs

Discover valid symbols and fetch detailed company information.

GET /companies/

Free

Lightweight company directory for symbol discovery before calling quote or company endpoints.

Endpoint

https://app.sahmk.sa/api/v1/companies/?search=aramco&market=TASI&limit=20&offset=0

Parameters

(*) Required

ParameterTypeExample
search stringaramco
market stringTASI
limit number20
offset number0

Response

200 OKapplication/json
{
  "results": [
    {
      "symbol": "2222",
      "name_ar": "أرامكو السعودية",
      "name_en": "Saudi Arabian Oil Co",
      "market": "TASI",
      "status": "active"
    }
  ],
  "count": 1,
  "total": 590,
  "limit": 100,
  "offset": 0
}
View Errors
json
{
  "error": {
    "code": "INVALID_MARKET",
    "message": "market must be one of: TASI, NOMU."
  }
}

{
  "error": {
    "code": "INVALID_PARAM",
    "message": "limit and offset must be valid integers."
  }
}

GET /company/{symbol}/

Free

Get company information. Response varies by plan.

Data Available by Plan:

  • Free: Name, sector, industry, description, website
  • Starter: + Full fundamentals (PE, EPS, book value, beta, week/month/52w ranges)
  • Pro+: + Technicals, valuation, analyst consensus

is_delayed indicates pricing freshness: true for delayed prices (Free/Starter) and false for real-time prices (Pro/Business/Enterprise).

New: week_high/low, month_high/low — Price levels in last 7/30 days

Endpoint

https://app.sahmk.sa/api/v1/company/2222/

Parameters

(*) Required

ParameterTypeExample
symbol *string2222

Response

200 OKapplication/json
{
  "symbol": "2222",
  "name": "أرامكو السعودية",
  "name_en": "Saudi Arabian Oil Co",
  "current_price": 25.64,
  "is_delayed": false,
  "sector": "Energy",
  "industry": "Oil & Gas",
  "description": "Saudi Aramco is the world's largest oil producer...",
  "website": "https://www.aramco.com",
  "country": "Saudi Arabia",
  "currency": "SAR",
  
  "fundamentals": {
    "market_cap": 6258120000000,
    "pe_ratio": 16.77,
    "forward_pe": 15.48,
    "eps": 1.54,
    "book_value": 6.16,
    "price_to_book": 4.19,
    "beta": 0.104,
    "shares_outstanding": 242000000000,
    "float_shares": 5969578000,
    "week_high": 26.10,
    "week_low": 25.40,
    "month_high": 27.20,
    "month_low": 24.80,
    "fifty_two_week_high": 27.85,
    "fifty_two_week_low": 23.04
  },
  
  "technicals": {
    "rsi_14": 55.3,
    "macd_line": 0.12,
    "macd_signal": 0.08,
    "macd_histogram": 0.04,
    "fifty_day_average": 26.1,
    "technical_strength": 0.65,
    "price_direction": "bullish",
    "updated_at": "2026-01-28T10:00:00+03:00"
  },
  
  "valuation": {
    "fair_price": 28.50,
    "fair_price_confidence": 0.85,
    "calculated_at": "2026-01-28T10:00:00+03:00"
  },
  
  "analysts": {
    "target_mean": 29.5,
    "target_median": 29.0,
    "target_high": 35.0,
    "target_low": 24.0,
    "consensus": "buy",
    "consensus_score": 2.1,
    "num_analysts": 15
  }
}

Historical Data

Access historical OHLCV (Open, High, Low, Close, Volume) data for technical analysis and backtesting.

GET /historical/{symbol}/

Starter+

Get historical price data for a stock.

Endpoint

https://app.sahmk.sa/api/v1/historical/2222/?from=2026-01-01&to=2026-01-28&interval=1d

Parameters

(*) Required

ParameterTypeExample
symbol *string2222
from string2026-01-01
to string2026-01-28
interval string1d

from: default is 30 days ago. to: default is today. interval: 1d, 1w, 1m (default 1d; weekly/monthly are aggregated from daily candles).

Response

200 OKapplication/json
{
  "symbol": "2222",
  "interval": "1d",
  "from": "2026-01-01",
  "to": "2026-01-28",
  "count": 20,
  "data": [
    {
      "date": "2026-01-28",
      "open": 25.3,
      "high": 25.68,
      "low": 25.3,
      "close": 25.64,
      "volume": 15738067,
      "adjusted_close": 25.64,
      "turnover": 402108076.72
    }
  ]
}

Related Tutorials

Build a Saudi Stock Tracker in PythonBuild a Stock Research Tool with the SAHMK Python SDK

Financials

Access structured income statement, balance sheet, and cash flow data for Saudi listed companies.

GET /financials/{symbol}/

Starter+

Endpoint

https://app.sahmk.sa/api/v1/financials/1120/?period=annual&history=5y&metrics=extended

Parameters

(*) Required

ParameterTypeExample
symbol *string1120
type stringall
period stringquarterly
history string5y
metrics stringextended
result stringseries

type: income, balance, cashflow, all. period: annual, quarterly, auto. history: 1y, 3y, 5y, 10y, max. metrics: core, extended. result: series, latest. Optional flags: include_quality=1, include_future_placeholders=1, include_partial=1.

Behavior Notes

  • period=auto resolves to annual when the latest fiscal year is full-year, otherwise quarterly.
  • Annual history returns completed fiscal years by default; use include_partial=1 to include the current incomplete annual/YTD row.
  • Quarterly mode returns the latest available quarters by default.
  • result=latest follows the selected/resolved granularity; in annual mode it returns the latest completed year by default unless include_partial=1 is used.
  • API default remains period=annual for backward compatibility.
  • Statements are returned in arrays such as income_statements, balance_sheets, and cash_flows.
  • Responses also include context fields like symbol, statement_period, and optional quality when requested.

Data Available by Plan:

  • Starter: Annual + core + up to 3 completed fiscal years + latest snapshot
  • Pro+: Pro, Business, and Enterprise include quarterly + extended + 5Y/10Y/max + full views

Response Example

Response

200 OKapplication/json
{
  "symbol": "1120",
  "statement_period": "annual",
  "quality": {
    "coverage": "high",
    "warnings": []
  },
  "income_statements": [
    {
      "report_date": "2025-09-30",
      "total_revenue": 123456789.0,
      "net_income": 9876543.0
    }
  ]
}

Analytics

Compare and analyze company ratios with compact analytics endpoints.

Implementation note: Analytics responses include meta fields like period, metrics, and warnings. Ratio keys can vary by symbol/data coverage, so render keys dynamically.

GET /analytics/ratios/{symbol}/

Starter+

Financial ratios for one symbol.

Endpoint

https://app.sahmk.sa/api/v1/analytics/ratios/1120/?history=5y&period=quarterly&metrics=extended

Parameters

(*) Required

ParameterTypeExample
symbol *string1120
history string5y
period stringquarterly
metrics stringextended

history: latest, 3y, 5y, 10y, max (default latest). period: annual, quarterly (default annual). metrics: core, extended (default core). Plan limits: Free has no analytics access; Starter supports latest + annual + core only; Pro, Business, and Enterprise unlock all ratios options.

Response

200 OKapplication/json
{
  "symbol": "1120",
  "ratios": [
    {
      "report_date": "2025-12-31",
      "statement_period": "annual",
      "fiscal_year": 2025,
      "fiscal_quarter": null,
      "ratios": {
        "roe": 9.77,
        "roa": 3.89,
        "net_margin": 19.09,
        "debt_to_equity": 0.6,
        "revenue_growth_yoy": 10.0,
        "net_income_growth_yoy": 16.67
      },
      "key_metrics": {
        "total_revenue": 1100.0,
        "operating_income": 250.0,
        "net_income": 210.0,
        "operating_cash_flow": 280.0,
        "total_assets": 5400.0,
        "stockholders_equity": 2150.0,
        "total_debt": 1300.0
      }
    }
  ],
  "meta": {
    "period": "annual",
    "metrics": "core",
    "warnings": []
  }
}

GET /analytics/compare/

Starter+

Compare ratio snapshots across multiple symbols.

Endpoint

https://app.sahmk.sa/api/v1/analytics/compare/?symbols=1120,1180,1010,2222&metrics=extended

Parameters

(*) Required

ParameterTypeExample
symbols *string1120,1180,1010,2222
metrics stringextended

symbols is required as comma-separated values (example 1120,1180,1010). metrics: core or extended (default core). Plan limits: Starter supports up to 3 symbols and core only; Pro supports up to 10 symbols; Business and Enterprise support up to 20 symbols, and all three support extended.

Response

200 OKapplication/json
{
  "results": [
    {
      "symbol": "1120",
      "company_name": "الراجحي",
      "sector": "Financial Services",
      "market_cap": 1000001120.0,
      "current_price": 89.4,
      "coverage": "high",
      "ratios": {
        "roe": 9.77,
        "roa": 3.89,
        "net_margin": 19.09,
        "debt_to_equity": 0.6,
        "revenue_growth_yoy": 10.0,
        "net_income_growth_yoy": 16.67,
        "asset_turnover": 0.2037,
        "debt_ratio": 0.2407
      },
      "key_metrics": {
        "total_revenue": 1100.0,
        "operating_income": 250.0,
        "net_income": 210.0,
        "operating_cash_flow": 280.0,
        "total_assets": 5400.0,
        "stockholders_equity": 2150.0,
        "total_debt": 1300.0
      }
    }
  ],
  "count": 1,
  "meta": {
    "period": "annual",
    "metrics": "extended",
    "warnings": []
  }
}

Dividends

Get dividend history, upcoming distributions, and trailing yield for a stock.

GET /dividends/{symbol}/

Starter+

Get dividend history and yield information.

Endpoint

https://app.sahmk.sa/api/v1/dividends/2222/?limit=10

Parameters

(*) Required

ParameterTypeExample
symbol *string2222
limit number10

Response

200 OKapplication/json
{
  "symbol": "2222",
  "current_price": 25.64,
  "trailing_12m_yield": 4.2,
  "trailing_12m_dividends": 1.60,
  "payments_last_year": 4,
  "upcoming": [
    {
      "value": 0.40,
      "period": "Q4",
      "eligibility_date": "2026-03-15",
      "distribution_date": "2026-04-01"
    }
  ],
  "history": [
    {
      "value": 0.40,
      "value_percent": 1.5,
      "period": "Q3",
      "fiscal_year": 2025,
      "announcement_date": "2025-09-01",
      "eligibility_date": "2025-09-15",
      "distribution_date": "2025-10-01"
    }
  ]
}

Related Tutorials

Build a Stock Research Tool with the SAHMK Python SDKBuild a Saudi Stock Tracker in Python

Stock Events

Get AI-generated summaries of significant stock events and news.

GET /events/

Pro+

Get stock events with AI-generated analysis.

Note: Event types are UPPERCASE (e.g., FINANCIAL_REPORT, DIVIDEND_ANNOUNCEMENT).

Endpoint

https://app.sahmk.sa/api/v1/events/?symbol=4190&importance=IMPORTANT&limit=20

Parameters

(*) Required

ParameterTypeExample
symbol string4190
type stringFINANCIAL_REPORT
importance stringIMPORTANT
limit number20

Response

200 OKapplication/json
{
  "events": [
    {
      "symbol": "4190",
      "stock_name": "جرير للتسويق",
      "event_type": "FINANCIAL_REPORT",
      "importance": "important",
      "sentiment": "positive",
      "description": "شركة جرير للتسويق تعلن عن نتائج مالية قياسية للربع الرابع 2025...",
      "event_date": "2026-01-29",
      "article_date": "2026-01-29T17:10:06+00:00",
      "created_at": "2026-01-29T17:10:12+00:00"
    }
  ],
  "count": 1,
  "available_types": [
    "FINANCIAL_REPORT", "DIVIDEND_ANNOUNCEMENT", "STOCK_SPLIT",
    "MERGER_ACQUISITION", "MANAGEMENT_CHANGE", "NEW_LISTING",
    "REGULATORY_ACTION", "PARTNERSHIP", "MARKET_EXPANSION",
    "RESTRUCTURING", "EARNINGS_SURPRISE", "OTHER"
  ]
}

Related Tutorials

Build a Stock Research Tool with the SAHMK Python SDKConnect SAHMK to Claude Desktop or Cursor via MCP

available_types: Server-defined list that may expand in future releases.

importance: critical, important, regular

sentiment: very_positive, positive, slightly_positive, neutral, slightly_negative, negative, very_negative

Realtime Event Engine

Operational Event Engine docs are now organized into dedicated pages for better depth and navigation.

Use the focused Realtime Event Engine docs for payload contracts, lifecycle, signature verification, and production best practices.

Open Realtime Event Engine docs

Related Tutorials

Build a Real-Time Tadawul Stream with SAHMK WebSocket

Overview

WebSocket Streaming

Event Webhooks

Payload Reference

Event Rules

Event Types & Conditions

Delivery Lifecycle

Signature Verification

Event History

Error Codes

Rate Limits

API access is rate-limited based on your subscription plan. There are two types of limits: daily quotas and per-minute burst limits.

Full Plan Comparison

PlanDaily LimitBurst LimitAPI KeysWebSocketEvent WebhooksEvent Rules
Free100/day10/min1✗00
Starter5,000/day100/min3✗00
Pro50,000/day500/min10✓310
Business150,000/day1,000/min30✓1050
EnterpriseCustomCustomCustom✓CustomCustom

Burst Protection: To prevent abuse and protect stability, per-minute throttling is applied at both API-key and account levels. Requests exceeding these limits return HTTP 429. Daily limits reset at midnight (UTC+3). Enterprise limits are contract-based and may be monthly quotas or resource-based.

Rate Limit Headers

Each response includes headers to help track your usage:

http
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 1769816400

X-RateLimit-Reset is a Unix timestamp (seconds).

Error Codes

The API uses standard HTTP status codes and returns structured JSON error responses.

400INVALID_ROUTE

Wrong endpoint path was used. The API returns a suggested correct route.

401INVALID_API_KEY

API key is missing, invalid, or revoked.

403PLAN_LIMIT

Endpoint requires a higher plan (e.g., historical data requires Starter+, or higher-tier financials combinations are requested on Starter).

404INVALID_SYMBOL

Company identifier not resolved in TASI or Nomu. Use the exchange symbol when ambiguous.

429RATE_LIMIT

Daily quota or per-minute burst limit exceeded.

500SERVER_ERROR

Internal server error. Please retry or contact support.

Some new free accounts may temporarily hit a security limit. If this happens, the API may return HTTP 429 with error code TEMP_SECURITY_LIMIT. User action: try again later or upgrade for higher limits.

Common integration error: Calling GET /api/v1/quote/batch/ returns 400 INVALID_ROUTE with route guidance.

json
{
  "error": {
    "code": "INVALID_ROUTE",
    "message": "Did you mean /api/v1/quotes/?symbols=2222,1120 ?"
  }
}

Error Response Format

json
{
  "error": {
    "code": "RATE_LIMIT",
    "message": "Daily request limit exceeded. Resets at midnight UTC+3."
  }
}

Market Data Usage

SAHMK market data may be used within your applications, tools, or products.

Developer plans are intended for development, internal tools, and small-scale applications.

Large-scale public market data platforms, commercial display services, or data redistribution may require an enterprise agreement.

Reselling market data or providing it as a standalone API or data feed is not permitted without a separate agreement with SAHMK.

Need More Help?

Check the machine-readable docs at /api-docs.md, browse examples on GitHub, or contact our team.

GitHub