Implementing Zakat and Sukuk Tracking via KhaleejiAPI Python SDK

Why Build Islamic Finance Features?

Islamic finance assets surpassed $4 trillion globally in 2025, with the GCC accounting for the largest share. If you're building a wealth management app, a banking dashboard, or a personal finance tool for Muslim users in the UAE, Saudi Arabia, or wider MENA, your product is incomplete without:

• Zakat calculation — the annual religious wealth tax that applies to savings, investments, gold, silver, and business assets
• Sukuk tracking — Islamic bonds that comply with Sharia (no riba/interest); a $1.3 trillion+ market in the GCC alone

KhaleejiAPI provides production-ready APIs for both, backed by live gold and silver spot prices and a reference database of 12 active GCC sukuk. This tutorial walks through a complete Python implementation from installation to a working portfolio dashboard.

Prerequisites

• Python 3.9+
• A KhaleejiAPI account (sign up free — 1,000 requests/month, no credit card)
• Your API key from the dashboard

Installation

pip install khaleejiapi

Or add to your requirements.txt:

khaleejiapi>=1.1.0

Part 1: Zakat Calculation

What is Nisab?

Nisab is the minimum wealth threshold above which Zakat becomes obligatory — roughly 85 grams of gold or 595 grams of silver at current market prices. Because gold and silver prices fluctuate daily, a static nisab figure is always wrong.

KhaleejiAPI's Zakat endpoint fetches live spot prices at request time and computes the exact nisab in AED, USD, SAR, and KWD simultaneously.

Basic Calculation

from khaleejiapi import KhaleejiAPI
client = KhaleejiAPI(api_key="YOUR_KEY")
result = client.zakat.calculate(
    assets={
        "cash": 50000,          # AED in savings / current accounts
        "gold": 120,            # grams
        "silver": 800,          # grams
        "stocks": 30000,        # AED market value of traded stocks
        "receivables": 5000,    # AED owed to you (expected to be paid)
    },
    currency="AED",
    lunar_year=True,            # use Hijri year (default) vs. solar
)
print(result)

Response:

{
  "nisab": {
    "gold_grams": 85,
    "silver_grams": 595,
    "value_aed": 28140.50,
    "spot_gold_aed_per_gram": 331.30,
    "spot_silver_aed_per_gram": 3.72,
    "method_used": "gold"
  },
  "total_zakatable_assets": 85000,
  "above_nisab": true,
  "zakat_due_aed": 2125.00,
  "zakat_rate": 0.025,
  "breakdown": {
    "cash": 1250.00,
    "gold": 90.00,
    "silver": 7.43,
    "stocks": 750.00,
    "receivables": 125.00
  },
  "calculated_at": "2026-05-14T12:00:00Z"
}

Multi-Currency Support

For users whose assets span multiple currencies, pass each currency separately:

result = client.zakat.calculate(
    assets={
        "cash": 50000,       # AED
        "cash_usd": 5000,    # USD (auto-converted at live rate)
        "cash_sar": 20000,   # SAR (auto-converted at live rate)
        "gold": 50,          # grams
    },
    currency="AED",
)

KhaleejiAPI uses its own live exchange rate feed (updated hourly) for currency conversion, so you don't need a separate FX integration.

Nisab Method Selection

There is a scholarly difference of opinion on whether to use the gold or silver nisab threshold. The silver nisab is lower (making Zakat obligatory on smaller wealth). Your app can let users choose:

# Gold nisab (default, most common in GCC)
result_gold = client.zakat.calculate(
    assets={"cash": 15000},
    nisab_method="gold",
    currency="AED",
)
# Silver nisab (more conservative — catches more wealth)
result_silver = client.zakat.calculate(
    assets={"cash": 15000},
    nisab_method="silver",
    currency="AED",
)
print(f"Gold nisab: {result_gold['above_nisab']}")    # may be False
print(f"Silver nisab: {result_silver['above_nisab']}") # more likely True

Direct REST Call

If you prefer raw HTTP calls without the SDK:

curl -X POST https://khaleejiapi.dev/api/v1/zakat/calculate \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": { "cash": 50000, "gold": 120 },
    "currency": "AED",
    "nisabMethod": "gold"
  }'

Part 2: Sukuk Portfolio Tracking

Sukuk (Islamic bonds) are structured to generate returns without paying interest (riba), using profit-sharing, leasing, or murabaha arrangements. The GCC sukuk market now exceeds $1.3 trillion in outstanding issuance.

List Available Sukuk

# List all tracked sukuk
sukuk_list = client.sukuk.list()
for s in sukuk_list["sukuk"]:
    print(f"{s['name']} | {s['issuer']} | Yield: {s['currentYield']}%")

The reference database includes 12 GCC sukuk covering sovereign issuances from UAE, Saudi Arabia, Kuwait, Qatar, and Bahrain, as well as corporate sukuk from major GCC banks.

Sample output:

UAE Sovereign Sukuk 2027 | UAE Ministry of Finance | Yield: 4.85%
Saudi Arabia Green Sukuk 2030 | Saudi Government | Yield: 5.12%
DP World Sukuk 2026 | DP World | Yield: 4.95%
Emaar Properties Sukuk 2028 | Emaar | Yield: 5.45%

Get Sukuk Details

sukuk = client.sukuk.get("uae-sovereign-2027")
print(sukuk)

