How to Add Shariah Screening to Your Fintech App

If you're building a fintech app that serves Muslim investors — or adding Shariah compliance features to an existing platform — the Halal Terminal API lets you integrate stock screening, ETF analysis, purification calculations, and zakat in minutes. This tutorial shows you how with Python, JavaScript, and React examples.

Getting Started

1. Get Your API Key

curl -X POST https://api.halalterminal.com/api/keys/generate \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@yourapp.com"}'

You'll receive a free API key with 50 calls/month instantly. No credit card required.

2. Test the Connection

curl https://api.halalterminal.com/api/health

Python Integration

Basic Stock Screening

import requests

class HalalTerminal:
    BASE_URL = "https://api.halalterminal.com/api"

    def __init__(self, api_key: str):
        self.session = requests.Session()
        self.session.headers["X-API-Key"] = api_key

    def screen_stock(self, symbol: str) -> dict:
        resp = self.session.post(f"{self.BASE_URL}/screen/{symbol}")
        resp.raise_for_status()
        return resp.json()

    def screen_etf(self, symbol: str) -> dict:
        resp = self.session.post(f"{self.BASE_URL}/etf/{symbol}/screen")
        resp.raise_for_status()
        return resp.json()

    def calculate_zakat(self, holdings: list, gold_price: float = 65.0) -> dict:
        resp = self.session.post(
            f"{self.BASE_URL}/zakat/calculate",
            json={"holdings": holdings, "gold_price_per_gram": gold_price}
        )
        resp.raise_for_status()
        return resp.json()

# Usage
api = HalalTerminal("YOUR_KEY")
result = api.screen_stock("AAPL")

if result["is_compliant"]:
    print(f"AAPL is halal (purification: {result['purification_rate']:.1%})")
else:
    print("AAPL fails Shariah screening")

Portfolio Compliance Check

def check_portfolio(api, symbols):
    results = []
    for symbol in symbols:
        data = api.screen_stock(symbol)
        results.append({
            "symbol": symbol,
            "compliant": data["is_compliant"],
            "aaoifi": data["aaoifi_compliant"],
            "djim": data["djim_compliant"],
            "purification": data["purification_rate"],
        })
    return results

portfolio = check_portfolio(api, ["AAPL", "MSFT", "NVDA", "GOOGL", "AMZN"])
compliant = [r for r in portfolio if r["compliant"]]
print(f"Portfolio compliance: {len(compliant)}/{len(portfolio)} stocks pass")

JavaScript / Node.js Integration

class HalalTerminal {
  constructor(apiKey) {
    this.baseUrl = 'https://api.halalterminal.com/api';
    this.headers = {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json'
    };
  }

  async screenStock(symbol) {
    const resp = await fetch(
      `${this.baseUrl}/screen/${symbol}`,
      { method: 'POST', headers: this.headers }
    );
    return resp.json();
  }

  async screenETF(symbol) {
    const resp = await fetch(
      `${this.baseUrl}/etf/${symbol}/screen`,
      { method: 'POST', headers: this.headers }
    );
    return resp.json();
  }

  async calculateZakat(holdings) {
    const resp = await fetch(
      `${this.baseUrl}/zakat/calculate`,
      {
        method: 'POST',
        headers: this.headers,
        body: JSON.stringify({ holdings, gold_price_per_gram: 65.0 })
      }
    );
    return resp.json();
  }
}

// Usage
const api = new HalalTerminal('YOUR_KEY');
const result = await api.screenStock('NVDA');
console.log(`NVDA: ${result.is_compliant ? 'HALAL' : 'NOT COMPLIANT'}`);

React Component Example

import { useState } from 'react';

function StockScreener({ apiKey }) {
  const [symbol, setSymbol] = useState('');
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);

  const screenStock = async () => {
    setLoading(true);
    const resp = await fetch(
      `https://api.halalterminal.com/api/screen/${symbol}`,
      {
        method: 'POST',
        headers: { 'X-API-Key': apiKey }
      }
    );
    setResult(await resp.json());
    setLoading(false);
  };

  return (
    <div>
      <input
        value={symbol}
        onChange={e => setSymbol(e.target.value.toUpperCase())}
        placeholder="Enter ticker (e.g. AAPL)"
      />
      <button onClick={screenStock} disabled={loading}>
        {loading ? 'Screening...' : 'Screen Stock'}
      </button>

      {result && (
        <div>
          <h3>{result.symbol}: {result.is_compliant ? 'HALAL' : 'NOT COMPLIANT'}</h3>
          <table>
            <tbody>
              <tr><td>AAOIFI</td><td>{result.aaoifi_compliant ? 'PASS' : 'FAIL'}</td></tr>
              <tr><td>DJIM</td><td>{result.djim_compliant ? 'PASS' : 'FAIL'}</td></tr>
              <tr><td>FTSE</td><td>{result.ftse_compliant ? 'PASS' : 'FAIL'}</td></tr>
              <tr><td>MSCI</td><td>{result.msci_compliant ? 'PASS' : 'FAIL'}</td></tr>
              <tr><td>S&P</td><td>{result.sp_compliant ? 'PASS' : 'FAIL'}</td></tr>
              <tr><td>Purification</td><td>{(result.purification_rate * 100).toFixed(1)}%</td></tr>
            </tbody>
          </table>
        </div>
      )}
    </div>
  );
}

Error Handling

# Always handle API errors gracefully
import requests

def safe_screen(api_key, symbol):
    try:
        resp = requests.post(
            f"https://api.halalterminal.com/api/screen/{symbol}",
            headers={"X-API-Key": api_key},
            timeout=30
        )
        if resp.status_code == 401:
            raise ValueError("Invalid API key")
        if resp.status_code == 429:
            raise ValueError("Rate limit exceeded — upgrade your plan")
        if resp.status_code == 404:
            return {"error": f"Symbol {symbol} not found"}
        resp.raise_for_status()
        return resp.json()
    except requests.Timeout:
        return {"error": "Request timed out — try again"}
    except requests.RequestException as e:
        return {"error": str(e)}

Key Takeaways

• Single endpoint, all methodologies — one API call returns AAOIFI, DJIM, FTSE, MSCI, and S&P results
• Works with any language — REST API with JSON responses
• Free tier available — 50 calls/month for development and testing
• Full documentation at /docs with interactive Swagger UI
• Production ready — authentication via X-API-Key header, rate limiting, and error codes