DEV Community: Yassir

Build a Halal Stock Screener with Python

Yassir — Fri, 31 Jul 2026 17:31:47 +0000

What We're Building

By the end of this tutorial, you'll have a Python script that can:

Screen any stock for Shariah compliance across 5 methodologies
Bulk-screen an entire index (S&P 500, NASDAQ 100, etc.)
Scan a portfolio and calculate aggregate compliance
Pull dividend purification data
Export everything to CSV

Total code: ~80 lines. Total time: ~15 minutes.

Prerequisites

Python 3.8+
requests library (pip install requests)
A free Halal Terminal API key (we'll generate one in Step 1)

Step 1: Get an API Key

First, generate a free API key. No credit card required -- the free tier includes 500 tokens/month:

import requests

BASE_URL = "https://api.halalterminal.com"

# Generate a free API key
resp = requests.post(f"{BASE_URL}/api/keys/generate", json={
    "email": "dev@example.com"
})
data = resp.json()
API_KEY = data["api_key"]
print(f"Your API key: {API_KEY}")
print(f"Plan: {data['plan']}, Tokens: {data['requests_limit']}")

Save your API key -- you'll use it in every subsequent request via the X-API-Key header.

Step 2: Screen a Single Stock

The /api/screen endpoint is the core of the API. It returns compliance status for all five Shariah screening methodologies in a single call:

headers = {"X-API-Key": API_KEY}

def screen_stock(symbol):
    """Screen a stock for Shariah compliance."""
    resp = requests.get(
        f"{BASE_URL}/api/screen",
        params={"symbol": symbol},
        headers=headers,
    )
    resp.raise_for_status()
    return resp.json()

# Screen Apple
result = screen_stock("AAPL")
print(f"{result['symbol']}: {result['overall_status']}")
for method, status in result["methodologies"].items():
    print(f"  {method}: {status}")
print(f"  Purification rate: {result['purification_rate']}%")

Output:

AAPL: COMPLIANT
  AAOIFI: COMPLIANT
  DJIM: COMPLIANT
  FTSE: COMPLIANT
  MSCI: COMPLIANT
  SP: COMPLIANT
  Purification rate: 0.42%

Token Costs

Each API endpoint costs a specific number of tokens. Single stock screening costs 5 tokens , so with the free plan's 500 tokens, you can screen 100 stocks per month. Upgrade to Starter ($19/mo) for 2,500 tokens or Pro ($49/mo) for 15,000 tokens. See the full cost table at /api/keys/token-costs.

Step 3: Bulk Screen an Entire Index

The /api/screen-bulk endpoint lets you screen an entire index asynchronously. Submit a list of symbols and get results for all of them:

def bulk_screen(symbols):

    """Screen multiple stocks at once."""

    resp = requests.post(

        f"{BASE_URL}/api/screen-bulk",

        json={"symbols": symbols},

        headers=headers,

    )

    resp.raise_for_status()

    return resp.json()

  
  
  Screen the FAANG stocks


faang = ["AAPL", "AMZN", "GOOGL", "META", "NFLX"]

results = bulk_screen(faang)

print(f"\nBulk screening results ({len(results['results'])} stocks):")

for stock in results["results"]:

    status = stock["overall_status"]

    emoji = "PASS" if status == "COMPLIANT" else "FAIL"

    print(f"  [{emoji}] {stock['symbol']}: {status}")

Step 4: Portfolio Compliance Scanner

The /api/portfolio/scan endpoint takes your actual holdings (with share counts) and returns per-stock compliance plus aggregate portfolio metrics:

def scan_portfolio(holdings):

    """Scan a portfolio for Shariah compliance."""

    resp = requests.post(

        f"{BASE_URL}/api/portfolio/scan",

        json={"holdings": holdings},

        headers=headers,

    )

    resp.raise_for_status()

    return resp.json()

  
  
  Define your portfolio


my_portfolio = [

    {"symbol": "AAPL", "shares": 50},

    {"symbol": "MSFT", "shares": 30},

    {"symbol": "GOOGL", "shares": 20},

    {"symbol": "JPM", "shares": 15},   # Bank - likely non-compliant

    {"symbol": "NVDA", "shares": 25},

]

portfolio = scan_portfolio(my_portfolio)

print(f"\nPortfolio Compliance Report")

print(f"{'='*40}")

print(f"Compliant holdings: {portfolio['compliant_count']}/{portfolio['total_count']}")

print(f"Compliance rate: {portfolio['compliance_rate']}%")

print(f"Portfolio purification rate: {portfolio['purification_rate']}%")

print(f"\nPer-stock breakdown:")

for stock in portfolio["holdings"]:

    status = stock["overall_status"]

    print(f"  {stock['symbol']:6s} {status}")

Step 5: Add Dividend Purification Data

For compliant holdings that pay dividends, fetch the purification details:

def get_purification(symbol):

    """Get dividend purification data for a stock."""

    resp = requests.get(

        f"{BASE_URL}/api/dividends/{symbol}/purification",

        headers=headers,

    )

    resp.raise_for_status()

    return resp.json()

  
  
  Get purification data for dividend-paying holdings


for holding in my_portfolio:

    symbol = holding["symbol"]

    try:

        purification = get_purification(symbol)

        rate = purification["purification_rate"]

        print(f"{symbol}: purification rate = {rate}%")

    except requests.HTTPError:

        print(f"{symbol}: no purification data available")

Step 6: Export Results to CSV

Finally, let's export everything into a clean CSV report:

import csv

def export_to_csv(portfolio_data, filename="shariah_report.csv"):

    """Export portfolio screening results to CSV."""

    with open(filename, "w", newline="") as f:

        writer = csv.writer(f)

        writer.writerow([

            "Symbol", "Status", "AAOIFI", "DJIM", "FTSE",

            "MSCI", "SP", "Purification Rate"

        ])

        for stock in portfolio_data["holdings"]:

            methods = stock.get("methodologies", {})

            writer.writerow([

                stock["symbol"],

                stock["overall_status"],

                methods.get("AAOIFI", "N/A"),

                methods.get("DJIM", "N/A"),

                methods.get("FTSE", "N/A"),

                methods.get("MSCI", "N/A"),

                methods.get("SP", "N/A"),

                stock.get("purification_rate", "N/A"),

            ])

    print(f"Report saved to {filename}")

export_to_csv(portfolio)

Endpoint Reference

Endpoint	Method	Tokens	Description
`/api/screen`	GET	5	Screen a single stock
`/api/screen-bulk`	POST	50	Bulk screen multiple stocks
`/api/portfolio/scan`	POST	25	Scan portfolio compliance
`/api/dividends/{symbol}/purification`	GET	2	Get purification data
`/api/etf/{symbol}/screening`	GET	10	Screen ETF holdings
`/api/quote/{symbol}`	GET	2	Get stock quote
`/api/zakat/calculate`	POST	5	Calculate zakat on portfolio
`/api/database/search`	GET	1	Search stock database

Build with Halal Terminal

Halal Terminal API

58+ endpoints, 5 screening methodologies, ETF analysis, zakat calculators, and MCP tools. Free tier available.

Explore the API -> Try the Terminal instead

Next Steps

You now have a working Shariah stock screener in Python. Here are some ideas to extend it:

Build a web dashboard -- Use Flask or FastAPI to create a web UI for your screener
Add scheduling -- Run portfolio compliance checks daily or weekly using cron
Integrate with your broker -- Pull holdings from Interactive Brokers, Alpaca, or Wealthsimple and auto-screen
Build alerts -- Notify when a holding's compliance status changes
Add zakat tracking -- Use the /api/zakat/calculate endpoint to track your annual obligation

For the full API reference with all 58+ endpoints, visit the Swagger documentation.

Important Disclaimer

Not financial advice. The information provided on this page is for educational and informational purposes only and should not be construed as financial advice, investment advice, trading advice, or any other type of advice. You should not make any financial decisions based solely on the information presented here.

Not a fatwa. Shariah compliance screening results are generated using automated data analysis based on publicly available financial data. These results do not constitute a religious ruling (fatwa) and should not be treated as one. Always consult a qualified Islamic scholar or Shariah advisor for guidance specific to your situation.

Do your own research. Past performance and current compliance status do not guarantee future results or continued compliance. Screening data may contain errors or become outdated. Always verify information independently and consult with a qualified financial advisor before making any investment decisions.

Originally published on the Halal Terminal blog.

Halal API quickstart in 10 lines — Python & JavaScript SDKs

Yassir — Fri, 31 Jul 2026 17:26:04 +0000

Today we're shipping two official SDKs for the Halal Terminal API: halalterminal on PyPI and @halalterminal/sdk on npm. Same surface in both languages: typed screening responses, a typed disclaimers array on every relevant call, granular error classes, and a generic GET/POST escape hatch for the long tail of endpoints.

If you've been hitting curl https://api.halalterminal.com from a script, this is the upgrade path. If you're new: this is the fastest way to ship a Shariah-aware feature into your app.

10 lines that screen a stock

Python:

pip install halalterminal


from halalterminal import Client

ht = Client(api_key="ht_…")               # or set HALAL_TERMINAL_API_KEY

aapl = ht.screen("AAPL")
print(aapl.is_compliant, aapl.compliance_explanation)

for d in aapl.disclaimers:                # render these inline in your UI
    print(f"[{d.severity}] {d.text}")

TypeScript / JavaScript:

npm install @halalterminal/sdk


import { HalalTerminal } from "@halalterminal/sdk";

const ht = new HalalTerminal({ apiKey: process.env.HALAL_TERMINAL_API_KEY });

const aapl = await ht.screen("AAPL");
console.log(aapl.is_compliant, aapl.compliance_explanation);

for (const d of aapl.disclaimers) {
  console.log(`[${d.severity}] ${d.text}`);
}

That's it. Both calls return the same shape, audited against the 5 published Shariah methodologies (AAOIFI, DJIM, FTSE, MSCI, S&P) -- with DJIM and S&P now using their spec-required 24-month and 36-month trailing-average market cap, not spot MC. Every per-methodology entry carries a verified: true audit flag.

Need a key? It's free.

Generate one with a single POST -- no credit card, no waiting list:

curl -X POST https://api.halalterminal.com/api/keys/generate \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

The free tier ships 500 tokens / month. Screening a single stock costs ~5 tokens; checking compliance on a portfolio of 10 names costs ~15. Upgrade to Starter ($19/mo) for 2,500 tokens, Pro ($49/mo) for 15,000 plus webhooks, or Enterprise ($199/mo) for 50,000 with $0.005/token overage.

What both SDKs ship with

Typed screening responses. ScreeningResult has is_compliant, shariah_compliance_status, purification_rate, by_methodology, and a plain-English compliance_explanation. Forward-compatible: unknown server fields stay on the raw object so the SDK never crashes on new API additions.
Typed disclaimers. Every relevant response carries a disclaimers array. Each entry has a stable id, an ISO version, a severity (religious for fatwa caveats, data for freshness / sourcing), and a url that deep-links to the right section on the legal page. Render them inline -- the API ships your compliance copy for you.
Granular errors. ApiKeyError / NotFoundError / RateLimitError / QuotaExceededError / ServerError. Catch the ones you care about (typically QuotaExceededError to trigger an upgrade flow); everything else falls through to HalalTerminalError.
Escape hatch. The SDKs wrap the most-used endpoints; for the long tail, ht.get("/api/...") and ht.post("/api/...", body) return parsed JSON.
Zero ceremony. Python: one runtime dep (requests). JS: zero deps, uses the platform's fetch. Both work in serverless / edge runtimes.

A more involved example: zakat at the end of the year

Computing zakat on a stock portfolio is a common one-time task. Here's the whole thing in Python:

from halalterminal import Client

ht = Client()  # uses HALAL_TERMINAL_API_KEY env var

z = ht.calculate_zakat([
    {"symbol": "AAPL", "market_value": 25_000},
    {"symbol": "MSFT", "market_value": 18_000},
    {"symbol": "GOOGL", "market_value": 12_000},
])

if z.is_above_nisab:
    print(f"You owe ${z.total_zakat:,.2f} in zakat on ${z.total_market_value:,.2f} of holdings.")
else:
    print(f"Below the nisab threshold (${z.nisab_threshold:,.2f}); no zakat owed this year.")

for d in z.disclaimers:
    print(f"-- {d.text}")

The zakat disclaimer ships with the response -- it names exactly what the simplified calculation excludes (the silver-nisab alternative, the hawl requirement, business-inventory rules, liability deductions) so you can surface it to the user without writing your own.

Portfolio scan in TypeScript

import { HalalTerminal } from "@halalterminal/sdk";

const ht = new HalalTerminal();

const scan = await ht.scanPortfolio(["AAPL", "MSFT", "JNJ", "BAC", "JPM"]);

console.log(

  ${scan.summary.compliant} compliant, ${scan.summary.non_compliant} non-compliant out of ${scan.summary.total}.,

);

// Per-symbol detail is on scan.results

for (const r of scan.results) {

  console.log(r.symbol, r.is_compliant);

}

Why we built typed disclaimers in

Most halal-data APIs make you assemble "not a fatwa" copy yourself, hand it to legal review, and bolt it onto your UI as a static string. That copy then drifts: scholars update their guidance, the methodology gains a caveat, the upstream data source adds a delay disclosure -- and your bolt-on copy is two quarters stale.

The Halal Terminal API attaches the disclaimer to the response. The SDKs unpack it as a typed object. When the registry advances (the version field is an ISO date), you can detect the change and re-prompt the user to acknowledge. severity lets you visually group the fatwa caveats separately from the data-freshness ones. url deep-links to the long-form text so you don't have to host your own.

For a regulated-fintech buyer, this is what compliance review actually asks for. For a solo dev, it's one less file to maintain.

The escape hatch in action

The API surfaces 60+ endpoints; the SDK wraps the dozen most-used. Anything else:

# Python

trending = ht.get("/api/trending")

report   = ht.post("/api/reports/portfolio", json={"symbols": ["AAPL", "MSFT"]})

// TypeScript

const trending = await ht.get>("/api/trending");

const report   = await ht.post("/api/reports/portfolio", { symbols: ["AAPL", "MSFT"] });

What's next on the SDK roadmap

Async Python client (AsyncClient on top of httpx) for FastAPI / asyncio users.
Streaming endpoints (bulk-screen progress) once the server side exposes SSE.
Type-safe response models for ETF look-through, dividend purification, and news.
Optional automatic retry-with-backoff on 5xx / network errors.

If you want to vote on what lands first, or you've hit a rough edge, the SDKs are open-source: github.com/goww7/FinanceData2/tree/main/sdks. PRs welcome.

Build with Halal Terminal

Halal Terminal API

58+ endpoints. 5 verified Shariah methodologies. Inline disclaimers shipped on every response. Free tier with 500 tokens/month.

Get a free API key -> Browse the full API docs

Important Disclaimer

Not financial advice. The information presented here is for developer education and informational purposes only. Nothing on this page constitutes financial advice, investment advice, or a recommendation to buy or sell any security.

Not a fatwa. The compliance verdicts returned by the Halal Terminal API are produced by automated screening of public financial filings against the 5 published methodologies. They are not a scholarly attestation or religious ruling. Consult a qualified Islamic scholar for personal religious decisions.

Do your own diligence. Past compliance does not guarantee future compliance. Data may be delayed, restated, or contain errors. Verify before acting.

Originally published on the Halal Terminal blog.

Connect Claude to Shariah Stock Screening in 5 Minutes (MCP)

Yassir — Fri, 31 Jul 2026 17:25:59 +0000

The Model Context Protocol (MCP) lets an AI client call external tools directly. Connect the Halal Terminal MCP server and your assistant can screen any stock or ETF for Shariah compliance in plain language, no copy-pasting tickers into a dashboard. This guide gets you from zero to a working setup in about five minutes.

What you get

Once connected, you can ask questions like "Is AAPL halal?" or "Audit this portfolio: AAPL, MSFT, GOOGL" straight inside Claude Desktop, Claude Code, Cursor, or any other MCP client (Windsurf, Cline, Continue, Zed, Goose). The assistant picks the right tool, calls the API, and answers with real data.

The server exposes 22 tools across eight categories: stock and ETF screening across 5 methodologies (AAOIFI, DJIM, FTSE, MSCI, S&P), bulk index screens, live quotes and price history, ETF holdings analysis, portfolio and watchlist scans, dividend and zakat calculators, news and SEC filings, plus report and education helpers. Every verdict is a methodology-based screen, not a fatwa.

Step 1: Get a free API key

Sign up at api.halalterminal.com. It is email-only, no credit card, and the key lands in your inbox in seconds. The free tier includes 500 tokens per month , which is plenty to evaluate the server before upgrading. Your key looks like ht_yourkey. Keep it handy for the next step.

Step 2: Connect your client

The fastest transport is the hosted SSE endpoint. For clients that need a local bridge, the @halalterminal/mcp package wraps it as stdio, and needs no install thanks to npx:

# Recommended - no install needed
npx -y @halalterminal/mcp

# Or pin globally
npm install -g @halalterminal/mcp

Claude Desktop

Open Settings, go to Developer, edit the config file, and add the server. Swap in your own key, then restart Claude Desktop:

{
  "mcpServers": {
    "halalterminal": {
      "command": "npx",
      "args": ["-y", "@halalterminal/mcp"],
      "env": { "HALALTERMINAL_API_KEY": "ht_yourkey" }
    }
  }
}

Claude Code

One command from your terminal registers the hosted server over SSE:

claude mcp add --transport sse halalterminal \
  https://mcp.halalterminal.com/sse \
  --header "X-API-Key: ht_yourkey"

Cursor, Windsurf, or any direct SSE client

Point the client at the SSE URL with your key as a query parameter:

https://mcp.halalterminal.com/sse?api_key=ht_yourkey

That is it. The client discovers all 22 tools automatically. Auth is either the X-API-Key header or the ?api_key= query parameter, whichever your client supports.

Step 3: Ask your first questions

Type these as normal chat messages. The assistant maps each one to a tool and returns live results.

"Is AAPL halal?" calls screen_stock and returns a verdict under each of the 5 methodologies side by side. On our live screen at publication, Apple came back compliant across all five (AAOIFI, DJIM, FTSE, MSCI, and S&P). Verdicts move with the financials, so always trust the fresh result over any snapshot.
"Scan this portfolio: AAPL, MSFT, GOOGL" calls scan_portfolio and returns a per-holding verdict plus an overall compliant percentage for the basket.
"Calculate zakat on my holdings" calls calculate_zakat, applying 2.5% against a live nisab threshold once you give it your positions.
"Compare SPUS vs HLAL" calls compare_etfs and lines up the two funds on compliant percentage, holdings, and aggregate purification rate so you can judge which fits your standard.
"What is dividend purification for this stock?" calls get_dividends with purification enabled, computing the non-compliant fraction to donate.

Because the assistant reads the structured response, it can chain calls too: screen a stock, then pull its recent news and SEC filings in the same conversation.

Token costs

The API is token-metered, not request-metered. Typical calls cost roughly 1 to 5 tokens : a full stock screen is 5 tokens, so the free plan's 500 tokens covers about 100 screenings per month. Lighter reads like a quote or a search cost less. You can see the full per-endpoint table at /api/keys/token-costs, and check your remaining balance any time from the dashboard.

Build with Halal Terminal

Halal Terminal API

22 MCP tools, 5 screening methodologies, ETF holdings analysis, and zakat calculators. Free tier, no credit card.

Get your free API key -> Explore the API

Where to go next

Official MCP registry: find the server listed at registry.modelcontextprotocol.io.
GitHub repo: setup guides for every client, the full tool reference, and issue tracker at github.com/goww7/halalterminal-mcp.
API docs: the interactive reference lives at api.halalterminal.com/api-reference.

Five minutes in, your AI client speaks Shariah screening. Get your key at api.halalterminal.com and ask it something.

Important Disclaimer

Originally published on the Halal Terminal blog.