Islamic Finance Guide

Multi-asset Zakat API guide

Calculate an indicative Zakat amount for cash, precious metals, investments, business assets, agriculture, and other supported asset classes with one authenticated request.

Authentication and scope

Use an API key with the finance:zakat scope and send it as a Bearer token. Keep the key on your server. The multi-asset request is POST /api/v1/zakat/calculate; simple cash calculations are also available by GET.

bash
curl "https://khaleejiapi.dev/api/v1/zakat/calculate?amount=50000&currency=AED" \
  -H "Authorization: Bearer $KHALEEJI_API_KEY"

Multi-asset request

Send a non-empty assets array. Each item has a supported type and non-negative monetary value. For gold or silver, a positive weight in grams is used to calculate that asset's value. Asset values use the top-level currency.

bash
curl -X POST "https://khaleejiapi.dev/api/v1/zakat/calculate" \
  -H "Authorization: Bearer $KHALEEJI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "AED",
    "assets": [
      { "type": "cash", "value": 50000 },
      { "type": "gold", "value": 0, "weight": 20 },
      { "type": "silver", "value": 0, "weight": 500 },
      { "type": "stocks", "value": 10000 },
      { "type": "agriculture", "value": 1500, "irrigated": false }
    ]
  }'

Node.js

typescript
const response = await fetch("https://khaleejiapi.dev/api/v1/zakat/calculate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KHALEEJI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    currency: "AED",
    assets: [
      { type: "cash", value: 50000 },
      { type: "gold", value: 0, weight: 20 },
      { type: "stocks", value: 10000 },
    ],
  }),
})
 
if (!response.ok) throw new Error(`Zakat API returned ${response.status}`)
const { data } = await response.json()
console.log(data.calculation.zakatDue, data.calculation.currency)

Python (standard library)

python
import json
import os
from urllib.request import Request, urlopen
 
payload = {
    "currency": "AED",
    "assets": [
        {"type": "cash", "value": 50000},
        {"type": "gold", "value": 0, "weight": 20},
        {"type": "stocks", "value": 10000},
    ],
}
request = Request(
    "https://khaleejiapi.dev/api/v1/zakat/calculate",
    data=json.dumps(payload).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['KHALEEJI_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urlopen(request, timeout=10) as response:
    data = json.load(response)["data"]
    print(data["calculation"]["zakatDue"], data["calculation"]["currency"])

Supported asset types and response

Supported types are cash, gold, silver, stocks, business, agriculture, mutual_funds, crypto, and real_estate. Agriculture accepts irrigated; the returned response includes the calculation, per-asset breakdown, metal-price timestamp, and method reference.

typescript
type ZakatResponse = {
  data: {
    calculation: {
      totalWealth: number
      nisabThreshold: number
      nisabGold: number
      nisabSilver: number
      eligible: boolean
      zakatDue: number
      currency: string
      assetsCount: number
    }
    breakdown: Array<{ type: string; value: number; zakatRate: number; zakatDue: number }>
    metalPrices: { goldPerGram: number; silverPerGram: number; currency: string; fetchedAt: string }
    reference: { method: string; nisabBasis: string; goldNisabGrams: number; silverNisabGrams: number; note: string }
  }
}

Supported currencies include AED, SAR, QAR, BHD, OMR, KWD, USD, EUR, and GBP. Metal and exchange-rate values may be cached or use fallback data; inspect metalPrices.fetchedAt and do not treat returned prices as a guaranteed live quote.