F.R.E.D — Open SPEI Detection Engine

Inspiration

In Mexico, SPEI (Sistema de Pagos Electronicos Interbancarios) moves trillions of pesos every year, settling transactions irreversibly within seconds. While speed and convenience have modernized Mexican payments, they created a devastating blind spot: Authorized Push Payment (APP) fraud and social engineering coercion.

When a grandmother or small business owner is pressured on the phone by a fake banking executive, a virtual extortionist, or tricked into remote screen-sharing, they authenticate legitimately using their own passwords and biometrics. Traditional anti-fraud and identity tools ask: "Is this the authorized customer?" - to which the answer is YES.

We realized the financial system was asking the wrong question. We were inspired to build a solution that asks: "Is this authenticated customer currently being manipulated or coerced before this money leaves the bank?"

What it does

F.R.E.D (Fraude Detection Engine) is a real-time, pre-submission prevention API designed for banking institutions and interbank rail operators (like Banco de Mexico). It intercepts coerced and fraudulent transfers prior to settlement without arbitrarily freezing accounts or generating false alarms for legitimate high-volume merchants (taquerias, gyms, suppliers).

Key capabilities:

• Multi-Factor Corroboration Engine: Synthesizes signals across three distinct dimensions:
  1. ATO (Account Takeover): Unrecognized device fingerprints, anomalous IP/geographic routing, recent password/OTP resets, and nocturnal access.
  2. Intent (Coercion & Manipulation): Transferred amount vs. 90-day baseline, severe liquidity drain (>80% of balance), beneficiary registered minutes prior, regulatory MTU structuring (staying just below the 1,500 UDIs ≈ $12,800 MXN threshold), limit elevation bursts, and mobile SDK telemetry indicating an active telephone call or remote desktop/screen-sharing.
  3. Recipient Network: First-time destination CLABE/institution for that payer, plus cross-payer rapid fan-in detection (multiple distinct payers funding the same CLABE in 24 hours).
• Explainable Friction: Emits three auditable verdicts: allow, challenge (step-up biometrics), and pause (15-minute cooling-off period or verified bank callback).
• Human-Centered AI Guidance: Uses Gemini (gemini-3.6-flash) with automatic fallback to deterministic templates to generate calm, empathetic, and actionable fraud warnings in Spanish directly inside the user's mobile banking app (e.g., "Banks never ask you to transfer funds to protect an account. Hang up this call.").

How we built it

We designed F.R.E.D as a clean, decoupled API as a Product backed by standard cloud-native tooling:

• Backend & API (apps/api): Built with Python 3.11+, FastAPI, SQLAlchemy 2.0, and Pydantic v2. All monetary values are strictly modeled using Numeric(18, 2) (never floats). Migrations are tracked via Alembic. Endpoints are protected with institution-level X-API-Key authentication.
• Deterministic FeatureStore: Computes 90-day historical aggregates, velocity windows (1h, 24h), and timing deltas strictly relative to a simulated transaction timestamp (as_of), completely decoupling feature engineering from wall-clock time.
• High-Fidelity Stream Generator & Bank Player (apps/generator): Simulates 52 realistic personas (normal consumers, small businesses, targeted coercion victims, and ATO targets). It feeds historical ledger events, calls /v1/evaluate on active transfers, and models customer decisions (with an explicit, declared cancellation assumption p = 0.85 when shown clear friction) while keeping hidden ground-truth labels isolated in its own process.
• Evaluation & Calibration Harness (tools/evaluate): A testing harness that runs 90 days of warmup and 30 days of active simulation to evaluate value-weighted recall, p95 latency, and subgroup false positive rates.
• Zero-Logic Live Dashboard (apps/ui): Built with vanilla HTML/JS and the Classical design-system stylesheet. Polls the API and simulation status at 1 Hz with cursors to display simulated timeline progression, bank operational metrics, ground-truth protection stats, and an interactive smartphone simulator showing the customer intervention.
• Production Deployment: Containerized with Docker and Docker Compose, served live over HTTPS with Caddy at sixsevencitos.tech via GitHub Actions CI/CD.

