Rule library overview

The rule library is the set of ready-made detection rules that ship with SpeculaPro. You do not write them from scratch: you switch on the ones that fit your business and tune their numbers — thresholds, time windows, which channels and customer segments they apply to — to match your customers.

The library describes 48 rules in nine categories, from simple “large transaction” checks to mule-network detection and mobile-money agent abuse, plus five rules for Ghanaian banks (GB1 to GB5). All of them ship today, as 55 rules in four packs: core, fraud, gh-psp and gh-bank. Fifteen more packs follow a jurisdiction’s rules: global-fatf for any country, ng-psp and ng-bank for Nigeria, uemoa-emi and uemoa-bank for the eight UEMOA states, and two each for Sierra Leone, Liberia, The Gambia, Guinea and Kenya. Their rules have their own codes (FATF1–FATF8, NG1–NG10, NGB1–NGB5, UE1–UE8, UEB1–UEB7, and SL, LR, GM, GN and KE codes) and are described on their pack contents pages rather than in the categories below. That makes 167 different rules in nineteen packs. A4 and F1 ship in both a post-event and a real-time version. Two ship in part: D5 checks shared devices but not yet shared phone or ID numbers, and F4 checks countries and merchant categories but not yet named counterparties. Pack contents lists every shipped rule with its exact defaults.

Library page or pack contents?

The category pages explain each typology: what it is, why criminals do it, and how to think about tuning. Pack contents is the exact reference for the shipped rules: their keys, parameters, defaults and expressions. Where the two differ, the pack contents page describes what actually runs.

Every default number in the library is a placeholder

The thresholds, windows and counts that come with library rules are starting points, not recommendations. They have not yet been calibrated against real Ghanaian transaction data or checked against Financial Intelligence Centre (FIC) and Bank of Ghana guidance.

Before you rely on any rule:

1. Set its parameters for your customers — a mobile money operator and a corporate bank see completely different “normal” amounts. See Tuning a rule.
2. Run the tuned version in shadow first and look at what it would have flagged.
3. Confirm regulatory thresholds (for example the cash transaction reporting threshold used by A2) with your compliance officer against current FIC guidance.

See Tuning and calibration for how to do this safely.

What a library rule is

Every rule has two parts:

• The logic — what pattern it looks for, written as an expression in CEL (Common Expression Language). For library rules, SpeculaPro writes and maintains the logic.
• The parameters — the numbers and lists the logic uses. You own these.

For example, Large single transaction (A1) has the logic “the amount is above the threshold, on one of these channels, for a customer in one of these segments”. You decide what the threshold is, which channels count and which segments it applies to.

This split is deliberate: you tune values, not logic. You never need a developer or a software release to change a threshold, and SpeculaPro can improve the logic of a library rule without overwriting your numbers.

You can still write your own rules

Library rules cover the common typologies. Rule authors can also build custom rules in the visual rule builder, or write them in CEL. Custom rules follow exactly the same versioning and approval process.

When rules run: the three modes

Each rule runs in one or more modes. The mode decides when the rule is checked and what it can do when it matches.

Mode	Short name	When it runs	What it can do
Real-time	RT	Inside the decision API, before your system approves the payment. It must answer in milliseconds.	allow, review, block or step_up (ask for extra verification such as an OTP)
Post-event	PE	Just after a transaction has been received, usually within seconds. It can look back over long history (weeks or months).	Raise an alert, add a tag, or contribute to a score (score_only)
Scheduled	SCH	On a timetable (for example nightly or weekly), looking across many transactions and many customers at once.	Raise an alert, add a tag, or contribute to a score

In plain terms:

• Real-time is for fraud: you want to stop the money before it leaves.
• Post-event is for money laundering patterns that only make sense once you look at a customer’s history — the transaction has already happened, but you need to investigate it.
• Scheduled is for patterns that no single transaction reveals: networks of mule accounts, money going round in a circle, an agent whose volume is unusual compared with other agents.

A rule listed as RT/PE is designed to run in either mode — for example as a real-time block for a PSP, or as a post-event alert for a bank that does not use the decision API.

What runs where today

Real-time and post-event rules both ship. Real-time rules run only for payments your system sends to the real-time decision API (POST /api/v1/decisions) before approving them; a transaction sent through the ingest API afterwards never reaches them. A decided transaction is also monitored post-event, and when a real-time rule blocks, holds or steps up a payment, a fraud alert is raised for your analysts.

Scheduled rules run on a timetable in the worker role, over the transaction history in the database: 9 of the shipped rules work this way (D3, D4, F5, G1, I1 to I4 and GB1). See Scheduled rules. The library’s RT/PE and PE/SCH rules ship in one mode each (see each page), and A4 and F1 ship in both real-time and post-event versions.

