SAHMK
PythonSDKBeginner6 min read

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.

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

Get a quote for Aramco (symbol: 2222):

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:,}")
Output
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.

Liquidity Data

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

python
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:

python
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:

python
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", "1120", "4191"])

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}%)")
Output
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 symbols and counts as a single API request.

5. Market Overview

market_overview.py
# TASI index summary
market = client.market_summary()
print(f"TASI: {market.index_value} ({market.index_change_percent:+.2f}%)")
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:

python
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 2222 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