> ## Documentation Index
> Fetch the complete documentation index at: https://docs.halal.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed a Compliance Badge

> Add a Shariah compliance badge to your app with a single API call.

## 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.

<Warning>
  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.
</Warning>

## 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.

```javascript theme={null}
// 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:

```json theme={null}
{
  "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`.

```jsx theme={null}
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"`.

```jsx theme={null}
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>
  );
}
```

<Note>
  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`.
</Note>