Skip to main content

​
What is the halal.sh API?

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

​
What you can do

Screen stocks

Get compliance status, financial ratios, and business activity screening for any public company.

Evidence Packets

Download audit-ready compliance bundles with full provenance — filing references, XBRL tags, extraction strategies.

ETF analysis

Analyze ETF holdings for Shariah purity, with per-holding compliance and purification ratios.

Compliance history

Track compliance status over time with stability metrics — flip rate, distance-to-threshold, trend analysis.

​
Why halal.sh?

Featurehalal.shOther providers
Individual screen results (debt ratio, interest ratio, etc.)YesNo — verdict only
Filing-level provenance (accession number, XBRL tags)YesNo
Extraction strategy transparencyYesNo
Methodology versioningYesNo
Stability metrics (flip rate, threshold distance)YesNo
Auto-analysis for any stockYesFixed coverage only

​
Base URL

All API requests use the following base URL: 
https://api.halal.sh/v1

​
Quick example

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

{
  "data": {
    "symbol": "NVDA",
    "determination": {
      "status": "compliant",
      "confidence": 0.94,
      "methodology": "aaoifi_standard_21@2026.1"
    },
    "screens": {
      "business_activity": { "result": "pass", "concerns": [] },
      "debt_to_market_cap": { "value": 0.082, "threshold": 0.30, "passes": true },
      "prohibited_revenue": { "value": 0.014, "threshold": 0.05, "passes": true },
      "cash_receivables_to_market_cap": { "value": 0.195, "threshold": 0.30, "passes": true }
    },
    "purification": {
      "required": true,
      "percentage": 1.8
    }
  },
  "meta": {
    "methodology": "aaoifi_standard_21@2026.1",
    "as_of": "2026-03-08",
    "request_id": "req_abc123"
  }
}

​
Client libraries

Official SDKs are coming soon. In the meantime, the API is a standard REST API that works with any HTTP client: 
# cURL
curl https://api.halal.sh/v1/instruments/AAPL/compliance \
  -H "X-API-Key: your_api_key"

// Node.js / TypeScript
const res = await fetch("https://api.halal.sh/v1/instruments/AAPL/compliance", {
  headers: { "X-API-Key": process.env.HALAL_API_KEY },
});
const { data } = await res.json();

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

Get started

Get your API key and make your first request in under 2 minutes.