ETF purification

Overview

An ETF holds many stocks, some compliant and some not. We screen each holding and combine the results into one purity figure: the share of the fund, by weight, in compliant holdings. You need two endpoints:

GET /etfs/{symbol}

Fund-level purity: the compliant share of the fund by weight, and the 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, not a decimal: 66.74 means 66.74% of the fund’s weight is in compliant holdings.

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 we haven’t analyzed yet, whose weight doesn’t count as compliant
`top_10_coverage`	Despite its name, the total weight of every holding in the snapshot, as a percentage of the fund (`99.95` = 99.95%)
`as_of`	When we computed the figure. A live figure is computed on each request
`holdings_as_of`	The date of the holdings snapshot behind the figure. It can be weeks older than `as_of`

Purity is weighted, so the percentage won’t match the count of compliant holdings: a few large non-compliant positions can lower percentage even when most holdings pass. The weight of unanalyzed holdings doesn’t count as compliant until we analyze them.

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 (7.12 = 7.12% of the fund), and compliance_status is compliant, non-compliant or pending. To find the holdings that lower purity the most, 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

Purification for a fund holder

purity.percentage is the compliant share of the fund by weight. 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 the amount to purify. We work out a fund holder’s amount this way, on the fund’s page and in the purification calculator:

Each compliant holding adds its per-share figure

A fund unit is proportional ownership of what the fund holds, so we apply the per-share method (AAOIFI Standard 21, clause 3/4/6/4) through it: each analyzed compliant holding adds 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 we haven’t analyzed adds nothing, so the figure is a floor, and we show it only once analyzed weight reaches 90% of the fund.

Non-compliant holdings affect purity only

A non-compliant holding lowers purity.percentage and adds no income to purify. A holder weighs the fund’s purity when choosing the fund.

The API doesn’t return the per-unit figure or the holding data it needs. Present purity as composition, and send holders to the purification calculator for the amount. The per-unit method is our own extension of the per-share method to funds: the standard has no clause on funds.

Use cases

Robo-advisors: rank funds by purity.percentage so users can pick the ETF with the highest purity.
Portfolio tools: weight each ETF’s purity by position size to estimate portfolio-level purity.
Research: track how a fund’s purity changes 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

Purification for a fund holder

Use cases