Introduction

The halal.sh API provides programmatic access to Shariah compliance screening for public equities and ETFs, based on AAOIFI Shari’ah Standard No. 21. Unlike providers that return a single black-box verdict, halal.sh exposes every screen, ratio, threshold, and source filing behind each determination. Every number traces back to an SEC filing and an XBRL tag.

What you can do

Screen stocks

Get the compliance status, financial-ratio screens, and business-activity screen for any analysed company.

Evidence Packets

Pull an audit-ready bundle with full provenance — accession numbers, XBRL tags, and extraction strategies for every metric.

Analyse ETFs

Get an ETF’s Shariah purity and a per-holding compliance breakdown.

Track history

Follow a company’s compliance determination across filing periods, with a stability signal.

Why halal.sh

	halal.sh	Typical provider
Individual screen results (debt, revenue, liquidity)	Yes	Verdict only
Filing-level provenance (accession number, XBRL tags)	Yes	No
Extraction-strategy transparency	Yes	No
Versioned methodology	Yes	No
Stability metrics (threshold distance, trend)	Yes	No

Base URL

All requests use a single base URL, with the version in the path:

https://api.halal.sh/v1

Authentication

Every request is authenticated with an API key passed in the X-API-Key header. Create a key — sandbox keys are free and instant. See Authentication for details.

Quick example

curl https://api.halal.sh/v1/instruments/AAPL/compliance \
  -H "X-API-Key: hsh_sandbox_your_key"

{
  "data": {
    "symbol": "AAPL",
    "name": "Apple Inc.",
    "methodology": "aaoifi-ss21@2026.1",
    "as_of": "2026-05-03T08:10:09.622Z",
    "determination": {
      "status": "compliant",
      "confidence": 0.95,
      "explanation": "Apple Inc. (AAPL) is **COMPLIANT** with AAOIFI Standard 21…"
    },
    "screens": {
      "business_activity": {
        "result": "pass",
        "activities": [],
        "prohibited_activities": [],
        "concerns": []
      },
      "debt_to_market_cap":  { "result": "pass", "value": 0.020616, "threshold": 0.30, "operator": "<=", "buffer": 27.94 },
      "cash_to_market_cap":  { "result": "pass", "value": 0.035677, "threshold": 0.30, "operator": "<=", "buffer": 26.43 },
      "prohibited_revenue":  { "result": "pass", "value": 0.010120, "threshold": 0.05, "operator": "<=", "buffer": 3.99 }
    },
    "purification": { "required": true, "percentage": 1.012 }
  },
  "meta": {
    "request_id": "req_C7F0xXgmN",
    "as_of": "2026-05-03T08:10:10.000Z",
    "methodology": "aaoifi-ss21@2026.1"
  }
}

Ratios are decimals (0.020616 = 2.06%); thresholds are decimals too (0.30 = 30%). The full response also includes revenue, stability, and filing. See Get compliance screening.

Client libraries

Official SDKs are on the way. Until then, the API is plain REST and works with any HTTP client:

const res = await fetch(
  "https://api.halal.sh/v1/instruments/AAPL/compliance",
  { headers: { "X-API-Key": process.env.HALALSH_API_KEY } }
);
const { data } = await res.json();
console.log(data.determination.status); // "compliant"

import requests

data = requests.get(
    "https://api.halal.sh/v1/instruments/AAPL/compliance",
    headers={"X-API-Key": API_KEY},
).json()["data"]

print(data["determination"]["status"])  # "compliant"

Get started

Create a key and make your first request in under two minutes.

Support

Questions, or a result that looks off? Get in touch.

Getting Started

Core Concepts

Guides

What you can do

Screen stocks

Evidence Packets

Analyse ETFs

Track history

Why halal.sh

Base URL

Authentication

Quick example

Client libraries

Get started

Support

​What you can do

Screen stocks

Evidence Packets

Analyse ETFs

Track history

​Why halal.sh

​Base URL

​Authentication

​Quick example

​Client libraries

Get started

Support

What you can do

Why halal.sh

Base URL

Authentication

Quick example

Client libraries