Skip to main content

​
Overview

ETFs contain hundreds of stocks, some compliant and some not. The halal.sh API analyzes each holding individually and provides:
  1. Purity percentage — what portion of the ETF (by weight) is Shariah-compliant
  2. Holdings breakdown — per-holding compliance status
  3. Purification data — how much to purify from dividends

​
Get ETF purity

curl https://api.halal.sh/v1/etfs/SPY \
  -H "X-API-Key: your_api_key"

{
  "data": {
    "symbol": "SPY",
    "name": "SPDR S&P 500 ETF Trust",
    "purity_percentage": 72.5,
    "holdings_breakdown": {
      "compliant": 289,
      "non_compliant": 156,
      "pending": 58,
      "total": 503
    },
    "analysis_date": "2026-03-07"
  }
}

​
Get per-holding compliance

curl "https://api.halal.sh/v1/etfs/SPY/holdings?status=non-compliant&limit=20" \
  -H "X-API-Key: your_api_key"
This returns the non-compliant holdings with their weights, so you can see exactly which stocks are dragging purity down.

​
Filter by compliance status

Use the status query parameter to get only the holdings you care about:
ValueReturns
compliantOnly Shariah-compliant holdings
non-compliantOnly non-compliant holdings
pendingHoldings with analysis in progress
(omit)All holdings

​
Use cases

  • Robo-advisors: Show users which ETFs are “most halal” and by how much
  • Portfolio tools: Calculate portfolio-level purity across multiple ETFs
  • Research: Track how ETF purity changes over time as holdings shift