Halal Terminal API
The Halal Terminal API is the most comprehensive Islamic finance data platform available — 85 REST endpoints, 25 MCP tools, and 7 AI resources across 21…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
The Halal Terminal API is the most comprehensive Islamic finance data
platform available — 85 REST endpoints, 25 MCP tools, and 7 AI resources
across 21 categories covering Shariah screening, market data, portfolio
compliance, ETF analysis, news, SEC filings, dividends, zakat calculators,
and more. Connect via REST API or MCP (Model Context Protocol) for AI-native access.
Quick start
1. Get a free API key — no credit card required:
curl -X POST https://api.halalterminal.com/api/keys/generate \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com"}'The key is in the response and in your inbox. If the address already has a
key, the answer is HTTP 202 with no key: we email the address a link, valid
1 hour, that issues the new key by email.
2. Screen your first stock:
curl https://api.halalterminal.com/api/screen/AAPL \
-H "X-API-Key: YOUR_KEY"3. Parse the response:
{
"symbol": "AAPL",
"is_compliant": true,
"compliance_status": "COMPLIANT",
"revenue_breakdown": { ... },
"financial_ratios": { ... }
}That's it — you're screening.
Authentication
Every /api/* request must include your key in the X-API-Key header.
Exempt endpoints (no key required): GET /api/health,POST /api/keys/generate, GET /api/keys/plans, GET /api/keys/token-costs.
Everything else — including billing checkout/portal — requires the key.
Code examples
Python
import requests
headers = {"X-API-Key": "YOUR_KEY"}
r = requests.get(
"https://api.halalterminal.com/api/screen/AAPL",
headers=headers,
)
print(r.json())JavaScript (fetch)
const res = await fetch(
"https://api.halalterminal.com/api/screen/AAPL",
{ headers: { "X-API-Key": "YOUR_KEY" } }
);
const data = await res.json();Plans & token-based pricing
| Plan | Tokens / month | Price | Overage |
|---|---|---|---|
| Free | 500 | $0 | Hard block |
| Starter | 2,500 | $19/mo | $0.01/token |
| Pro | 15,000 | $49/mo | $0.008/token |
| Enterprise | 50,000 | $199/mo | $0.005/token (no hard cap) |
Each API request costs a certain number of tokens depending on the
endpoint. Lightweight reads (database search, news) cost 1 token,
standard reads (quotes, OHLC) cost 2 tokens, screening and heavy
operations cost 5–50 tokens. Free endpoints (health, education,
api-keys, billing, watchlist reads) cost 0 tokens.
See the full cost table at GET /api/keys/token-costs.
Overage: Free plan hard-blocks at the limit. Paid plans continue
at the per-token overage rate — you're never locked out. Token usage
resets monthly.
Upgrade anytime via the billing endpoint.
Common recipes
| Use case | Endpoint | Method |
|---|---|---|
| Screen a single stock | /api/screen/AAPL | GET |
| Bulk-screen an index | /api/screen-bulk | POST |
| Get real-time quote | /api/quote/{symbol} | GET |
| Check portfolio compliance | /api/portfolio/scan | POST |
| Screen an ETF's holdings | /api/etf/{symbol}/screening | GET |
| Calculate zakat | /api/zakat/calculate | POST |
| Calculate dividend purification | /api/dividends/{symbol}/purification | GET |
| Search the stock database | /api/database/search?q=apple | GET |
| Get market news | /api/news/market | GET |
| Fetch SEC filings | /api/filings/{symbol} | GET |
Error handling
All errors return a consistent JSON envelope:
{
"code": "ERROR_CODE",
"message": "Human-readable explanation",
"detail": null
}| Status | Code | Meaning |
|---|---|---|
| 400 | HTTP_400 | Bad request — check parameters |
| 401 | API_KEY_REQUIRED | Missing X-API-Key header |
| 401 | INVALID_API_KEY | Key does not exist |
| 403 | API_KEY_DEACTIVATED | Key has been disabled |
| 404 | HTTP_404 | Resource not found |
| 429 | QUOTA_EXCEEDED | Monthly quota exhausted — upgrade plan |
| 429 | OVERAGE_CAP_REACHED | Pay-as-you-go spend cap hit for this billing period (paid plans; resets at billing_period_end) |
| 500 | INTERNAL_ERROR | Server error — retry or contact support |
| 503 | SERVER_BUSY | Too many screening computations in flight — honor Retry-After (seconds) |
Rate limits & headers
Every authenticated response includes:
| Header | Description |
|---|---|
X-Request-ID | Unique request identifier for debugging |
X-RateLimit-Limit | Monthly token allowance for your plan (unlimited on unmetered plans) |
X-RateLimit-Remaining | Tokens remaining in the current billing period |
X-RateLimit-Reset | Unix timestamp when your billing period (and quota) resets |
X-Plan | Your current plan |
X-Tokens-Charged | Number of tokens deducted for this request |
X-Tokens-Remaining | Legacy alias of X-RateLimit-Remaining |
X-Tokens-Overage | Present… |
Endpoints 93
health
- GETHealth Check
/api/healthCheck API health status. Returns a simple status message confirming the API is running. This endpoint requires no authentication and is suitable for uptime…
screening
- GETAAOIFI verdict on a past date (US-listed stocks, since 2023-08-15)
/api/screen/:symbol/as-of?date=string - POSTAAOIFI verdicts for a list of (symbol, date) rows, JSON or CSV
/api/screen/as-of/batch - GETList Indices
/api/screen-bulk/indicesList available stock indices for bulk screening. Returns every index supported by the bulk-screening engine, along with an estimated ticker count and a short… - GETSource Health
/api/screen-bulk/source-healthHealth of every index constituent source. Resolves each index's upstream source and flags any whose count collapsed below its healthy floor (the failure mode… - GETBulk Status
/api/screen-bulk/statusGet the status of a bulk screening run. Returns real-time progress for the active run (or a specific run if run_id is provided), including completion… - GETList Runs
/api/screen-bulk/runsList historical bulk screening runs. Returns a paginated history of screening runs, optionally filtered by index name (e.g. "SP500") or status (e.g.… - GETCompare Runs
/api/screen-bulk/compare?run_a=string&run_b=stringCompare the results of two bulk screening runs. Identifies symbols whose compliance status changed between run A and run B, including newly compliant, newly… - POSTScreen Bulk
/api/screen-bulkTrigger a new bulk Shariah screening run. Starts asynchronous screening of all tickers in the specified index (e.g. "SP500", "DJIA"). Returns immediately with… - POSTCancel Run
/api/screen-bulk/:run_id/cancelCancel a running bulk screening job. Stops the specified run gracefully. Results already collected are preserved and can still be queried. Returns the run… - GETGet Run Results
/api/screen-bulk/:run_id/resultsRetrieve filtered, paginated results for a bulk screening run. Returns individual symbol screening results for the given run. Supports filtering by compliance… - GETGet Run Summary
/api/screen-bulk/:run_id/summaryGet an aggregated summary of a bulk screening run. Returns compliance statistics broken down by methodology and sector, overall compliance rate, and a list of… - GETExport Csv
/api/screen-bulk/:run_id/export/csvExport screening results as a CSV file. Returns a downloadable CSV containing every screened symbol, its compliance status, financial ratios, and… - GETExport Json
/api/screen-bulk/:run_id/export/jsonExport screening results as JSON. Returns the complete screening dataset for a run in JSON format, suitable for programmatic consumption or archiving. curl… - DELETEDelete Run
/api/screen-bulk/:run_idDelete a bulk screening run and its results. Permanently removes a completed or cancelled run and all associated screening results from the database. This… - GETGet Results Updates
/api/results/updates?since=stringGet screening results updated since a given timestamp. Returns only the results that have been created or modified after the since ISO-8601 timestamp. Useful… - GETGet Results
/api/resultsGet cached screening results, whole or one page at a time. Without limit (or cursor), returns every screening result currently stored in the database,… - GETGet Result
/api/result/:symbolGet the cached screening result for a single symbol. Returns the most recent Shariah compliance screening result for the given ticker symbol. Costs 1 token… - GETScreen Symbol
/api/screen/:symbolScreen a single symbol for Shariah compliance. Performs a full Shariah compliance analysis on the given ticker, including business activity screening and… - POSTScreen Symbol
/api/screen/:symbolScreen a single symbol for Shariah compliance. Performs a full Shariah compliance analysis on the given ticker, including business activity screening and…
database
- GETSuggest Symbol
/api/suggestAuto-complete symbol suggestions for a search query. Returns a ranked list of symbol suggestions that match the provided query prefix, useful for type-ahead… - GETSearch Database
/api/database/searchSearch the local database of assets with filtering and pagination. Returns a paginated list of assets matching the query string and optional filters for asset… - GETGet Stock From Database
/api/database/stock/:symbolRetrieve the database record for a single stock by symbol. Returns the stored reference data for the given symbol including name, sector, exchange, and… - GETGet Database Stats
/api/database/statsGet aggregate statistics about the database contents. Returns counts of equities, ETFs, funds, indices, and screening results, along with the number of…
market
- GETGet Ohlc
/api/ohlc/:symbolRetrieve OHLC candlestick data for a given symbol. Returns a time-series list of Open, High, Low, Close, and Volume data points for the requested symbol,… - GETGet Quote
/api/quote/:symbolGet a real-time quote for a single symbol. Returns the latest price, change, volume, and key metrics for the requested ticker symbol. curl example: curl -X… - POSTGet Quotes Batch
/api/quotes/batchFetch quotes for multiple symbols in a single request. Returns a dictionary keyed by symbol, where each value is either the quote object or null if the symbol… - GETGet Asset Full
/api/asset/:symbol/fullGet a comprehensive view of an asset combining multiple data sources. Returns a unified response containing the live quote, Shariah screening result, and… - GETGet Trending
/api/trendingList currently trending assets. Returns an ordered list of assets that are currently trending by trading activity or price movement. curl example: curl -X GET…
portfolio
- POSTPortfolio Scan
/api/portfolio/scanScan a portfolio of stocks for Shariah compliance. Set force_refresh=true to bypass cached screening data — available only for enterprise and internal plans.…
watchlists
- GETList Watchlists
/api/watchlistsList all watchlists. Returns every watchlist owned by the authenticated user, ordered by creation date. curl example: curl… - POSTCreate Watchlist
/api/watchlistsCreate a new watchlist. Creates a named watchlist with an optional initial set of symbols. Returns the full watchlist object including its generated ID. curl… - GETGet Watchlist
/api/watchlists/:watchlist_idGet a single watchlist by ID. Returns the full watchlist object including all symbols. Raises 404 if the watchlist does not exist. curl example: curl… - DELETEDelete Watchlist
/api/watchlists/:watchlist_idDelete a watchlist. Permanently removes the watchlist and all its symbol associations. Returns a confirmation object. Raises 404 if the watchlist does not… - POSTAdd Symbol To Watchlist
/api/watchlists/:watchlist_id/symbolsAdd a symbol to an existing watchlist. Appends a single ticker symbol to the watchlist. Returns the updated watchlist. Raises 404 if the watchlist does not… - DELETERemove Symbol From Watchlist
/api/watchlists/:watchlist_id/symbols/:symbolRemove a symbol from a watchlist. Removes the specified ticker symbol from the watchlist. Returns the updated watchlist. Raises 404 if the watchlist does not…
comparison
- POSTCompare Symbols
/api/compareCompare Shariah compliance across multiple symbols. Accepts 2-5 ticker symbols and returns screening results, market quotes, and stored database data for each…
reports
- GETGet Screening Report
/api/reports/screening/:symbolGenerate a Shariah compliance screening report for a single stock. Returns a comprehensive report including business activity screening, financial ratio… - POSTGet Portfolio Report
/api/reports/portfolioGenerate a Shariah compliance report for a portfolio of stocks. Accepts a list of ticker symbols and returns an aggregated report with per-holding compliance… - GETExport Csv
/api/reports/export/csvExport all cached screening results as a downloadable CSV file. Returns a CSV file containing the most recent screening results for all previously screened…
education
- GETGet Glossary
/api/education/glossaryRetrieve the Islamic finance glossary, optionally filtered by search query. Returns a list of key Islamic finance terms (e.g. Riba, Gharar, Murabaha, Sukuk)… - GETGet Methodologies
/api/education/methodologiesList all supported Shariah screening methodologies. Returns summary information for every screening methodology available in the system, such as AAOIFI, SEC… - GETGet Methodology
/api/education/methodologies/:nameRetrieve detailed information about a specific Shariah screening methodology. Returns comprehensive details for the requested methodology, including its… - GETGet Screening Criteria
/api/education/screening-criteriaRetrieve the Shariah compliance screening criteria. Returns the business activity screening rules (prohibited sectors and revenue thresholds) and financial… - GETGet Purification Guide
/api/education/purificationRetrieve the dividend purification and zakat guide. Returns educational content on how to purify investment returns that may contain a haram (impermissible)…
news
- GETGet News
/api/newsRetrieve a paginated list of Islamic finance and market news articles. Returns news articles from all configured sources, optionally filtered by source,… - GETGet Sources
/api/news/sourcesList all configured news sources. Returns every news feed source available in the system, including its category, URL, and whether it is currently enabled.… - GETGet News For Symbol
/api/news/:symbolRetrieve recent news articles for a specific stock symbol. Each article is tagged with compliance_relevance (high/medium/low) and compliance_categories…
filings
- GETGet Filings
/api/filings/:symbolRetrieve SEC EDGAR filings for a company by ticker symbol. Returns a list of filings (10-K, 10-Q, 8-K, etc.) sourced from the SEC EDGAR database. Results can… - GETGet Facts
/api/filings/:symbol/factsRetrieve XBRL company facts for a ticker symbol. Returns structured financial data extracted from the company's SEC filings via the EDGAR XBRL API. Facts are… - GETGet Provenance
/api/filings/:symbol/provenanceCompliance provenance for a ticker: which filing carried which verdict figure, and how that figure moved. For each financial filing (10-K/10-Q/20-F/40-F)… - GETGet Events
/api/filings/:symbol/eventsRetrieve the parsed 8-K event feed for a company by ticker symbol. Each 8-K (current report) filed by the company is parsed into structured events: SEC item…
dividends
- GETGet Dividend History
/api/dividends/:symbolRetrieve the dividend payment history for a stock. Returns every recorded dividend payment for the given symbol, including the payment date and per-share… - GETGet Dividend Purification
/api/dividends/:symbol/purificationCalculate dividend purification amounts for a stock. Applies the company's Shariah purification rate to each historical dividend payment and returns… - GETGet Purification Rate As Of
/api/dividends/:symbol/purification-rate?as_of=stringRate from the latest screening pass on or before as_of; falls back to the current rate (mode = fallback_current) when no pass precedes the date.
zakat
- POSTCalculate Zakat
/api/zakat/calculateCalculate zakat owed on a portfolio of stock holdings. Determines whether the total market value of the provided holdings exceeds the nisab threshold (85… - POSTCalculate Purification
/api/purification/calculateCalculate dividend purification amounts for multiple holdings at once. For each holding, looks up its Shariah purification rate and applies it to the provided…
etf
- GETGet Etf Holdings
/api/etf/:symbol/holdingsRetrieve the full list of holdings for an ETF. Returns every underlying position with its ticker, name, portfolio weight, share count, market value, and… - GETGet Etf Info
/api/etf/:symbol/infoRetrieve general fund information for an ETF. Returns metadata such as the fund name, description, inception date, expense ratio, NAV, total assets, category,… - POSTScreen Etf
/api/etf/:symbol/screenRun a Shariah compliance screening on an ETF. Screens every holding in the ETF against Shariah compliance criteria and returns an overall compliance status, a… - GETGet Etf Screening
/api/etf/:symbol/screeningRetrieve a previously cached Shariah screening result for an ETF. Unlike the POST /screen endpoint, this does not trigger a new screening run. It returns the… - POSTCalculate Etf Purification
/api/etf/:symbol/purificationCalculate the purification amount for an ETF investment. Given an investment amount and optional dividend income, computes how much money should be donated to… - POSTCompare Etfs
/api/etf/compareCompare two to five ETFs side by side. Returns per-ETF summary data (holdings count, expense ratio, compliance status, compliant/non-compliant weights) and… - POSTScreen Bulk
/api/etf/screen-bulkScreen multiple ETFs for Shariah compliance in a single request. Accepts up to 100 ETF symbols and returns each ETF's compliance status,… - GETRated-ETF directory
/api/etf/directoryDirectory of every rated ETF, with issuer and Shariah-label facets. Backs the terminal's ETF explorer. The universe is the funds that carry a rating (screened…
sukuk
- GETSearch Sukuk
/api/sukuk/searchSearch the sukuk registry by issuer, country, structure, currency, or maturity window. Returns matching instruments with a total count. - GETGet issuer sukuk
/api/sukuk/issuer/:leiReturn an issuer (by Legal Entity Identifier) and every sukuk instrument it has issued. 404 when the LEI is not in the registry. - POSTSukuk portfolio impact
/api/sukuk/portfolio-impactEvaluate a list of sukuk holdings against the registry, returning pre- and post-AAOIFI-Standard-62 compliant / non-compliant counts, the data-quality-flag… - GETGet sukuk by ISIN
/api/sukuk/:isinReturn a single sukuk instrument by ISIN, with its issuer, scholar attestations, and lifecycle events. 404 when the ISIN is not in the registry.
api-keys
- POSTGenerate Key
/api/keys/generateGenerate a free-trial API key. For an address with no active key, creates a key with 500 free tokens, returns it in the response (HTTP 200) and emails it to… - POSTRevoke Key
/api/keys/revokeDeactivate a key by its public prefix. Internal-plan callers only. Used by the admin dashboard to revoke a customer key without ever handling the raw key… - GETGet Token Costs
/api/keys/token-costsReturn the full token cost table. Lists every endpoint pattern and how many tokens each request costs. Use this to estimate usage before making API calls. No… - GETGet Usage
/api/keys/:api_key/usageDeprecated — use GET /api/auth/me instead. The path-parameter form leaks the key into Caddy/proxy access logs. The replacement reads from the X-API-Key header… - GETGet Daily Usage
/api/keys/:api_key/usage/dailyDeprecated — use GET /api/auth/me/usage/daily instead. The path-parameter form leaks the key into Caddy/proxy access logs. The replacement reads from the… - GETGet Recent Requests
/api/keys/:api_key/usage/recentDeprecated — use GET /api/auth/me/usage/recent instead. The path-parameter form leaks the key into Caddy/proxy access logs. The replacement reads from the… - POSTRegenerate Key
/api/keys/:api_key/regenerateDeprecated — use POST /api/auth/me/regenerate instead. The path-parameter form leaks the key into Caddy/proxy access logs. The replacement reads from the… - GETList Plans
/api/keys/plansList all available API plans with pricing. Returns every plan tier including name, monthly price, token limits, overage rates, and included features. No…
auth
- GETMe
/api/auth/meReturn plan, quota, and identity for the calling API key. Requires the X-API-Key header. Calling this endpoint does not consume tokens — it's safe to poll for… - GETMe Usage Daily
/api/auth/me/usage/dailyReturn per-day usage for the *calling* API key (header-only). Path-clean replacement for /api/keys/{api_key}/usage/daily. The key is read from the X-API-Key… - GETMe Usage Recent
/api/auth/me/usage/recentReturn the most recent individual requests for the *calling* API key. Path-clean replacement for /api/keys/{api_key}/usage/recent. curl example: curl -H… - POSTMe Regenerate
/api/auth/me/regenerateDeactivate the *calling* API key and issue a replacement. Path-clean replacement for /api/keys/{api_key}/regenerate. The request must carry the old key in the…
billing
- POSTCreate Checkout
/api/billing/checkoutCreate a checkout session for a plan upgrade. Requires the X-API-Key header — the calling key is the one that will be upgraded. The returned URL should be… - POSTCreate Portal Session
/api/billing/portalCreate a billing portal session for the calling key. Requires the X-API-Key header — the calling key's subscription is the one that will be managed. The…
disclaimers
- GETCanonical disclaimer registry
/api/disclaimersReturn every disclaimer the API may attach to a response, keyed by stable ID, so a client can render the long-form text or translate it locally instead of… - GETLookup a single disclaimer by ID
/api/disclaimers/:disclaimer_idLook up one disclaimer by its stable ID. 404 when the ID is unknown.
symbols
- POSTCanonical Symbols
/api/symbols/canonicalResolve symbols to the canonical form the screening engine settled on. curl example: curl -X POST "https://api.halalterminal.com/api/symbols/canonical" \ -H…
fx
- GETFx Rates
/api/fxRates for converting several currencies into one base. curl example: curl -X GET "https://api.halalterminal.com/api/fx?base=EUR&symbols=USD,GBP" \ -H…
insights
- GETHalal alternatives for a non-compliant ticker
/api/insights/:symbol/alternativesFor any non-compliant or unscreened ticker, surface up to N Shariah-compliant alternatives in the same sector ranked by how close their market cap sits to the… - GETDetect screening staleness from recent SEC filings
/api/insights/:symbol/stalenessCross-reference the symbol's last screening timestamp with its SEC filing history. Returns a screening_stale_reason when a material 8-K (debt issuance, M&A,… - GETCompliance ratio trajectory from XBRL facts
/api/insights/:symbol/trajectoryBuild a time series of the four ratios that drive Shariah compliance — debt/assets, cash/assets, liquidity/assets, interest/revenue — from the SEC XBRL… - GETAnnual cash flow and capital allocation from XBRL facts
/api/insights/:symbol/cashflowPer-fiscal-year cash flow and capital allocation from the SEC XBRL company-facts cache: operating cash flow, capex, free cash flow, dividends, buybacks, debt… - GETWhere a symbol ranks within its sector
/api/insights/:symbol/peer-percentilesRank a symbol against its sector peers on margin, ROE, growth, leverage, and valuation multiples. Each metric returns the symbol's value, its percentile…
terminal-agent
- POSTTerminal AI research agent
/api/terminal/agentDrive the terminal's AI research assistant: a tool-calling loop over the platform's own data (screening, filings, watchlist, portfolio). Restricted to the…
API details
- Base URL
https://api.halalterminal.com- Authentication
- An API key in the X-API-Key header
- Operations
- 93 operations on 90 pathsGET 65POST 25DELETE 3
- Main resources
- screening 19api-keys 8etf 8watchlists 6education 5insights 5market 5auth 4database 4filings 4
- Response formats
application/jsontext/csv- Description format
- OpenAPI 3.1.0, API version
1.0.0 - Links
- OpenAPI document · Terms of service · Support
How to test the Halal Terminal API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Halal Terminal API collection, without the publisher's secrets.
- Add your credentialsThis API uses an API key in the X-API-Key header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Health Check” (GET /api/health), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Halal Terminal API?
The Halal Terminal API is the most comprehensive Islamic finance data platform available — 85 REST endpoints, 25 MCP tools, and 7 AI resources across 21… It is listed under Finance & banking and has 93 endpoints.
Who publishes the Halal Terminal API?
It is listed from Halal Terminal's public API description (an OpenAPI document), not published by Halal Terminal on Swastik Codes. Anyone who controls halalterminal.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Halal Terminal API?
Requests go to https://api.halalterminal.com. Endpoint paths are added to this base URL.
How do I authenticate with the Halal Terminal API?
With an API key in the X-API-Key header.
How many endpoints does the Halal Terminal API have?
93 operations on 90 paths (65 GET, 25 POST, 3 DELETE). The largest groups are screening, api-keys, etf, watchlists.
Is forking the Halal Terminal API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.