Not using the real-time decision API?

Many banks start by sending transactions after the fact (through the ingest API or, once available, end-of-day files). That is fine: every rule that supports PE or SCH works without the decision API. Rules that are RT only (such as H1 card testing) need real-time integration to be useful.

Rule packs

Library rules are delivered in packs — bundles for a market or a type of institution.

Pack	For	Status	Contents
core	Every institution	Ships today, version 1.4.1, 24 rules: 21 post-event, 3 scheduled	A1–A3, B1, B3–B5, C1–C5, D1, D2, D6, D7, E1, F1–F3, H4 post-event; D3, D4, F5 scheduled
fraud	Anyone using the real-time decision API	Ships today, version 1.4.0, 11 rules, all real-time	H1–H3, H5, C6, C7, E2, E3, D5, F1-RT, F4
gh-psp	Ghanaian PSPs and mobile money operators	Ships today, version 1.2.0, 14 rules: 8 post-event, 2 real-time, 4 scheduled	A4, A5, B2, E4, G2, G4–G6 post-event; G3 and A4-RT real-time; G1, I1–I3 scheduled
gh-bank	Ghanaian universal and rural banks	Ships today, version 1.1.0, 10 rules: 5 post-event, 5 scheduled	GB2–GB5, E4 post-event; GB1, I1–I4 scheduled
global-fatf	Every institution, in any country	Ships today, version 1.2.0, 8 rules, all post-event	FATF1–FATF8. See Pack contents: FATF baseline
ng-psp	Nigerian PSPs, mobile money operators and agents	Ships today, version 1.2.0, 9 rules: 8 post-event, 1 real-time	NG1–NG9. See Pack contents: Nigeria
ng-bank	Nigerian banks	Ships today, version 1.2.0, 8 rules, all post-event	NG1, NG2, NG10, NGB1–NGB5
uemoa-emi	E-money issuers and mobile money in the UEMOA	Ships today, version 1.1.0, 8 rules: 7 post-event, 1 real-time	UE1–UE8. See Pack contents: UEMOA
uemoa-bank	Banks in the UEMOA	Ships today, version 1.0.0, 8 rules, all post-event	UE1, UEB1–UEB7
sl-psp	Mobile money, PSPs and agents in Sierra Leone	Ships today, version 1.0.0, 8 rules: 7 post-event, 1 real-time. Values to verify with counsel	SL1–SL8. See Pack contents: Sierra Leone
sl-bank	Banks in Sierra Leone	Ships today, version 1.0.0, 8 rules, all post-event. Values to verify with counsel	SL1, SL2, SLB1–SLB6
lr-psp	Mobile money, PSPs and agents in Liberia	Ships today, version 1.0.0, 9 rules: 8 post-event, 1 real-time. Values to verify with counsel	LR1–LR9. See Pack contents: Liberia
lr-bank	Banks in Liberia	Ships today, version 1.0.0, 8 rules, all post-event. Values to verify with counsel	LR1–LR3, LRB1–LRB5
gm-psp	Mobile money, PSPs and agents in The Gambia	Ships today, version 1.0.0, 8 rules: 7 post-event, 1 real-time. Values to verify with counsel	GM1–GM8. See Pack contents: The Gambia
gm-bank	Banks in The Gambia	Ships today, version 1.0.0, 8 rules, all post-event. Values to verify with counsel	GM1, GM2, GMB1–GMB6
gn-emi	E-money issuers and mobile money in Guinea	Ships today, version 1.0.0, 8 rules: 7 post-event, 1 real-time. Values to verify with counsel	GN1–GN8. See Pack contents: Guinea
gn-bank	Banks in Guinea	Ships today, version 1.0.0, 8 rules, all post-event. Values to verify with counsel	GN1, GN2, GNB1–GNB6
ke-psp	Mobile money, PSPs and agents in Kenya	Ships today, version 1.0.0, 12 rules: 11 post-event, 1 real-time. Values to verify with counsel	KE1–KE12. See Pack contents: Kenya
ke-bank	Banks in Kenya	Ships today, version 1.0.0, 9 rules, all post-event. Values to verify with counsel	KE1–KE3, KEB1–KEB6

I1, I2, I3 and E4 are in both gh-psp and gh-bank; NG1 and NG2 in both Nigerian packs; UE1 in both UEMOA packs; SL1 and SL2, LR1 to LR3, GM1 and GM2, GN1 and GN2, and KE1 to KE3 in both of their country’s packs. A workspace that installs both packs of a pair gets each shared rule once, from whichever pack it installed first. Each pack’s rules can be found first in the rule library by workspaces following its jurisdiction.

