Embed a Compliance Badge

Overview

The simplest integration: fetch a stock’s compliance result and render a badge. One request to GET /instruments/{symbol}/compliance, one badge in your UI.

Never call the halal.sh API directly from the browser — that would expose your API key. Proxy the request through your own backend, which holds the key, and have your frontend talk to the proxy.

Step 1 — Proxy the request through your backend

Your server holds the API key and forwards the call to halal.sh. The browser only ever talks to your own endpoint.

// server: GET /api/compliance/:symbol
app.get("/api/compliance/:symbol", async (req, res) => {
  const response = await fetch(
    `https://api.halal.sh/v1/instruments/${req.params.symbol}/compliance`,
    { headers: { "X-API-Key": process.env.HALALSH_API_KEY } }
  );
  const json = await response.json();
  res.json(json);
});

The compliance payload looks like this:

{
  "data": {
    "determination": { "status": "compliant" },
    "screens": {
      "debt_to_market_cap": { "result": "pass", "value": 0.037, "threshold": 0.30 },
      "cash_to_market_cap": { "result": "pass", "value": 0.221, "threshold": 0.30 },
      "prohibited_revenue": { "result": "pass", "value": 0.012, "threshold": 0.05 }
    }
  }
}

Step 2 — Render the badge

Drive the badge off determination.status. The three statuses are compliant, non-compliant, and pending.

import { useEffect, useState } from "react";

const BADGE = {
  "compliant": { label: "Halal", className: "bg-emerald-100 text-emerald-800" },
  "non-compliant": { label: "Not Halal", className: "bg-rose-100 text-rose-800" },
  "pending": { label: "Not yet analysed", className: "bg-gray-100 text-gray-800" },
};

function ComplianceBadge({ symbol }) {
  const [data, setData] = useState(null);

  useEffect(() => {
    // Hits your backend proxy, never api.halal.sh directly.
    fetch(`/api/compliance/${symbol}`)
      .then((res) => res.json())
      .then(({ data }) => setData(data));
  }, [symbol]);

  if (!data) return null;

  const { label, className } = BADGE[data.determination.status];

  return (
    <span className={`px-2 py-1 rounded-full text-sm font-medium ${className}`}>
      {label}
    </span>
  );
}

Step 3 — Show the screen details

For a richer view, surface the three financial screens. Each one reports a result of "pass" or "fail" — there is no boolean passes field, so check result === "pass".

function ComplianceDetail({ data }) {
  const { screens, purification } = data;

  const rows = [
    { label: "Debt / market cap", screen: screens.debt_to_market_cap },
    { label: "Cash / market cap", screen: screens.cash_to_market_cap },
    { label: "Prohibited revenue", screen: screens.prohibited_revenue },
  ];

  return (
    <div>
      <h3>Screening results</h3>
      <ul>
        {rows.map(({ label, screen }) => (
          <li key={label}>
            {label}: {(screen.value * 100).toFixed(1)}%
            {" "}(limit {(screen.threshold * 100).toFixed(0)}%) —{" "}
            {screen.result === "pass" ? "Pass" : "Fail"}
          </li>
        ))}
      </ul>

      {purification?.required && (
        <p>Purify {purification.percentage}% of dividends received.</p>
      )}
    </div>
  );
}

Ratio value and threshold are decimals — 0.30 means 30%, so multiply by 100 before display. The three financial screen keys are always debt_to_market_cap, cash_to_market_cap, and prohibited_revenue.

Getting Started

Core Concepts

Guides

Embed a Compliance Badge

Overview

Step 1 — Proxy the request through your backend

Step 2 — Render the badge

Step 3 — Show the screen details

​Overview

​Step 1 — Proxy the request through your backend

​Step 2 — Render the badge

​Step 3 — Show the screen details

Overview

Step 1 — Proxy the request through your backend

Step 2 — Render the badge

Step 3 — Show the screen details