The pre-trade Shariah guardrail: a contract for AI agents that touch a Muslim's orders

Why a contract and not a feature

Screening services already answer "is this halal?". The gap is not the answer, it is the shape of the answer when the caller is software about to act on it. A confident paragraph is fine for a person reading a stock page. It is dangerous as the input to a function called place_order, because the agent will parse it, and whatever it parses becomes the rule.

The contract fixes the shape so that an agent cannot read a screen as an authority it does not have. It is written against the seven commitments of the Standard: it declines where it should (review), it dates every answer, it hands off to a person on every outcome, it logs in a form a third party can verify (the receipt), and it names who is accountable.

The three outcomes

The decision table

The outcome depends only on the published verdict and whether it is current. There is no hidden weighting.

A sell always passes. The response still says whether purification may apply to the gain, so the agent can offer the calculation; it never nets it out on its own.

The request and the response

One call, before the order:

GET https://halalscreener.app/api/v1/guardrail?symbol=AAPL&action=buy
Authorization: Bearer <api key>

The same check is exposed to assistants as the MCP tool pretrade_check (symbol, action). The response:

{
  "guardrail": {
    "version": "1.0",
    "action": "buy",
    "decision": "pass",
    "reasonCode": "passes_screen",
    "reason": "Apple Inc. passes the AAOIFI Standard No. 21 screen (screened 10 Oct 2026; methodology v2.3).",
    "nextStep": "Present this result and its receipt to the account holder for approval before any order is placed. The screen passes the security; it does not place the order.",
    "humanApprovalRequired": true,
    "purificationApplies": true,
    "autonomousExecution": "not_permitted"
  },
  "verdict": { "symbol": "AAPL", "verdict": { "status": "halal", "grade": "A" }, "methodology": { "standard": "AAOIFI Standard No. 21", "version": "v2.3" }, "screenedAt": "2026-10-10T00:00:00.000Z", "freshness": "fresh", "auditHash": "3f9c…e1", "notTradeGate": true },
  "receipt": { "jwt": "eyJhbGciOiJFZERTQSIs…", "kid": "hsg-1a2b3c4d5e6f", "verifyUrl": "https://halalscreener.app/api/v1/guardrail/verify", "keysUrl": "https://halalscreener.app/.well-known/halalscreener-guardrail.json" }
}

Five fields are mandatory in any implementation of this contract: decision, reasonCode, reason, nextStep and humanApprovalRequired, which must always be true. An implementation that returns a bare boolean, or a score without a decision, does not meet the contract.

The receipt

The receipt is a compact JSON Web Token (RFC 7519) with header alg: EdDSA, typ: halalscreener-guardrail+jwt and a key id. Its claims are the issuer, the symbol, the time issued, a unique receipt id, the guardrail version, the action, the decision and reason code, the published status and grade, the verdict's audit hash, the methodology and its version, the screening date and the freshness flag. Paid responses add the purification share.

Verification is offline: fetch the JWK Set once from the published key address, pick the key whose id matches, and verify the signature with any library that supports EdDSA (RFC 8037). A convenience endpoint does the same check for people without a library to hand.

What a valid receipt proves: that this issuer ran this check on this symbol at this time, that these were the inputs, and that nobody edited it since. What it does not prove: that the verdict was correct. A wrong verdict signed is still a wrong verdict. The audit hash inside it lets a reviewer reproduce the verdict from the same stored figures; the methodology version tells them which rules applied.

Webhooks: the other half

A check before the trade is half the job. A holding's verdict can change a month later when a new filing lands. The contract therefore includes a push: a subscribed endpoint receives a signed verdict.changed event within the hour of a status flip, with the previous and new status, the date, the stock page and a ready guardrail call for the held position (action=hold). Optionally, verdict.updated reports a change in the figures without a change in status.

Delivery rules that matter for an agent:

1. Signed. A header carries a timestamp and an HMAC-SHA256 over the timestamp and the raw body, keyed with a secret the subscriber holds. Reject anything older than five minutes.
2. In order, stopping at the first failure. Events go out oldest first, one per request. If the endpoint does not acknowledge one, delivery stops there and resumes next hour, so no change is skipped.
3. Idempotent. Event ids are deterministic (a hash of endpoint, type, symbol and time), so a retry carries the same id and the receiver can deduplicate.
4. Self-limiting. An endpoint that fails ten hours in a row is switched off and its owner told, rather than hammered.

The five rules every implementation keeps

1. Never execute. The guardrail does not place, cancel or block orders, and says so in the payload (autonomousExecution: not_permitted).
2. Always hand off. Every outcome requires a person's approval. There is no outcome that an agent may act on alone.
3. Date everything. Each response carries the screening date, the methodology version and a freshness flag; a stale verdict is a review, not a pass.
4. Decline honestly. Doubtful, withheld and uncovered are reviews. The contract has no outcome for "probably".
5. Prove it. The receipt is verifiable by third parties without trusting the agent's own log.

These map onto commitments three (dating), four (decline), five (hand-off), six (logging) and seven (accountability: the issuer is named in every receipt) of the Standard.

Adopting it

If you run an order flow (a broker, a robo-adviser, a copy-trading platform): call the guardrail before the order ticket is confirmed, store the receipt beside the order, show the person the reason in their language, and subscribe an endpoint to verdict changes for the positions you hold. Your compliance desk can verify any receipt without asking anyone.

If you build agents (MCP tools, assistant plug-ins, trading bots): call pretrade_check before you suggest, prepare or stage any order; relay reason and nextStep verbatim; never map pass to an automatic buy.

If you run a screening service: implement the same five mandatory fields and the three outcomes, publish your key set, and tell us; we will list implementations here.

Limits, stated plainly

Verdicts are batch-screened from filings, not real-time; the freshness flag says how old one is. Coverage is what the screener covers; an uncovered security is a review, not a verdict either way. The methodology is the screener's published one; whether it satisfies a given school is for the person and their scholar, which is why the hand-off is unconditional. None of this is a fatwa, and no receipt changes that. See can AI issue a fatwa.

Changelog

• 1.0, 13 October 2026. Initial publication: three outcomes, decision table, five mandatory fields, EdDSA receipts, signed webhooks. Reference implementation live at halalscreener.app.