{
  "id": "uae-sovereign-2027",
  "name": "UAE Sovereign Sukuk 2027",
  "issuer": "UAE Ministry of Finance",
  "type": "sovereign",
  "structure": "Ijara",
  "faceValue": 1000,
  "currency": "USD",
  "issueDate": "2022-09-15",
  "maturityDate": "2027-09-15",
  "profitRate": 4.50,
  "currentYield": 4.85,
  "rating": "Aa2",
  "shariaCompliance": {
    "certified": true,
    "board": "AAOIFI",
    "standard": "Sharia Standard No. 17"
  },
  "market": "Nasdaq Dubai",
  "isin": "XS2000000001"
}

Portfolio Dashboard

Here is a complete portfolio tracker that combines zakat calculation with sukuk holdings:

from khaleejiapi import KhaleejiAPI
from dataclasses import dataclass, field
from typing import Optional
import os
client = KhaleejiAPI(api_key=os.environ["KHALEEJI_API_KEY"])
@dataclass
class Portfolio:
    """Islamic finance portfolio: cash, gold, and sukuk holdings."""
    cash_aed: float = 0.0
    gold_grams: float = 0.0
    silver_grams: float = 0.0
    sukuk_holdings: dict[str, float] = field(default_factory=dict)
    # {sukuk_id: face_value_held_in_usd}
def build_portfolio_report(portfolio: Portfolio) -> dict:
    """
    Generate a full Islamic finance report:
    - Sukuk portfolio valuation
    - Zakat due across all asset classes
    """
# 1. Resolve sukuk market values
    sukuk_value_usd = 0.0
    sukuk_details = []
    for sukuk_id, face_value in portfolio.sukuk_holdings.items():
        sukuk = client.sukuk.get(sukuk_id)["sukuk"]
        # Estimate market value: face * (current yield / profit rate) proxy
        market_value = face_value * (sukuk["profitRate"] / sukuk["currentYield"])
        sukuk_value_usd += market_value
        sukuk_details.append({
            "name": sukuk["name"],
            "face_value_usd": face_value,
            "estimated_market_value_usd": round(market_value, 2),
            "current_yield_pct": sukuk["currentYield"],
            "sharia_certified": sukuk["shariaCompliance"]["certified"],
        })
# 2. Convert sukuk USD value to AED for zakat
    # KhaleejiAPI exchange rate for USD/AED is ~3.67 (pegged)
    sukuk_value_aed = sukuk_value_usd * 3.672
# 3. Calculate zakat across all assets
    zakat = client.zakat.calculate(
        assets={
            "cash": portfolio.cash_aed,
            "gold": portfolio.gold_grams,
            "silver": portfolio.silver_grams,
            "stocks": sukuk_value_aed,  # sukuk treated as investments
        },
        currency="AED",
        nisab_method="gold",
    )
return {
        "portfolio_summary": {
            "cash_aed": portfolio.cash_aed,
            "gold_grams": portfolio.gold_grams,
            "sukuk_value_aed": round(sukuk_value_aed, 2),
            "sukuk_holdings": sukuk_details,
        },
        "zakat": {
            "due_aed": zakat["zakat_due_aed"],
            "above_nisab": zakat["above_nisab"],
            "nisab_value_aed": zakat["nisab"]["value_aed"],
            "breakdown": zakat["breakdown"],
        },
    }
# --- Run it ---
my_portfolio = Portfolio(
    cash_aed=85000,
    gold_grams=50,
    silver_grams=200,
    sukuk_holdings={
        "uae-sovereign-2027": 10000,   # $10,000 face value
        "saudi-green-sukuk-2030": 5000, # $5,000 face value
    },
)
report = build_portfolio_report(my_portfolio)
print(f"Total Zakat Due: AED {report['zakat']['due_aed']:,.2f}")
print(f"Sukuk Portfolio: AED {report['portfolio_summary']['sukuk_value_aed']:,.2f}")
for h in report["portfolio_summary"]["sukuk_holdings"]:
    sharia = "✓ Sharia-certified" if h["sharia_certified"] else "⚠ Check certification"
    print(f"  {h['name']}: USD {h['face_value_usd']:,} — {sharia}")

Part 3: Adding a Hijri Date to Your Reports

Zakat is traditionally due on the Hijri calendar anniversary of first reaching nisab. Add a Hijri date stamp to your report:

from datetime import date
today = date.today().isoformat()
hijri = client.islamic.convert_hijri(date=today, direction="to_hijri")
print(f"Report Date: {today} / {hijri['hijri']['date']} AH")
# "Report Date: 2026-05-14 / 1447-11-16 AH"

Performance: Why ap-south-1 Matters

Every zakat calculation fetches live gold and silver spot prices from global commodity feeds. Stale cached prices can shift a user's nisab threshold by hundreds of AED. KhaleejiAPI refreshes commodity prices every 15 minutes and serves them from AWS ap-south-1 (Mumbai) behind Cloudflare's GCC edge network.

For UAE and Saudi users, this delivers 80–120 ms total round-trip latency — fast enough that you can call the API synchronously during a page load or checkout flow without degrading UX. A comparable US-East-1 deployment would add 150–200 ms of extra latency for GCC users, making synchronous calls impractical.

Error Handling

from khaleejiapi import KhaleejiAPI, KhaleejiAPIError, RateLimitError
client = KhaleejiAPI(api_key=os.environ["KHALEEJI_API_KEY"])
try:
    result = client.zakat.calculate(
        assets={"cash": 100000},
        currency="AED",
    )
except RateLimitError as e:
    print(f"Rate limit hit — retry after {e.retry_after}s")
except KhaleejiAPIError as e:
    print(f"API error {e.status_code}: {e.message}")

Pricing & Limits

Zakat and Sukuk APIs count as standard API calls — no premium tier required.

Next Steps

• Browse the full Zakat API documentation
• Explore the Sukuk Tracker reference
• Check out the Python SDK on PyPI

Get your free API key →