# HalalStock — Agent Skill

Check whether any stock or ETF worldwide is **halal (Sharia-compliant)** using the
HalalStock API. Screening follows **AAOIFI Standard 21**: a business-activity check
plus financial ratios (debt, cash + interest-bearing securities, impure income),
each measured against market cap. Every response is HalalStock's own derived
analysis — a verdict, a 0–100 compliance score, the computed ratios, plain-language
reasons, and zakat/purification figures. Gulf (e.g. Tadawul `.SR`) and US markets
are first-class; any Yahoo-supported ticker can be screened.

> Not a fatwa or investment advice. Verdicts are informational and can change as a
> company's finances change. Always relay the `disclaimer` field to the user.

## Base URL & auth

- Base URL: `https://halalstock.net`
- Auth: send your API key as a Bearer token header:
  `Authorization: Bearer thl_your_key`
- Most read endpoints work **without** a key (metered per IP); a key raises the
  daily quota. Some endpoints **require** a key, and a few require a **paid** key
  (see the table). Get a free key at `https://halalstock.net/#signup` or via
  `POST /v1/signup` with `{"email": "you@example.com"}`.

## The 3-state honesty model

Read the `status` field, not just the score:

- ✅ **`halal`** — business is permissible and every computable ratio passes. Only
  surfaced as `confidence: "verified"` when independently corroborated by a
  scholar-screened Sharia fund (`corroborated_by`); otherwise `confidence:
  "likely"` (free data can't confirm the 5% impure-income rule alone).
- ❌ **`not_halal`** — a non-permissible core business, or a breached ratio.
- ❓ **`questionable`** — HalalStock can't confirm compliance and says so instead of
  guessing. The `reasons` array states exactly why: missing financial data, a
  currency mismatch on the statements, an Islamic bank/takaful whose ratios don't
  apply, or independent sources disagreeing on a core number.
- `unknown` — no data found for that ticker (the API returns HTTP 404).

The `score` is capped at 50 for `questionable` and is 0 for `not_halal`, so a high
score never accompanies anything but a clean pass.

## Key endpoint: screen one symbol

`GET /v1/stock/{symbol}/halal?profile=standard`

- `profile`: `standard` (core scholarly consensus) or `strict` (also excludes
  debated activity such as hotels/entertainment).
- Returns a JSON verdict with these fields:
  - `symbol`, `name`, `currency`, `kind` (`stock` or `etf`)
  - `status` — `halal` | `not_halal` | `questionable` | `unknown`
  - `compliance_score` — 0–100
  - `confidence` — `verified` | `likely` | `needs_review`
  - `corroborated_by` — Sharia-fund tickers that also hold it (independent check)
  - `ratios` — list of `{name, value, threshold, passed, usage_pct, headroom}` for
    `debt_ratio`, `cash_ratio`, `impure_income_ratio`
  - `risk_level` (`safe`/`watch`/`at_risk`/`fail`) + `risk_notes` — early warning
    when a passing ratio sits near its limit
  - `purification_pct` — share of dividends to give to charity (null until impure
    income is known on free data)
  - `activity_flags`, `reasons`, `explanation` (`{en, ar}`)
  - `data_quality`, `sources_used`, `field_confidence`, `disclaimer`

## Other useful endpoints

- `GET /v1/screen?symbols=2222.SR,AAPL,JPM&profile=standard` — batch screen up to 25.
- `GET /v1/search?q=aramco` — resolve a name/ticker before screening.
- `GET /v1/screener?status=halal&country=US&sector=Technology&min_score=80` — find
  halal names from the pre-screened index.
- `GET /v1/stock/{symbol}/zakat?shares=100&intent=investment` — zakat due (2.5%).
- `GET /v1/stock/{symbol}/purification?shares=100` — dividend purification amount.
- `GET /v1/stock/{symbol}/alternatives` — halal stocks in the same sector.
- `GET /v1/top-halal?sector=Technology&limit=20` — top halal stocks by score.
- `GET /v1/methodology` — the exact thresholds and screening stages applied.

Financial-data endpoints (same Bearer `thl_` key; all return HalalStock's own
cross-verified/derived figures, not a redistributed third-party feed):

- `GET /v1/fundamentals/{symbol}` — cross-verified market cap, debt, cash, revenue
  with per-field sources (optional key, metered).
- `GET /v1/ratios/{symbol}` — the screening ratios (debt, cash, impure income) with
  thresholds and pass/fail (optional key, metered).
- `GET /v1/profile/{symbol}` — name, sector, industry, business summary, currency,
  kind (optional key, metered).
- `GET /v1/dividends/{symbol}` — derived dividend-purification figures + the bundled
  verdict (optional key, metered).
- `GET /v1/financials/{symbol}` — multi-period income / balance-sheet / cash-flow
  statements (**paid** key required).
- `GET /v1/stock/{symbol}/history` — compliance status over time (optional key).

## MCP server (AI agents)

HalalStock also ships a Model Context Protocol server, so an agent can call the
same screening without writing HTTP. Add it to your MCP client config:

```json
{
  "mcpServers": {
    "halalstock": {
      "command": "python",
      "args": ["-m", "tahleel.mcp_server"],
      "env": {
        "HALALSTOCK_API_URL": "https://halalstock.net",
        "HALALSTOCK_API_KEY": "thl_your_key"
      }
    }
  }
}
```

With `HALALSTOCK_API_URL` + `HALALSTOCK_API_KEY` set, every tool calls the hosted,
metered API; without them the server screens locally (free, offline via yfinance).
The legacy `TAHLEEL_API_URL` / `TAHLEEL_API_KEY` names are still accepted for
back-compat. The server exposes `check_halal`, `screen_portfolio`, `screen_stock`,
`screener`, `fundamentals`, `ratios`, `financials`, `profile`,
`dividends_purification`, `zakat` and `purification`.

## Rate limits & errors

- Anonymous (no key): metered per IP. A free key raises the daily quota; paid tiers
  raise it further. Read `X-Daily-Used` / `X-Daily-Limit` response headers.
- `401` — missing or invalid API key (for endpoints that require one).
- `402` — paid-only feature; the key is on the free tier.
- `404` — no data found for that symbol (`status: unknown`).
- `429` — daily quota reached. Back off; get a key at `/#signup` or upgrade at
  `/#pricing`.

## Example calls

Screen Saudi Aramco (Tadawul) with a key:

```bash
curl https://halalstock.net/v1/stock/2222.SR/halal \
  -H "Authorization: Bearer thl_your_key"
```

Batch-screen three tickers, no key needed (metered by IP):

```bash
curl "https://halalstock.net/v1/screen?symbols=AAPL,TSLA,JPM&profile=standard"
```

Find the top 10 halal US technology stocks:

```bash
curl "https://halalstock.net/v1/top-halal?country=US&sector=Technology&limit=10"
```

## Reading a verdict (guidance for the agent)

1. Branch on `status` first: `halal` → permissible; `not_halal` → avoid;
   `questionable`/`unknown` → tell the user it can't be confirmed and why.
2. Quote the `reasons` array and the `explanation` so the user sees the rationale.
3. For a `halal` result, mention `confidence` and any `corroborated_by` funds, and
   surface `risk_notes` if `risk_level` is `watch`/`at_risk`.
4. Always pass along the `disclaimer`.