Behavioural fraud-risk scoring and cooling-window holds for Nigerian transfers.
Transfers that fit the customer's own habits go straight through. The one that doesn't is checked, or held where the customer can still cancel it.
Problem โข Solution โข Agents โข Status โข Architecture โข Setup โข Demo Guide โข API โข License
Every bank's fraud system kicks in after the user hits send. By then, the scammer has already won.
In the modern digital banking eraโparticularly across emerging African markets like Nigeriaโscams no longer happen inside the banking apps themselves. The technological perimeters (2FA, biometric logins, hardware tokens) are generally secure against brute force. Instead, the human is the vulnerability.
Scams happen on WhatsApp, phone calls, and cloned websites in the five minutes before the transaction. They manifest as:
- Social Engineering & Impersonation: Scammers posing as family members in distress.
- Fake officials and fake investments: "your account is under review", "double your money by Friday".
- Urgency Scripts: Crafted messages in English and Nigerian Pidgin designed to trigger panic and bypass rational thought.
- Account takeover and mules: A stolen login, a new device, and money routed to an account the customer has never paid.
Because the user themselves is convinced to authorize the transfer, traditional rule-based fraud systems (which only look for credential stuffing or geographic anomalies) fail. They see a legitimate user, on a legitimate device, entering a legitimate OTP.
To the bank, it looks like a perfect transaction. To the user, it is a catastrophic loss.
Fable is an API that a bank, wallet, payment service provider or lender calls before a transfer is sent.
It compares the transfer with that customer's own history: who they pay, how much, when, from which device and where. KYC answers "is this the right person?" once, at onboarding. Fable asks, on every transfer, "does this look like something this customer does?", which is the question a social engineering scam fails.
Transfers that fit go through with no extra step. One that doesn't gets a PIN, passkey or code check, or a hold the customer can cancel, before the money leaves.
- Behavioral over Identity: We assume the user is logged in perfectly. We secure their intent, not just their credentials.
- Security Without Friction: Safe users get fewer prompts than today, not more.
- Context, Not Just Payload: Device, location, session timing, typing and paste signals, recipient history and narration.
- Transparency by Design: Every intervention is explained in plain English. No black-box rejections.
- Containment over Cancellation: When a customer insists on a blocked transfer, it is held for a cooling window instead of sent, and scoring never fails open.
Three parts, each with one job, deciding inside a 200ms budget before the transfer goes to NIP. Copilot, Shield and Ghost are live today; Watch is planned.
| The Personalization Engine | The Threat Defense | The Containment Layer |
|
Always On, Passive. Learns each customer's usual amounts, recipients, hours, devices and places from their history. A customer with no history yet is compared with the institution's customers as a whole. Example: Ada paying her landlord on the 1st of the month. |
Real-Time Interception. Scores the transfer against that baseline: amount, recipient, timing, device, location, session, typing, channel, NIP codes and scam-script narrations (e.g. "urgent help abeg"). Every flag or block comes with a plain-language reason, from a template, or from Claude or GPT-4o when configured, without blaming the customer. |
Blast-Radius Containment. If a customer insists on a blocked transfer, Ghost holds it for a cooling window (5 to 15 minutes by default, set per institution). The customer can cancel for free, or release it only with stronger proof. Live, the bank keeps the funds and acts on Fable's webhooks. |
Shield adds up its signals into a risk score from 0.0 to 1.0, then softens it slightly for customers with a long clean record:
- Amount anomaly: how far above the customer's own baseline, with tiers past 10x, 25x and 50x. With no history, the amount itself is priced in tiers from NGN 100k to NGN 20m.
- Recipient and timing: new recipient, time of day on the device clock, timezone mismatch.
- Channel and rail: channel risk weights informed by NIBSS fraud data (internet banking highest, branch lowest) and NIP response codes.
- Social engineering: narration matched against the Nigerian scam-pattern library (deliberately a weak signal).
- Device, location and session: unrecognised device, new city or country, a large transfer right after login.
- Behavioural biometrics: pasted account numbers, near-zero hesitation.
- History and velocity: how far the amount and hour together sit from the customer's own past transfers, bursts of transfers, recent failed verifications.
Decisions are PASS, FLAG or BLOCK. The cutoffs default to 0.5 and 0.8 and are tuned per channel. Shield never fails open: if scoring throws, it returns a conservative FLAG. Weights live in governed engine versions: every scoring change goes through approval with a cooling-off period, a backtest and a shadow run (two-person approval when there are two owners), and every decision records the version that made it. Full weights are in the scoring docs and docs/ENGINE-GOVERNANCE.md.
When a flagged transfer needs proof, the step-up engine picks the lightest factor that holds: PIN, device passkey, passkey plus a one-time code (email or SMS), or passkey, code and PIN together. Releasing a Ghost hold always costs one tier more than the transfer itself, and only factors set up before the decision count.
| Status | What |
|---|---|
| Live | Per-customer scoring with Copilot and Shield; per-customer data export and erasure, scheduled retention, coarse location and a customer location switch; step-up with PIN, passkeys and one-time codes; Ghost holds with release, cancel, expiry and "ask my bank to release"; signed webhooks with a durable outbox; the institution console (review queue, customers, risk policy, roles, imports, audit, Ask Fable); the operator platform with approval with a cooling-off period for keys and engine changes (two-person approval when there are two owners); the sandbox app and sandbox inbox |
| Live when configured | SMS codes and alerts through Termii or Africa's Talking (including its free sandbox); AI-written explanations through Anthropic or OpenAI; email through your mail server |
| In progress | First-transfer amount weights and the new anomaly model ship as a draft engine version for an owner to propose, shadow and promote |
| Planned | Watch (monitoring between transfers); cross-institution intelligence (each institution's data is strictly its own today); a face or liveness check through a KYC provider; published SDK packages on npm and PyPI |
One repository: a Python (FastAPI) scoring service and a Next.js frontend.
fable/
โโโ api/ # ๐ง FastAPI backend (scoring, holds, console API)
โ โโโ main.py # App entry point: middleware, routers, startup
โ โโโ core/ # Plumbing: config, database and migrations, sessions,
โ โ # tenancy and roles, password and API-key hashing
โ โโโ services/ # Domain logic: ledger, audit log, branding, notifications,
โ โ # risk policy, signed webhooks, scheduler, email and SMS
โ โโโ agents/
โ โ โโโ copilot/ # Baseline profiling and the analyst assistant
โ โ โโโ shield/ # Scoring, step-up and assurance, explanations
โ โ โโโ ghost/ # Containment holds and release
โ โโโ intelligence/ # Scam patterns and fraud context
โ โโโ middleware/ # API-key auth, rate limiting, latency
โ โโโ models/ # Request and response schemas
โ โโโ routers/ # /v1/shield, /v1/ghost, /v1/review, /v1/team, /v1/webhooks, /auth, ...
โ โโโ scripts/ # Operator tools: rename or remove institutions, PIN reset, admin email
โ โโโ tests/ # Scoring, endpoint, tenancy, hold, console-workflow and migration tests
โ โโโ eval/ # Offline evaluation harness for labelled transactions
โ โโโ Dockerfile # Production image
โ โโโ docker-compose.yml
โ โโโ ruff.toml, pytest.ini # Tool settings (import sorting, tests)
โ โโโ requirements.txt # What the app needs
โ โโโ requirements-dev.txt # Plus pytest and Ruff, for tests and linting
โ
โโโ src/ # ๐ป Next.js 16 Frontend
โ โโโ app/
โ โ โโโ (marketing)/ # Public site: home, platform, pricing, privacy, terms
โ โ โโโ dashboard/ # B2B institution console
โ โ โโโ demo/[institution]/ # Mobile-first demo bank, one per institution
โ โ โโโ docs/ # Public documentation
โ โโโ content/docs/ # The documentation source (Markdown)
โ โโโ components/ # UI (Tailwind)
โ โโโ lib/fable/ # Browser client: API calls, fingerprint, geolocation, passkeys
โ โโโ proxy.ts # Console route guard (Next 16's renamed middleware)
โ
โโโ e2e/ # Playwright browser tests for the sandbox app and console
โ
โโโ sdk/ # Reference clients for Node and Python (no dependencies)
โโโ docs/ # Internal guides: deployment, system guide, plans
โโโ public/ # Static assets and brand logos
โโโ LICENSE # Proprietary, all rights reserved
- Backend API: Python 3.12, FastAPI, SQLite
- AI Integration: Anthropic Claude then OpenAI GPT-4o for plain-language explanations and the analyst assistant, both optional with a deterministic fallback; a nearest-neighbour anomaly model on each customer's own history (the retiring Isolation Forest uses scikit-learn)
- Identity: WebAuthn passkeys (
py_webauthn), hashed PINs, one-time codes by email or SMS - Frontend App: Next.js 16 (App Router), React 19, Tailwind CSS v4
- UI Components: Phosphor Icons, Sonner, react-markdown
- Third-party services: Paystack (account-name resolution), Google Maps Geocoding, ipapi.co, OpenStreetMap Nominatim and BigDataCloud (location), SMTP (email), Termii or Africa's Talking (SMS), all optional
- Hosting: Vercel (frontend), a Docker Compose deployment on a VPS (backend). See docs/DEPLOYMENT.md
Run the API and the frontend locally.
- Node.js 20+ and
pnpm(ornpm) - Python 3.12+
- Optional: an Anthropic or OpenAI key for AI-written explanations. With no key set, Shield still returns full scores and signals and falls back to a local template.
The backend runs on port 8000 locally and handles all scoring logic. (The Docker image listens on 8010; see the deployment guide.)
cd api
# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements-dev.txt # the app's requirements, plus pytest
# Environment (every key is optional for local use)
cp .env.example .env
# Set a session secret, or console sign-ins reset every time the API reloads:
# python -c "import secrets; print(secrets.token_urlsafe(48))" -> FABLE_SESSION_SECRET in .env
uvicorn main:app --port 8000 --reload๐ Interactive API documentation is generated at http://localhost:8000/docs. Run the tests with pytest, and the browser tests from the repository root with pnpm test:e2e. On a machine where Windows blocks compiled Python packages, run both on Linux in Docker instead: see docs/DEPLOYMENT.md, section 11.
The Next.js frontend runs on port 3000 and hosts the marketing site, the console and the demo bank.
# In a new terminal at the repository root
pnpm install
# Point the frontend at the API (it defaults to http://localhost:8000)
echo "NEXT_PUBLIC_FABLE_API_URL=http://localhost:8000" > .env.local
# Restart `pnpm dev` after changing it: the security headers are built at startup.
# Optional: add PAYSTACK_SECRET_KEY=sk_test_... for real account-name resolution
pnpm dev๐ The platform is now at http://localhost:3000. Data lives in api/fable.db (SQLite), created on first run.
If the API is unreachable, the sandbox app says so and sends nothing; it never makes a decision on the device. http://localhost:8000/health shows the database, background jobs and webhook outbox.
Fable ships a sandbox banking app. Each institution gets its own at /demo/{institution}, open to its console members, using the test customers it imports or adds. There is no built-in demo data: import a few test customers with history shaped like a trader, a salaried worker and a student (CSV templates are in Settings > Data), then try the scenarios below. See the quickstart.
Per-customer baselines in action.
- Open
http://localhost:3000/demo/{your-institution}and pick the trader from the customer switcher. - Send โฆ250,000 to a new 10-digit account. For a trader who moves that much every week, it passes silently.
- Switch to the student and send the same โฆ250,000. It is many times her normal, so Shield asks for a check or stops it. The exact result depends on the history you imported.
Shield catching a social-engineering shape.
- As the student, send โฆ500,000 to a new account over Web (internet banking).
- Narration:
urgent help abeg(matches the Pidgin urgency script). - Result: Shield intercepts it and explains, in plain language, why.
Containment when the user ignores the warning.
- On the blocked screen, choose to send anyway.
- Nothing goes to the recipient. Ghost holds it in a cooling window and tells the customer on another channel (in the sandbox, the sandbox inbox).
- Cancel keeps the money in the account. Release demands a stronger factor than the transfer did, set up before the transfer. A customer without one can ask the bank to release it from the console.
Sign in at /dashboard/login and see the same transfers from the institution's side, scoped to that institution only.
| Page | What it is for |
|---|---|
| Overview | Live decisions, money kept from fraud, decision time, and what needs review |
| Review queue | Every flagged or blocked transfer as a case: assign, add notes, escalate, and resolve as fraud or legitimate. Labelling a case never moves money |
| Transactions | The full log with 7, 30 and 90 day ranges and CSV export |
| Customers | Each customer's baseline, verification status, history and cases |
| Agents, Insights | What Copilot, Shield and Ghost are doing, and which scams and signals recur |
| Compliance | The audit trail, an incident log, CSV export and a printable board report |
| Settings | Profile, branding, risk policy (your own thresholds and hold windows), team and roles, data imports, API key and webhooks, and the go-live checklist |
| Ask Fable | An analyst assistant that answers from the institution's own figures, with customers pseudonymised before any AI provider sees a question |
Fable staff run a separate operator platform at /operator (password plus authenticator, with roles): they create institutions empty, follow their setup, set Ask Fable's limits, manage integration keys with two-owner approval (see docs/SECRETS.md), propose, shadow and promote scoring engine versions, and read the full audit log.
Console users have a role, enforced by the API: owner (everything), analyst (works the review queue) or viewer (read only).
Institutions call one endpoint before sending a transfer. A clean transfer is that one call; a flagged one adds a verification step. Full reference: the public docs at /docs on the site (source in src/content/docs) and the OpenAPI spec at /docs on the API host.
Authenticate with X-API-Key: fbl_live_....
Request:
{
"user_id": "usr_44210",
"transaction": {
"amount": 150000,
"currency": "NGN",
"recipient_account": "0123456789",
"recipient_bank_code": "058",
"recipient_name": "ADEOLA MUSA",
"channel": "mobile_app",
"narration": "urgent help abeg"
},
"device": { "fingerprint_id": "fp_9c1e4b7a", "timezone": "Africa/Lagos" },
"context": { "session_duration_seconds": 14, "paste_detected": true },
"client_reference": "txn_8f2ac1"
}Response:
{
"risk_score": 0.64,
"risk_level": "MEDIUM",
"action": "FLAG",
"signals": [
"amount_anomaly: 12x above your baseline (+0.28)",
"new_recipient: first transfer to this account (+0.2)",
"scam_pattern: urgency script (+0.13)"
],
"explanation": "This is much larger than your usual transfers, to someone you have never paid before...",
"decision_ms": 48.2,
"latency_ms": 51.7,
"explanation_source": "template",
"transaction_id": "txn_a1b2c3d4e5f6"
}POST /v1/ghost/create- Hold a blocked transfer the customer insists on, by itstransaction_id.POST /v1/ghost/{id}/cancel- End the hold; the money stays with the customer. No proof needed.POST /v1/ghost/{id}/confirm- Release the transfer. Requires a step-up token.POST /v1/ghost/{id}/request-release- Ask the bank to release it instead.POST /v1/stepup/requirement- Which factor does this decision need?GET /v1/copilot/transparency/{user_id}- Everything Fable has learned about a customer's baseline.
| Guide | What it covers |
|---|---|
| Public docs | Overview, quickstart, scoring, identity assurance, API reference, integration guide |
| sdk/README.md | Node and Python reference clients, including webhook verification |
| docs/SYSTEM-GUIDE.md | How the whole system fits together, and its honest limits |
| docs/DEPLOYMENT.md | Vercel plus a Docker Compose backend on a VPS, updates, backups and maintenance scripts |
| docs/SECRETS.md | Integration keys and settings managed from the operator console |
| docs/ENGINE-GOVERNANCE.md | How scoring weights are changed, approved, shadowed and promoted |
| docs/PIN-RECOVERY.md | Clearing a customer's PIN, and backing up the database safely |
| api/eval/README.md | Measuring Shield's weights against labelled outcomes |
The backend stores everything in SQLite (api/fable.db), with the schema and in-place migrations in api/core/db.py. Core tables: customers and transaction_history (imported), transactions (decisions, with review state, outcome and engine version), case_notes, ghost_containers, institutions, institution_settings (risk policy), institution_branding, admins (with roles), api_keys, webhooks, webhook_outbox and webhook_deliveries, accounts and ledger_entries (sandbox balances), user_security and user_credentials (PIN hash and passkey public keys), stepup_challenges and stepup_tokens, device_profiles and customer_devices, user_locations, notifications, sandbox_inbox, engine_versions, job_runs and audit_log. Every row is scoped to an institution.
Fable is proprietary software. Copyright (c) 2026 Fable. All rights reserved.
The source is visible for review and evaluation only. Copying, forking for reuse, redistributing, or using any part of it (code, scam-pattern data, designs, or branding) in another project, product, or submission is not permitted without written permission. See LICENSE for the full terms. How the hosted platform itself is governed is in the site's Terms and Privacy pages.
Contributions are accepted from invited collaborators only. To request permission to use anything here, contact the owner at github.com/kenzycodex.