Skip to main content

​
Overview

The simplest integration: fetch a stock’s compliance status and display a badge in your app. One API call, one badge.

​
Fetch compliance status

const response = await fetch(
  `https://api.halal.sh/v1/instruments/${symbol}/compliance`,
  { headers: { "X-API-Key": process.env.HALAL_API_KEY } }
);
const { data } = await response.json();

​
Display the badge

Use data.determination.status to render a badge: 
function ComplianceBadge({ symbol }) {
  const [compliance, setCompliance] = useState(null);

  useEffect(() => {
    fetch(`/api/compliance/${symbol}`) // Your backend proxy
      .then(res => res.json())
      .then(({ data }) => setCompliance(data));
  }, [symbol]);

  if (!compliance) return null;

  const { status, confidence } = compliance.determination;

  const config = {
    compliant: { label: "Halal", color: "bg-emerald-100 text-emerald-800" },
    "non-compliant": { label: "Not Halal", color: "bg-rose-100 text-rose-800" },
    pending: { label: "Analyzing...", color: "bg-gray-100 text-gray-800" },
  };

  const { label, color } = config[status];

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

​
Add ratio details

For a richer display, show the individual screen results: 
function ComplianceDetail({ data }) {
  const { screens, purification } = data;

  return (
    <div>
      <h3>Screening Results</h3>
      <ul>
        <li>
          Business Activity: {screens.business_activity.result === "pass" ? "Permissible" : "Prohibited"}
        </li>
        <li>
          Debt Ratio: {(screens.debt_to_market_cap.value * 100).toFixed(1)}%
          (threshold: {screens.debt_to_market_cap.threshold * 100}%)
        </li>
        <li>
          Prohibited Revenue: {(screens.prohibited_revenue.value * 100).toFixed(1)}%
          (threshold: {screens.prohibited_revenue.threshold * 100}%)
        </li>
        <li>
          Cash & Receivables: {(screens.cash_receivables_to_market_cap.value * 100).toFixed(1)}%
          (threshold: {screens.cash_receivables_to_market_cap.threshold * 100}%)
        </li>
      </ul>
      {purification.required && (
        <p>Purification: {purification.percentage}% of dividends</p>
      )}
    </div>
  );
}
Always call the halal.sh API from your backend, never from client-side code. Your API key must stay secret.