Packs are versioned. When you install one, SpeculaPro stores a SHA-256 digest of its contents, so you can always prove which definitions arrived. When a new version of an installed pack is available, you upgrade it: new rules are added, switched off, and a rule whose definition changed gets a new version awaiting approval, with your tuning carried over. Nothing changes in production until a second person approves and deploys it. New pack versions arrive with a SpeculaPro upgrade, or as a signed pack file that SpeculaPro verifies before reading.

Packs for more countries are planned.

What ships today

Category	Shipped (pack)	Not shipped yet
A. Thresholds	A1, A2, A3 (core); A4, A5 (gh-psp); A4-RT (gh-psp, real-time); GB2 (gh-bank)	—
B. Structuring	B1, B3, B4, B5 (core); B2 (gh-psp); GB1 (gh-bank, scheduled)	—
C. Velocity	C1, C2, C3, C4, C5 (core); C6, C7 (fraud, real-time)	—
D. Networks	D1, D2, D6, D7 (core); D3, D4 (core, scheduled); D5 for devices (fraud, real-time)	D5 for shared phone and ID numbers
E. Geography	E1 (core); E2, E3 (fraud, real-time); E4 (gh-psp, gh-bank); GB5 (gh-bank)	—
F. Designations	F1, F2, F3 (core); F5 (core, scheduled); F1-RT and F4 for countries and merchant categories (fraud, real-time)	F4 for named counterparties
G. Mobile money	G2, G4, G5, G6 (gh-psp); G3 (gh-psp, real-time); G1 (gh-psp, scheduled)	—
H. Card fraud	H4 (core); H1, H2, H3, H5 (fraud, real-time); GB3, GB4 (gh-bank)	—
I. Business	I1, I2, I3 (gh-psp, gh-bank, scheduled); I4 (gh-bank, scheduled)	—

C7, D7 and G6 came out of building the packs, and GB1 to GB5 out of building gh-bank; the original catalogue didn’t have them. Two rules run differently from the catalogue: D6 is post-event only (the case history isn’t looked up in real-time decisions), and I4 is scheduled rather than post-event, because it compares several payments with the customer’s declared industry.

The categories

Category	What it catches
A. Thresholds and reporting	Single transactions or totals that are simply too large, or above what a customer’s KYC tier allows
B. Structuring and smurfing	Breaking large sums into small pieces to stay under reporting thresholds
C. Velocity and behaviour change	Sudden changes from a customer’s normal pattern; money passing straight through
D. Mule and network patterns	Accounts used to collect and redistribute money for others; circular flows
E. Geography and high-risk exposure	Payments to or from high-risk countries; impossible travel
F. Customer risk and designations	Sanctioned persons, PEPs, deny-listed counterparties, activity that doesn’t fit the customer
G. Mobile money and agents	Agent abuse, SIM swap fraud, wallet sweeps, reversal abuse
H. Card and online fraud	Card testing, account takeover, suspicious first-time payees
I. Business and merchant	Merchants and personal accounts behaving unlike their declared business

How to read a rule page

Each rule is described with the same headings:

• What it looks for — the pattern, in plain words.
• Example — a worked case that fires the rule, and one that does not.
• Parameters — the values you tune, what each one means and how to think about setting it.
• Mode and pack — when it runs and which pack it comes in.
• False positives — the legitimate activity that commonly trips it, and how to handle it.
• Data it needs — the fields your integration must send for the rule to work.

Parameter names are shown in code because that is how they appear in the rule’s parameter editor. A name ending in [] (such as channels[]) takes a list of values.

What every rule carries

Behind the scenes, every library rule has the same set of properties. You will see most of them in the rule’s detail screen.

Property	What it means
ID and name	For example B1 — Multiple deposits just below threshold
Description and typology	The money-laundering or fraud pattern it detects, in FATF-style terms
Category	Which of the nine categories above it belongs to
Mode	realtime, post_event or scheduled; a scheduled rule also has a timetable
Entity scope	What the rule is “about”: a transaction, customer, account, counterparty, device, agent or merchant
Parameters	The tunable values, each with a type, default, allowed range and help text
Severity	low, medium, high or critical — how serious a match is
Score	A number added to the alert’s risk score; higher-scoring alerts rise to the top of the queue
Action	What happens on a match (see modes)
Required fields	Data the rule needs to work. Listed under Data it needs on each rule’s page
Explanation	The sentence an analyst sees on the alert, explaining in plain words why it fired

Check required fields before you switch a rule on

A rule that needs data you do not send will simply never fire. SpeculaPro doesn’t warn you yet. For example, G3 needs sim_swap account events, and E3 impossible travel needs geo_lat and geo_lon on transactions. If a rule looks suspiciously quiet, check its required fields first.

Related

• Pack contents
• Managing rules
• Tuning and calibration
• Rules and versions
• Suppressions
• Risk designations and lists
• Rule engine (architecture)