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

# Quickstart

> Create a key and make your first compliance request in under two minutes.

## 1. Get your API key

Sign up at [halal.sh/account/api](https://halal.sh/account/api) to get a sandbox
API key instantly — no credit card required. Sandbox keys return **real data**
with the **same response schema** as production, scoped to a curated set of
instruments:

* **Stocks** — AAPL, MSFT, NVDA, GOOGL, JPM, GS, META, TSLA, JNJ, AMZN
* **ETFs** — SPY, HLAL

Requests for any other symbol return `403`. Live keys, included with the
[halal.sh Plus plan](https://halal.sh/plans), unlock the full universe.

## 2. Make your first request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.halal.sh/v1/instruments/AAPL/compliance \
    -H "X-API-Key: hsh_sandbox_your_key"
  ```

  ```javascript Node.js theme={null}
  const res = await fetch(
    "https://api.halal.sh/v1/instruments/AAPL/compliance",
    { headers: { "X-API-Key": process.env.HALALSH_API_KEY } }
  );
  const { data } = await res.json();

  console.log(data.determination.status);            // "compliant"
  console.log(data.screens.debt_to_market_cap.value); // 0.020616
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
      "https://api.halal.sh/v1/instruments/AAPL/compliance",
      headers={"X-API-Key": "hsh_sandbox_your_key"},
  )
  data = res.json()["data"]

  print(data["determination"]["status"])              # "compliant"
  print(data["screens"]["debt_to_market_cap"]["value"])  # 0.020616
  ```
</CodeGroup>

## 3. Read the response

Every compliance response carries the determination plus the four screens behind
it:

| Field                              | Meaning                                                              |
| ---------------------------------- | -------------------------------------------------------------------- |
| `determination.status`             | `compliant`, `non-compliant`, or `pending`                           |
| `determination.confidence`         | Confidence in the determination (0–1)                                |
| `screens.business_activity.result` | `pass` / `fail` — is the core business permissible                   |
| `screens.debt_to_market_cap`       | Interest-bearing debt ÷ market cap (threshold ≤ 0.30)                |
| `screens.prohibited_revenue`       | Prohibited income ÷ revenue (threshold ≤ 0.05)                       |
| `screens.cash_to_market_cap`       | (Cash + interest-bearing securities) ÷ market cap (threshold ≤ 0.30) |
| `purification.percentage`          | Percentage of dividends to purify                                    |

<Note>
  Financial screens report `value` and `threshold` as **decimals** (`0.020616` =
  2.06%, `0.30` = 30%). `buffer` is the distance from the threshold in
  **percentage points** — negative when a screen fails.
</Note>

## 4. Screen a portfolio

Check up to 50 symbols in one request:

```bash theme={null}
curl -X POST https://api.halal.sh/v1/screen \
  -H "X-API-Key: hsh_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "symbols": ["AAPL", "MSFT", "NVDA", "JPM", "GS"] }'
```

```json theme={null}
{
  "data": [
    { "symbol": "AAPL", "compliance_status": "compliant",     "health_status": "antifragile", "market_data": { "price": 315.02, "change_24h": 8.71, "change_percent_24h": 2.84 } },
    { "symbol": "MSFT", "compliance_status": "compliant",     "health_status": "antifragile", "market_data": { "price": 441.45, "change_24h": -19.10, "change_percent_24h": -4.15 } },
    { "symbol": "JPM",  "compliance_status": "non-compliant", "health_status": "fragile",     "market_data": { "price": 301.00, "change_24h": 4.42, "change_percent_24h": 1.49 } }
  ],
  "meta": { "total": 3, "requested": 5 }
}
```

## 5. Get an Evidence Packet

For audit-ready documentation with full provenance:

```bash theme={null}
curl https://api.halal.sh/v1/instruments/NVDA/evidence \
  -H "X-API-Key: hsh_sandbox_your_key"
```

This returns each screen with its calculation and source filings — accession
numbers, XBRL tags, and extraction strategies. See
[Evidence Packets](/concepts/evidence-packets) for the full schema.

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Keys, rate limits, and the sandbox.
  </Card>

  <Card title="How screening works" icon="scale-balanced" href="/concepts/compliance">
    AAOIFI Standard 21, screen by screen.
  </Card>

  <Card title="Evidence Packets" icon="file-certificate" href="/concepts/evidence-packets">
    The full audit bundle.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/instruments/get-compliance">
    Every endpoint, every field.
  </Card>
</CardGroup>