Quickstart

1. Get your API key

Sign up at halal.sh/account/api and create a sandbox API key. It’s free and needs no credit card. Sandbox keys return real data in the same response schema as live keys, for these 12 instruments:

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

Any other symbol returns 403 sandbox_restricted. With the Plus plan or the Developer plan, you get live keys for the full universe. To show results to the users of your product, you need the Developer plan, which is billed separately from Plus.

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 has the determination and the four screens behind it:

Field	Meaning
`determination.status`	`compliant`, `non-compliant`, or `pending`
`determination.confidence`	Confidence in the determination (0 to 1)
`screens.business_activity.result`	`pass` / `fail`: whether the core business is 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`	The company’s prohibited-income rate (prohibited revenue ÷ total revenue)

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", "JPM"] }'

{
  "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": "non-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": 3, "not_found": [] }
}

5. Get an Evidence Packet

An Evidence Packet is the audit-ready record behind a determination:

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

It has each screen’s calculation, the values it used, and the filing they came from with its accession number. 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