Quickstart

1. Get your API key

Sign up at halal.sh/account/api to get a sandbox API key instantly — no credit card required. Sandbox keys return real data with the same response schema as production, scoped to a curated set of instruments:

Stocks — AAPL, MSFT, NVDA, GOOGL, JPM, GS, META, TSLA, JNJ, AMZN
ETFs — SPY, HLAL

Requests for any other symbol return 403. Live keys, included with the halal.sh Plus plan, unlock the full universe.

2. Make your first request

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

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"
console.log(data.screens.debt_to_market_cap.value); // 0.020616

import requests

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

print(data["determination"]["status"])              # "compliant"
print(data["screens"]["debt_to_market_cap"]["value"])  # 0.020616

3. Read the response

Every compliance response carries the determination plus the four screens behind it:

Field	Meaning
`determination.status`	`compliant`, `non-compliant`, or `pending`
`determination.confidence`	Confidence in the determination (0–1)
`screens.business_activity.result`	`pass` / `fail` — is the core business permissible
`screens.debt_to_market_cap`	Interest-bearing debt ÷ market cap (threshold ≤ 0.30)
`screens.prohibited_revenue`	Prohibited income ÷ revenue (threshold ≤ 0.05)
`screens.cash_to_market_cap`	(Cash + interest-bearing securities) ÷ market cap (threshold ≤ 0.30)
`purification.percentage`	Percentage of dividends to purify

Financial screens report value and threshold as decimals (0.020616 = 2.06%, 0.30 = 30%). buffer is the distance from the threshold in percentage points — negative when a screen fails.

4. Screen a portfolio

Check up to 50 symbols in one request:

curl -X POST https://api.halal.sh/v1/screen \
  -H "X-API-Key: hsh_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "symbols": ["AAPL", "MSFT", "NVDA", "JPM", "GS"] }'

{
  "data": [
    { "symbol": "AAPL", "compliance_status": "compliant",     "health_status": "antifragile", "market_data": { "price": 315.02, "change_24h": 8.71, "change_percent_24h": 2.84 } },
    { "symbol": "MSFT", "compliance_status": "compliant",     "health_status": "antifragile", "market_data": { "price": 441.45, "change_24h": -19.10, "change_percent_24h": -4.15 } },
    { "symbol": "JPM",  "compliance_status": "non-compliant", "health_status": "fragile",     "market_data": { "price": 301.00, "change_24h": 4.42, "change_percent_24h": 1.49 } }
  ],
  "meta": { "total": 3, "requested": 5 }
}

5. Get an Evidence Packet

For audit-ready documentation with full provenance:

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

This returns each screen with its calculation and source filings — accession numbers, XBRL tags, and extraction strategies. See Evidence Packets for the full schema.

Next steps

Authentication

Keys, rate limits, and the sandbox.

How screening works

AAOIFI Standard 21, screen by screen.

Evidence Packets

The full audit bundle.

API reference

Every endpoint, every field.

Getting Started

Core Concepts

Guides

1. Get your API key

2. Make your first request

3. Read the response

4. Screen a portfolio

5. Get an Evidence Packet

Next steps

Authentication

How screening works

Evidence Packets

API reference

​1. Get your API key

​2. Make your first request

​3. Read the response

​4. Screen a portfolio

​5. Get an Evidence Packet

​Next steps

Authentication

How screening works

Evidence Packets

API reference

1. Get your API key

2. Make your first request

3. Read the response

4. Screen a portfolio

5. Get an Evidence Packet

Next steps