Challenges we ran into

1. The Merchant False-Positive Dilemma (Failure Mode 4): Small businesses in Mexico (such as a local gym or taqueria) naturally receive frequent, identical transfers from many customers. A naive ruleset or weighted sum flags them as money mules immediately. We solved this by enforcing strict multi-factor corroboration: high frequency alone never triggers an alarm unless paired with anomalous rapid pass-through or payer-side coercion telemetry.
2. Timezone Pitfalls in Simulated Time: When transitioning our SQLite test database to PostgreSQL in Docker, we encountered silent 500 errors caused by datetime comparisons between timezone-naive inputs and offset-aware timestamps stored in PostgreSQL. We solved this by implementing strict UTC normalization (_to_utc) across our ingestion pipeline and feature store.
3. Keeping AI Out of the Decision Path: Financial regulators and banks cannot accept black-box LLM hallucinations when making risk decisions. We enforced a strict architectural separation: the risk decision (allow/challenge/pause) and signal weights are 100% deterministic and rule-based; generative AI (Gemini) is strictly isolated to formatting the user-facing explanation copy within a 180-character limit.

Accomplishments that we're proud of

• Sub-2ms In-Request Decision Latency: Our benchmark achieved a p50 latency of 1.03 ms and a p95 of 1.37 ms, proving that comprehensive pre-submission risk evaluation can run synchronously inside an interbank request path without degrading payment throughput.
• 100% Value-Weighted Recall with 0.0% PyME False Alarms: In our 30-day calibration benchmark (evaluating 615 active transfers), F.R.E.D intercepted 100% of social engineering and ATO attack attempts ($146,800.00 MXN in protected funds) while maintaining a 0.0% false positive rate on legitimate small merchants.
• Fully Operational Live Stack: Deployed an end-to-end working platform with an active background simulator, automated testing (23 tests passing in <0.2s), live dashboard UI, and an interactive executive presentation with WebGL Three.js animations.

What we learned

• Regulatory caps create attacker incentives: Mexico's mandatory default MTU cap (1,500 UDIs ≈ $12,800 MXN) was designed to protect consumers, but scammers adapt by structuring transfers just below the limit or coaching victims to increase their limits right before a transfer. Modeling the regulatory cap directly yielded one of our strongest detection signals.
• Transparency beats black boxes in fraud prevention: When a user is being scammed, showing an arbitrary "Risk Score: 87/100" doesn't help. Showing specific, corroborated reasons ("You registered this account 4 minutes ago while on an active call") breaks the scammer's psychological grip.
• Simulation discipline matters: Decoupling simulation time from wall-clock time allowed us to execute deterministic 90-day replays with fixed seeds (--seed 42), making anti-fraud rules testable and verifiable just like ordinary software logic.

What's next for F.R.E.D — Open SPEI Detection Engine

• Banco de Mexico Pilot & Open API Standardization: Propose F.R.E.D as a centralized, open interbank service operated at the rail level by Banxico, establishing privacy-preserving CLABE reputation signals across institutions under Open Banking principles.
• Continuous Streaming Materializer: Transition the background batch worker from HTTP polling into high-throughput streaming consumers (AWS Kinesis / Kafka / SQS) to materialize per-CLABE risk scores horizontally at national rail scale (~100M accounts).
• CEP (Comprobante Electronico de Pago) Cryptographic Standing: Integrate Banxico-sealed CEP validation so participating institutions can corroborate interbank transfers with zero exposure of underlying personal customer data.
• Cross-Bank Mule Ring Graph Analytics: Expand the recipient network scorer with lightweight graph clustering algorithms to detect multi-hop pass-through rings across newly opened digital neo-bank accounts.

Built With

• alembic
• docker
• fastapi
• httpx
• python
• remotion
• sqlalchemy