SAHMK
Developers API

SAHMK Python SDK Quick Start

Get started in minutes with the official SAHMK Python SDK. Install via pip, authenticate with your API key, and start fetching real-time Tadawul stock data with typed models and IDE autocompletion.

PythonSDKBeginner6 min read
PyPI version

1. Installation

Install the SAHMK Python SDK from PyPI:

bash
pip install -U sahmk

Requires Python 3.9 or above. The package includes both the Python client library and a sahmk CLI.

2. Authentication

You need a SAHMK API key. Get your free key by signing up here.

auth.py
from sahmk import SahmkClient

client = SahmkClient(api_key="your_api_key_here")

Or use an environment variable:

auth_env.py
import os
from sahmk import SahmkClient

client = SahmkClient(api_key=os.environ["SAHMK_API_KEY"])

3. Fetch Your First Stock Quote by Identifier

Get a quote for Aramco using any supported identifier. In this example we use the symbol 2222:

If you don't know the exact symbol, use client.companies(...) first to reduce invalid-symbol errors.

bash
# Simple search
results = client.companies(search="aramco")

# Market filter (NOMUC alias is accepted and normalized)
nomu = client.companies(search="marketing", market="NOMUC", limit=20, offset=0)
get_quote.py
from sahmk import SahmkClient

client = SahmkClient(api_key="your_api_key_here")

quote = client.quote("2222")

print(f"Company: {quote.name_en}")
print(f"Symbol:  {quote.symbol}")
print(f"Price:   {quote.price} SAR")
print(f"Change:  {quote.change} ({quote.change_percent}%)")
print(f"Volume:  {quote.volume:,}")
Example response
Company: Saudi Arabian Oil Co
Symbol:  2222
Price:   25.86 SAR
Change:  0.18 (0.7%)
Volume:  9,803,705

The SDK returns typed objects with attribute access. You get autocompletion in your IDE for every field.

Supported identifiers include symbol, Arabic company name, English name, and alias. Symbols remain fully supported.

If an identifier matches more than one company, resolve ambiguity by passing the exchange symbol directly.

Liquidity Data

Each quote includes money flow data — useful for tracking institutional buying pressure:

bash
quote = client.quote("2222")

if quote.liquidity:
    liq = quote.liquidity
    net = liq.net_value
    direction = "inflow" if net > 0 else "outflow"
    print(f"Net liquidity: {net:,.0f} SAR ({direction})")

Dict Access Still Works

If you prefer dictionary-style access, it works exactly as before:

bash
quote = client.quote("2222")

# Both styles work
print(quote.price)        # attribute access
print(quote["price"])     # dict access
print(quote.get("price")) # .get() with default

The .raw attribute gives you the original API response as a plain dict — useful for serialization or forwarding:

bash
import json
print(json.dumps(quote.raw, indent=2))

4. Batch Quotes (Multiple Stocks)

Fetch multiple stocks in a single request (Starter plan or higher):

batch_quotes.py
result = client.quotes(["2222", "الراجحي", "stc"])

print(f"Fetched {result.count} quotes\n")
for q in result.quotes:
    print(f"{q.symbol}: {q.name_en} — {q.price} SAR ({q.change_percent:+.2f}%)")
Example response
Fetched 3 quotes

2222: Saudi Arabian Oil Co — 25.86 SAR (+0.70%)
1120: Al Rajhi Banking & Investment Corp SJSC — 108.60 SAR (+0.18%)
4191: Maison Marketing Trade Group — 59.50 SAR (+8.97%)

The quotes() method accepts up to 50 identifiers and counts as a single API request.

5. Market Overview

market_overview.py
# TASI index summary
market = client.market_summary(index="TASI")
print(f"TASI: {market.index_value} ({market.index_change_percent:+.2f}%)")
print(f"Delayed Feed: {market.is_delayed}")
print(f"Advancing: {market.advancing} | Declining: {market.declining}")
print(f"Mood: {market.market_mood}")

# Top gainers
gainers = client.gainers(limit=3)
print("\nTop Gainers:")
for s in gainers.stocks:
    print(f"  {s.symbol}: {s.name_en} +{s.change_percent}%")

# Top losers
losers = client.losers(limit=3)
print("\nTop Losers:")
for s in losers.stocks:
    print(f"  {s.symbol}: {s.name_en} {s.change_percent}%")

Other market methods: client.volume_leaders(), client.value_leaders(), client.sectors().

6. Error Handling

The SDK provides structured errors you can catch and inspect:

errors.py
from sahmk import SahmkClient, SahmkError, SahmkRateLimitError

client = SahmkClient(api_key="your_api_key_here")

try:
    quote = client.quote("INVALID")
except SahmkRateLimitError as e:
    print(f"Rate limited. Try again later. ({e.status_code})")
except SahmkError as e:
    print(f"API error: {e} (code: {e.error_code}, status: {e.status_code})")

The SDK automatically retries on transient failures (429, 5xx) with exponential backoff. You can configure this:

bash
client = SahmkClient(
    api_key="your_api_key_here",
    retries=5,              # max retry attempts (default: 3)
    backoff_factor=0.5,     # backoff multiplier (default: 0.3)
    retry_on_timeout=True,  # retry on timeouts (default: True)
)

7. Next Steps

You now know the SDK basics. Here's what to explore next:

  • →Company info: client.company("2222") — fundamentals, technicals, valuation, analyst targets
  • →Financials: client.financials("2222") — income statements, balance sheets, cash flows (Starter+)
  • →Dividends: client.dividends("2222") — yield, payment history, upcoming distributions (Starter+)
  • →Events: client.events(symbol="2222") — AI-generated event summaries (Pro+)
  • →Historical: client.historical("2222") — OHLCV data with date ranges and intervals (Starter+)
  • →WebSocket: client.stream(["2222"], on_quote=callback) — real-time price streaming (Pro+)
  • →CLI: Run sahmk quote "Saudi Aramco" from your terminal — no code needed

Resources

SDK Source CodePyPI PackageAPI Reference

Ready to build?

Get your free API key and start building with the SAHMK Python SDK. 100 free requests per day, no credit card required.

Get Your Free API KeyView on GitHub