ETF Purification

Overview

An ETF holds many underlying stocks, some compliant and some not. halal.sh screens each holding and rolls the results up into a single purity figure, so you can tell at a glance how much of a fund is Shariah-compliant by weight. Two endpoints cover the workflow:

GET /etfs/{symbol}

Fund-level purity — the headline compliant-by-weight percentage plus holding counts.

GET /etfs/{symbol}/holdings

The per-holding breakdown, with each holding’s compliance status and weight.

Get fund-level purity

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

{
  "data": {
    "symbol": "SPY",
    "name": "SPDR S&P 500 ETF Trust",
    "purity": {
      "percentage": 66.74,
      "compliant_holdings": 289,
      "non_compliant_holdings": 156,
      "unanalyzed_holdings": 58,
      "top_10_coverage": 99.95,
      "as_of": "2026-06-02T09:14:00Z",
      "holdings_as_of": "2026-05-30"
    }
  }
}

purity.percentage is a percentage number, not a decimal: 66.74 means 66.74% of the fund is compliant by weight. The holding counts break the fund down by status:

Field	Meaning
`purity.percentage`	Share of the fund’s weight that is Shariah-compliant (`66.74` = 66.74%)
`compliant_holdings`	Number of holdings screened as compliant
`non_compliant_holdings`	Number of holdings screened as non-compliant
`unanalyzed_holdings`	Holdings not yet analysed — excluded from the compliant weight
`top_10_coverage`	Share of fund weight held by its 10 largest positions (`99.95` = 99.95%)
`as_of`	When the figure was computed. A live figure is computed on each request
`holdings_as_of`	The date of the holdings snapshot the figure weighs, which can be weeks older than `as_of`

Purity is weighted, so the percentage won’t match the raw count of compliant holdings. A handful of large non-compliant positions can pull percentage down even when most holdings pass, and unanalyzed_holdings represents weight that simply isn’t counted as compliant yet.

Get the per-holding breakdown

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

{
  "data": {
    "symbol": "SPY",
    "holdings": [
      { "symbol": "AAPL", "name": "Apple Inc.", "weight": 7.12, "compliance_status": "compliant" },
      { "symbol": "JPM", "name": "JPMorgan Chase & Co.", "weight": 1.34, "compliance_status": "non-compliant" },
      { "symbol": "EXMPL", "name": "Example Corp.", "weight": 0.18, "compliance_status": "pending" }
    ]
  }
}

Each holding’s weight is a percentage number (7.12 = 7.12% of the fund), and compliance_status is one of compliant, non-compliant, or pending. To find the positions dragging purity down, filter for non-compliant holdings and sort by weight:

const res = await fetch("https://api.halal.sh/v1/etfs/SPY/holdings", {
  headers: { "X-API-Key": process.env.HALALSH_API_KEY },
});
const { data } = await res.json();

const offenders = data.holdings
  .filter((h) => h.compliance_status === "non-compliant")
  .sort((a, b) => b.weight - a.weight);

console.log(offenders); // heaviest non-compliant positions first

Purity is composition, not a purification rate

purity.percentage is the share of the fund that is compliant by weight. It says how much of the basket passes the screen. It is not a rate to apply to income: multiplying a distribution, a gain or an investment by the non-compliant share does not give an amount to purify, and no surface on halal.sh presents it that way. How halal.sh works a fund holder’s amount out, on the fund’s page and the purification calculator:

Each compliant holding contributes its per-share figure

A fund unit is proportional ownership of what the fund holds, so the per-share method (AAOIFI Standard 21, clause 3/4/6/4) runs through it: each analyzed compliant holding contributes its prohibited income per dollar of its own market value, weighted by its share of the fund.

The result is a per-unit floor

per unit = fund price × sum of weight × (prohibited income ÷ market cap) over the analyzed compliant holdings. Weight not yet analyzed contributes nothing, so the figure is a floor, and it is shown only once analyzed weight reaches 90% of the fund.

Non-compliant holdings are the purity question, not the purification one

A non-compliant holding inside a fund lowers purity.percentage. It does not add an income line to purify; the fund’s purity is what a holder weighs when choosing the fund.

The per-unit figure needs each holding’s share count and price, which this endpoint does not carry; it is halal.sh’s own extension of the per-share method through a fund’s holdings, and no clause of the standard we have found addresses funds. Present purity as composition and point holders at the purification calculator for the amount.

Use cases

Robo-advisors — rank funds by purity.percentage so users can pick the most compliant ETF.
Portfolio tools — weight each ETF’s purity by position size to estimate portfolio-level purity.
Research — track how a fund’s purity shifts over time as its holdings change.

Getting Started

Core Concepts

Guides

Overview

GET /etfs/{symbol}

GET /etfs/{symbol}/holdings

Get fund-level purity

Get the per-holding breakdown

Purity is composition, not a purification rate

Use cases

​Overview

GET /etfs/{symbol}

GET /etfs/{symbol}/holdings

​Get fund-level purity

​Get the per-holding breakdown

​Purity is composition, not a purification rate

​Use cases

Overview

Get fund-level purity

Get the per-holding breakdown

Purity is composition, not a purification rate

Use cases