DEV Community

Yassir
Yassir

Posted on • Originally published at halalterminal.com

Halal API quickstart in 10 lines — Python & JavaScript SDKs

#api #python #javascript #tutorial

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}")
Enter fullscreen mode Exit fullscreen mode

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}`);
}
Enter fullscreen mode Exit fullscreen mode

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"}'
Enter fullscreen mode Exit fullscreen mode

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}")
Enter fullscreen mode Exit fullscreen mode

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);

}
Enter fullscreen mode Exit fullscreen mode




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"] });
Enter fullscreen mode Exit fullscreen mode




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.

Top comments (0)