DeenGen API reference Free beta
Shariah screening for coins and stocks, the rulings recognised bodies have published, a separate ethics score where every flag has a source and a date, and calculators for purification and zakat. JSON over REST, described by an OpenAPI 3.1 spec. The Free plan is open as a beta: get a key by email. Paid plans are coming later.
Quick start
- Get a key. Fill in the form on the developers page. The key arrives by email within a minute and starts with
dg_. - Paste it here to use the try-it panels below. It stays in this browser tab and is sent only to this site's API.
- Make a call. Copy the curl line, or use one of the small clients.
export DEENGEN_API_KEY="dg_..." # the key from your email curl "https://www.deengen.com/api/v1/screen?symbols=AAPL,bitcoin" \ -H "Authorization: Bearer $DEENGEN_API_KEY"
The answer, as returned on 2026-11-12:
{
"data": [
{
"input": "AAPL",
"key": "AAPL",
"type": "stock-us",
"symbol": "AAPL",
"name": "Apple Inc.",
"rating": {
"band": "PASS",
"label": "Passes screen",
"score": 90,
"method": "3.0"
},
"summary": "Apple Inc. passes the screen with 90 out of 100: it is in the S&P 500 Shariah index and its debt and cash ratios are under 33%.",
"ratios": {
"debtToAssets": 19.8,
"cashToAssets": 14.02,
"interestIncomeToRevenue": null,
"unit": "percent"
},
"ethics": {
"status": "assessed",
"score": 100,
"band": "clear",
"flags": []
},
"url": "https://www.deengen.com/stocks/AAPL"
},
{
"input": "bitcoin",
"key": "bitcoin",
"type": "coin",
"symbol": "BTC",
"name": "Bitcoin",
"rating": {
"band": "PASS",
"label": "Passes screen",
"score": 81,
"method": "3.0"
},
"summary": "Bitcoin passes the screen with 81 out of 100, and every one of the five criteria scores 60 or more.",
"rulings": {
"tally": {
"permit": 5,
"conditional": 2,
"prohibit": 6
},
"n": 13
},
"scMalaysia": "2020-07-20",
"ethics": {
"status": "not_assessed",
"score": null,
"band": null,
"flags": []
},
"url": "https://www.deengen.com/coins/bitcoin"
}
],
"meta": {
"asOf": "2026-11-05",
"method": {
"screen": "3.0",
"screenDate": "2026-11-07",
"ethics": "1.0"
},
"disclaimer": {
"id": "dg-v1",
"version": "2026-11-10",
"text": "The DeenGen Shariah screen and ethics score are published methods, not fatwas. Positions are the issuing bodies' own words. Education, not financial advice: no buy, sell or hold call. Capital is at risk."
},
"attribution": "Data: DeenGen (deengen.com)",
"requested": 2,
"found": 2,
"notFound": 0
}
}
Check /api/v1/status (no key needed) to see whether keys are open and when the data was last updated.
Keys and auth
Send your key in the Authorization: Bearer <key> header. X-API-Key: <key> works too. Keep keys on your server: a key in a public web page can be copied and used against your quota.
Free keys are sent by email, one per address per day; asking again on the same day does not create a second key. The index, /status, /openapi.json and /methodology need no key.
Report a leaked key. Write to admin@deengen.com from the address the key was sent to and quote the key id: the 12 characters shown in the key email and as data.key in /usage. Do not send the key itself. We revoke it, after which it answers 401, and you can request a new key the next day.
Response shape
Every success has the same two parts: data holds the result, meta says where it came from. Show the attribution line wherever you display the data.
{
"data": { ... },
"meta": {
"asOf": "date of the underlying data",
"method": { "screen": "3.0", "screenDate": "2026-11-07", "ethics": "1.0" },
"disclaimer": { "id": "dg-v1", "version": "2026-11-10", "text": "..." },
"attribution": "Data: DeenGen (deengen.com)"
}
}
Errors
Errors keep the same envelope with an error object instead of data: {"error": {"code", "message", "field", "docs"}, "meta": {...}}. Build on code, not on the message text.
| HTTP | code | Meaning |
|---|---|---|
| 400 | missing_parameter, invalid_parameter | A required value is missing or out of range. field names it. |
| 400 | too_many_symbols | More symbols than your plan screens in one request (Free 10, others 50). |
| 400 | terms_required, invalid_token | POST /keys only: the terms were not accepted, or the form token is missing, too fresh or expired. |
| 401 | unauthorized | Missing, invalid or revoked key. |
| 404 | not_found | No coin or stock matches. Try /search. |
| 404 | unknown_endpoint | The path does not exist in v1. |
| 403 | forbidden_origin | POST /keys only: the form was posted from another site. |
| 405 | method_not_allowed | Use GET, or POST where the reference shows it. |
| 415 | unsupported_media_type | POST /keys only: send Content-Type: application/json. |
| 422 | ratio_unavailable | No purification ratio is known for this asset. Pass ratio. |
| 429 | rate_limited | Too many requests this minute. Wait Retry-After seconds. |
| 429 | quota_exceeded | Monthly units used up. Resets on the first of the month (UTC). |
| 429 | too_many_requests, key_already_sent | POST /keys only: too many key requests from one network, or a key already went to that address today. |
| 500 | server_error | Our fault. Quote the X-Request-Id header if you write to us. |
| 502 | mail_failed | POST /keys only: the key email could not be sent. Try again in a few minutes. |
| 503 | not_open_yet | POST /keys only: free keys are not open on this deployment. Join the waitlist. |
A missing key, as returned:
{
"error": {
"code": "unauthorized",
"message": "Missing, invalid or revoked API key. Send Authorization: Bearer <key>. Get a free beta key at https://www.deengen.com/developers.html#get-key",
"docs": "https://www.deengen.com/api-docs.html#errors"
},
"meta": {
"asOf": "2026-11-05",
"method": {
"screen": "3.0",
"screenDate": "2026-11-07",
"ethics": "1.0"
},
"disclaimer": {
"id": "dg-v1",
"version": "2026-11-10",
"text": "The DeenGen Shariah screen and ethics score are published methods, not fatwas. Positions are the issuing bodies' own words. Education, not financial advice: no buy, sell or hold call. Capital is at risk."
},
"attribution": "Data: DeenGen (deengen.com)"
}
}
Plans and limits
A request costs one unit. /screen costs one unit per symbol. /zakat, /search, /logos and /usage cost nothing but count toward the per-minute rate. Each answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Quota-* and X-DeenGen-Units headers, and a 429 adds Retry-After in seconds; /usage shows the month so far.
| Plan | Status | Units / month | Per minute | Bulk screen | Use |
|---|---|---|---|---|---|
| Free | Open beta | 1,000 | 10 | 10 symbols | Personal, non-commercial, with attribution |
| Starter | Coming soon | 25,000 | 60 | 50 symbols | Commercial with attribution. Planned to come with DeenGen Pro. |
| Pro | Coming soon | 250,000 | 300 | 50 symbols | Commercial display. Planned to come with Pro Advisor. |
| Enterprise | Coming soon | By agreement | By agreement | 50 symbols | White label and data licensing |
Paid plans are not on sale: their quotas and prices are planned figures, and you can join the waitlist on the developers page. During the beta the monthly count is kept per server, so it is approximate; the per-minute rate is enforced on every server.
Caching
Successful GET answers carry a weak ETag. Send it back as If-None-Match and an unchanged answer returns 304 with no body (it still counts as a request). Keyed answers are Cache-Control: private, max-age=60; /status, /methodology and the spec are public for five minutes. Cross-origin GET is allowed from any site.
Data policy
The API returns what DeenGen produces: screen bands and scores, ratios we compute from companies' SEC filings, the SC Malaysia list status, rulings with their source and date, purification ratios and ethics flags. It does not resell market data, so there are no prices, market caps or market-cap ranks in any answer. The coin list covers the largest 1,000 coins and is ordered by id; no figure or rank behind that selection is included, and reason texts never quote a market value. Logos are for display next to our data only.
Nothing here is a fatwa or advice to buy, sell or hold. Scholars differ, and capital is at risk.
Ethics score
A separate layer from the Shariah screen. It looks only at company conduct in dated public records: the UN OHCHR settlements database, US arms sale notifications, FEC filings by the company or its PAC, an interest-based core business from SEC filings, and US Justice Department resolutions. It never uses nationality, religion, ethnicity or anyone's personal donations. Campaign lists are context and never change the score.
Each flag shows its tier (T1 official finding, T2 documented research at half weight, T3 context at zero), a one-line finding, the source, a link and the date. coverage says which criteria were checked for that asset, so a missing flag is never read as a clean record when the check was not run. Companies can reply or correct a record at admin@deengen.com; replies are published next to the flag. Full method: /methodology.
Clients
Two single-file clients with no dependencies, one for JavaScript (Node 18+ and browsers) and one for Python 3.8+. They are source files to copy into your project, not published packages. They live in the repository under tools/api/clients/ with a README, and will be linked here as downloads on GitHub once the repository is public; until then, ask at admin@deengen.com.
Each exports one class, DeenGen. After importing it:
// JavaScript
const dg = new DeenGen(); // reads DEENGEN_API_KEY
const { data, meta } = await dg.screen(["AAPL", "bitcoin"]);
console.log(data[0].rating.band, meta.attribution);
# Python dg = DeenGen() # reads DEENGEN_API_KEY res = dg.screen(["AAPL", "bitcoin"]) print(res["data"][0]["rating"]["band"], res["meta"]["attribution"])
Both raise a typed error with code, status and the seconds to wait after a 429, expose the rate-limit headers of the last call, and wait and retry once when the per-minute limit is hit.
Terms
By asking for a key you accept the API terms (version 13 Nov 2026). In short:
- The free beta is for personal, non-commercial use. Commercial use needs a paid plan, and those are not open yet.
- Show "Data: DeenGen" with a link to deengen.com wherever you display the data.
- Show the disclaimer from
meta.disclaimer, or a link to it, next to screen results and ethics flags. - Do not resell, republish or mirror the raw data, and do not rebuild the dataset by bulk download.
- Stay within the limits, with one key per person.
- The beta comes as it is. Fields, limits and endpoints can change; breaking changes are listed in the changelog below.
Loading the reference...
Changelog
| 2026-11-13 | v1.1, free beta. Free keys by email from the developers page (POST /keys). New /status. ETag and If-None-Match on GET answers. Changed: /coins is now ordered by coin id instead of market value, and coin reason texts no longer quote a market value, so no third-party market figure can be read from an answer. Single-file JavaScript and Python clients. |
| 2026-11-10 | v1.0: one envelope for every answer (data + meta), error codes, plans with monthly units, /screen, /ethics, /search, /logos, /purification, /zakat, /rulings/{asset}, /usage, /methodology, OpenAPI 3.1 spec. Removed the market-cap rank from coin answers and the fund weight from stock answers. |
| 2026-11-05 | v1 preview: coins, one coin, US and Bursa stocks, rulings. |