---
title: "Calculate Etf Purification"
method: POST
path: "/api/etf/{symbol}/purification"
tags: ["etf"]
---

# Calculate Etf Purification

`POST /api/etf/{symbol}/purification`

## Request

- Base URL: `https://api.halalterminal.com`
- URL: `https://api.halalterminal.com/api/etf/{symbol}/purification`
- Auth: API key in header `X-API-Key`

Calculate the purification amount for an ETF investment.

Given an investment amount and optional dividend income, computes how much
money should be donated to purify returns based on each holding's
purification rate. Returns both aggregate amounts and a per-holding
breakdown.

**curl example:**

    curl -X POST "http://localhost:8000/api/etf/VTI/purification" \
         -H "Content-Type: application/json" \
         -d '{"investment_amount": 50000, "dividend_income": 1200}'

**Python requests example:**

```python
import requests
resp = requests.post(
    "http://localhost:8000/api/etf/VTI/purification",
    json={"investment_amount": 50000, "dividend_income": 1200},
)
data = resp.json()
print(f"Total to purify: ${data['total_purification_amount']:.2f}")
```

## Path parameters

- `symbol` string, required: ETF ticker symbol.

## Request body

- ETFPurificationRequest: Request body for calculating purification amounts on an ETF investment.
  - `investment_amount` number, required: Total investment amount in USD.
  - `dividend_income` number, nullable: Dividend income received from the ETF in USD.

## Response `200`

Purification amounts for the investment and optional dividend income.

- ETFPurificationResponse: Purification calculation result for an ETF investment.
  - `symbol` string, required: ETF ticker symbol.
  - `investment_amount` number: Original investment amount in USD.
  - `dividend_income` number, nullable: Dividend income in USD, if provided.
  - `etf_purification_rate` number: Purification rate in percent over the WHOLE fund: 4.17 means 4.17%. Compliant rated holdings contribute their own rate, and every non-compliant or unscreened holding is charged at 100% by prudence. This is the conservative figure and the one to show an investor. GET /api/etf/{symbol}/screening returns `purification_rate`, which averages the compliant rated holdings only and is therefore lower.
  - `purification_basis` string: Denominator behind `etf_purification_rate`. Always 'whole_fund_conservative' on this endpoint, against 'compliant_rated_holdings' on the screening endpoint.
  - `investment_purification_amount` number: Amount to purify from investment gains.
  - `dividend_purification_amount` number, nullable: Amount to purify from dividends.
  - `total_purification_amount` number: Total purification amount (investment + dividends).
  - `holdings` ETFHoldingPurificationDetail[]: Per-holding purification breakdown.
    - `symbol` string, nullable: Ticker symbol of the holding, or null for a weighted line with no listing of its own.
    - `name` string: Company or security name.
    - `weight` number: Portfolio weight in percent: 6.5 means 6.5% of the fund.
    - `compliance_status` string: Shariah compliance status.
    - `purification_rate` number: Effective purification rate charged on this holding, in percent. A compliant rated holding contributes its own rate. A non-compliant or unscreened holding is charged at 100.0 by prudence. A holding compliant by nature is charged at 0.0.
    - `purification_amount` number: Dollar amount to purify for this holding.
  - `disclaimers` Disclaimer[], nullable: Attached by middleware; see /api/disclaimers.
    - `id` string, required: Stable category identifier — safe for clients to dedupe and cache on.
    - `version` string, required: ISO-8601 date of the most recent edit to `text`. Advances whenever the wording changes, even for typo fixes.
    - `lang` string: BCP-47 language tag for `text`. Today always 'en'; reserved for future i18n.
    - `severity` string, required: Grouping hint for UIs. 'religious' for fatwa/scholar caveats; 'data' for data-freshness, sourcing, or coverage caveats.
    - `text` string, required: Short inline disclaimer text.
    - `url` string, required: Canonical legal page URL (deep-linked to the relevant section).

## Other responses

- `404`: ETF symbol not found or has no screening data.
- `422`: Validation Error

---

[API](https://skmtc.dev/halalterminal/apis/halal-terminal-api.md) · [All operations](https://skmtc.dev/halalterminal/apis/halal-terminal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/halalterminal/apis/halal-terminal-api/revisions/78768b250943?raw)