# Daleel — Auditable Halal Stock Screening (Developer Hub)

**دليل · Daleel** (Arabic for *evidence*) screens US-listed stocks and ETFs for
Sharia compliance — and shows its receipts. Every verdict cites the SEC filing
behind it: the XBRL tag, the form (10-K / 20-F / 40-F), the period, and a link
to the filing on sec.gov. Five methodologies checked side by side: **AAOIFI,
DJIM, MSCI, S&P, and FTSE**.

**Live**: https://daleel.o11r.com · **Docs**: https://daleel.o11r.com/developers · **Methodology**: https://daleel.o11r.com/methodology

> This repo is the public developer hub (docs, examples, MCP metadata).
> The screening engine itself is closed source.

## For AI agents (MCP)

Daleel runs a Model Context Protocol server — connect any MCP-capable agent:

```json
{
  "mcpServers": {
    "daleel": {
      "type": "http",
      "url": "https://daleel.o11r.com/mcp"
    }
  }
}
```

Tools: `screen_ticker(ticker)` → full verdict with evidence citations ·
`screening_methodology()` → the methodology summary.
Anonymous use: 10 req/min per IP. With an `X-API-Key` header: 30+ req/min.

## REST quickstart

```bash
# No key needed (demo tier, 10 req/min):
curl https://daleel.o11r.com/v1/screen/MSFT

# Free key (30 req/min, batch + history):
curl -X POST https://daleel.o11r.com/api/keys \
  -H "Content-Type: application/json" -d '{"email": "you@example.com"}'

curl https://daleel.o11r.com/v1/screen/MSFT -H "X-API-Key: YOUR_KEY"
```

The response includes a per-methodology audit matrix (every ratio vs every
threshold), an evidence ledger with sec.gov links, purification percentages,
and — with `?overlays=all` — values/ESG screens sourced from official
government lists (UFLPA, DoD 1260H, state divestment lists), each with its
citation. See [examples/](examples/) for Python and JavaScript.

## Principles

- **Missing data is never treated as compliant.** Unscreenable → says so.
- **Every approximation is disclosed** in the response itself.
- **Verdicts are methodology calculations**, not religious rulings; consult a
  qualified scholar for matters of fiqh. Nothing here is investment advice.

## Links

- OpenAPI: https://daleel.o11r.com/openapi.json
- llms.txt: https://daleel.o11r.com/llms.txt
- Why we built this: https://daleel.o11r.com/blog/why-my-trading-bot-made-nothing
- Contact: daleel@o11r.com