Halal API quickstart in 10 lines — Python & JavaScript SDKs

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 for unlimited.

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.