---
title: "Calculate Zakat"
method: POST
path: "/api/zakat/calculate"
tags: ["zakat"]
---

# Calculate Zakat

`POST /api/zakat/calculate`

## Request

- Base URL: `https://api.halalterminal.com`
- URL: `https://api.halalterminal.com/api/zakat/calculate`
- Auth: API key in header `X-API-Key`

Calculate zakat owed on a portfolio of stock holdings.

Determines whether the total market value of the provided holdings exceeds
the nisab threshold (85 grams of gold at the given price per gram). If
above nisab, calculates 2.5% zakat on each holding. Returns per-holding
zakat amounts and aggregate totals.

Key response fields:
- `nisab_threshold`: 85 * gold_price_per_gram
- `is_above_nisab`: whether zakat is due
- `total_zakat`: total amount to pay (0 if below nisab)

**curl example:**

    curl -X POST "http://localhost:8000/api/zakat/calculate" \
         -H "Content-Type: application/json" \
         -d '{"holdings": [{"symbol": "AAPL", "market_value": 25000}, {"symbol": "MSFT", "market_value": 18000}], "gold_price_per_gram": 65.0}'

**Python requests example:**

```python
import requests
resp = requests.post(
    "http://localhost:8000/api/zakat/calculate",
    json={
        "holdings": [
            {"symbol": "AAPL", "market_value": 25000},
            {"symbol": "MSFT", "market_value": 18000},
        ],
        "gold_price_per_gram": 65.0,
    },
)
data = resp.json()
if data["is_above_nisab"]:
    print(f"Zakat due: ${data['total_zakat']:.2f}")
else:
    print("Below nisab — no zakat due")
```

## Request body

- ZakatCalculateRequest: Request to calculate zakat owed on a set of stock holdings.
  - `holdings` ZakatHolding[], required: List of stock holdings with current market values.
    - `symbol` string, required: Ticker symbol (e.g. 'AAPL').
    - `market_value` number, required: Current market value of the holding in USD.
  - `gold_price_per_gram` number, nullable: Current gold price per gram in USD, used to compute the nisab threshold. If omitted, live gold price is fetched automatically.

## Response `200`

Zakat calculation with nisab check and per-holding breakdown.

- ZakatCalculateResponse: Complete zakat calculation result with nisab check and per-holding breakdown.
  - `total_market_value` number, required: Total market value of all holdings in USD.
  - `nisab_threshold` number, required: Nisab threshold in USD (85 grams of gold at given price).
  - `gold_price_per_gram` number, required: Gold price per gram used for nisab calculation.
  - `is_above_nisab` boolean, required: Whether total holdings exceed the nisab threshold.
  - `zakat_rate` number, required: Zakat rate applied (0.025 = 2.5%).
  - `total_zakat` number, required: Total zakat owed across all holdings in USD. Zero if below nisab.
  - `holdings` ZakatHoldingResult[], required: Per-holding zakat breakdown.
    - `symbol` string, required: Ticker symbol.
    - `market_value` number, required: Market value of the holding in USD.
    - `zakat_amount` number, required: Zakat owed on this holding in USD (2.5% of value).
  - `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

- `401`: Authentication required (if auth is enabled).
- `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)