Financial data + Sharia compliance in one API.

Quickstart — 3 steps

From zero to a compliance verdict in a couple of minutes.

curl https://halalstock.net/v1/stock/2222.SR/halal?profile=standard \
  -H "Authorization: Bearer thl_your_key"

{
  "symbol": "2222.SR",
  "name": "Saudi Arabian Oil Company",
  "status": "halal",
  "compliance_score": 82,
  "confidence": "likely",
  "corroborated_by": [],         // Sharia-screened funds that also hold it (independent scholar check) — not data sources
  "ratios": [
    {"name": "debt_ratio", "value": 0.09, "threshold": 0.30, "passed": true},
    {"name": "cash_ratio", "value": 0.04, "threshold": 0.30, "passed": true},
    {"name": "impure_income_ratio", "value": null, "threshold": 0.05, "passed": null}
  ],
  "risk_level": "safe",
  "purification_pct": null,
  "reasons": ["Business is permissible and all computable financial ratios pass."],
  "explanation": {"en": "...", "ar": "..."},
  "disclaimer": "Screening analysis for information only — not a fatwa..."
}

Try it live

Type a ticker and run a real screen against the public endpoint — no key, no signup. This is the same JSON your code will get back.

SDKs & copy-paste examples

Official zero-dependency clients for Python and JavaScript, plus a raw curl call and the MCP config. Set your key once as HALALSTOCK_API_KEY (it starts with thl_).

import os
from halalstock import HalalStock, HalalStockError

# key from your account (starts with thl_); keyless works too but is IP-metered
hs = HalalStock(api_key=os.environ.get("HALALSTOCK_API_KEY"))

try:
    v = hs.check("AAPL")                 # GET /v1/stock/AAPL/halal
    # status is a screening result, not a fatwa — read it with confidence
    print(v["status"], v["compliance_score"], v["confidence"])
    print(v["disclaimer"])               # always relay this to the user

    res = hs.screen(["AAPL", "TSLA", "2222.SR"])   # batch, up to 25
    print(res["count"], "screened")
except HalalStockError as e:
    print("error", e.status, e.message)

import { HalalStock, HalalStockError } from "./halalstock.js";

// key from your account (starts with thl_); keyless works too but is IP-metered
const hs = new HalalStock(process.env.HALALSTOCK_API_KEY);

try {
  const v = await hs.check("AAPL");            // GET /v1/stock/AAPL/halal
  // status is a screening result, not a fatwa — read it with confidence
  console.log(v.status, v.compliance_score, v.confidence);
  console.log(v.disclaimer);                   // always relay this to the user

  const res = await hs.screen(["AAPL", "TSLA", "2222.SR"]);  // batch, up to 25
  console.log(res.count, "screened");
} catch (e) {
  if (e instanceof HalalStockError) console.error(e.status, e.detail);
}

# public — no key needed (metered per IP)
curl "https://halalstock.net/v1/stock/AAPL/halal?profile=standard"

# with your key (starts with thl_) for a higher quota
curl "https://halalstock.net/v1/stock/2222.SR/halal" \
  -H "Authorization: Bearer $HALALSTOCK_API_KEY"

# batch screen up to 25 tickers
curl "https://halalstock.net/v1/screen?symbols=AAPL,TSLA,2222.SR" \
  -H "Authorization: Bearer $HALALSTOCK_API_KEY"

# add to your MCP client config (e.g. Claude Desktop)
{
  "mcpServers": {
    "halalstock": {
      "command": "python",
      "args": ["-m", "tahleel.mcp_server"],
      "env": {
        "HALALSTOCK_API_URL": "https://halalstock.net",
        "HALALSTOCK_API_KEY": "thl_your_key"
      }
    }
  }
}
# then just ask: "Is Aramco (2222.SR) halal?" — the agent calls check_halal()

Get the clients from the repo: /sdk/python/halalstock.py and /sdk/javascript/halalstock.js. Both wrap the same REST endpoints below.

For AI agents (MCP)

HalalStock ships a Model Context Protocol server. Point Claude Desktop, Cursor, or any MCP client at it and just ask whether a stock is halal.

# add to your MCP client config (e.g. Claude Desktop)
{
  "mcpServers": {
    "halalstock": {
      "command": "python",
      "args": ["-m", "tahleel.mcp_server"],
      "env": {
        "HALALSTOCK_API_URL": "https://halalstock.net",
        "HALALSTOCK_API_KEY": "thl_your_key"
      }
    }
  }
}

# the server exposes two tools:
#   check_halal(symbol, profile="standard")
#   screen_portfolio(symbols, profile="standard")

# then just ask the agent:
"Is Aramco (2222.SR) halal?"
"Screen AAPL, TSLA and JPM for Sharia compliance."

# With HALALSTOCK_API_URL + HALALSTOCK_API_KEY set, calls
# go to the hosted, metered API. Without them, the server
# screens locally with no API key (best-effort, via Yahoo —
# US names degrade gracefully; still needs a network connection).

Endpoint reference

Most read endpoints need no key (metered per IP); some need a key, a few need a paid plan.

Discovery endpoints (/v1/discovery/*) and zakat tools (/v1/zakat/*) are also available — see /v1/info for the full list and your plan's quota.

Market coverage: US-listed stocks are fully supported (SEC EDGAR + Yahoo + Finnhub). Gulf and other international markets are best-effort, covered where reliable data is available; when a figure can't be confirmed we return status 'unknown' or verified=false rather than guess.

Rate limits & errors

Calls are metered daily. Watch the X-Daily-Used and X-Daily-Limit response headers.

There is also a per-minute burst cap on top of the daily quota: Pro = 300 requests/min, Business = 600 requests/min. Spread large jobs out — a per-minute hit returns a 429 whose body says "max N requests/minute on your plan" (distinct from the daily-quota 429).

Get your API key See pricing