Points Fraud Protection Integration
Flash protects the points ledger with a freeze-then-verdict model: hardcoded detectors run nightly and freezesuspicious points the moment they're found (still on the member's record, but unspendable and paused from expiring), then SoClaw reviews each hold and voids, releases or escalates it — through the same governed MCP worklist as win-back.
This guide is for the operator/integrator running the agent. For the business overview see the SoClaw product page; the worklist tools build on the governed MCP server in the MCP Integration guide and share the agent-tasks worklist with the win-back guide.
Freeze on detection, decide on review
The safer alternative to award-then-clawback: points are held the instant a rule fires, so nothing can be cashed out during review. A frozen batch stays on the ledger but is excluded from the spendable balance, from redemption, and from expiry. The verdict is the only thing that moves points.
# Nightly, server-side (no agent involved):
for detector in enabled_detectors(team): # master switch + per-detector checkbox
for hold in detector.detect(team): # each hold = one entity, e.g. a referral or order
freeze(hold.targets) # FREEZE suspect points (idempotent, reversible)
enqueue(kind="fraud_points_hold", subject_key=hold.subject_key) # one review task
# Agent side (self-hosted OpenClaw + SoClaw decisions skill):
task = claim_agent_task(kind="fraud_points_hold") # NO_TASKS_AVAILABLE / AGENT_TASKS_DISABLED → STOP
facts = get_agent_task(task.id) # ids + signal + evidence (no PII)
complete_agent_task(task.id,
decision="block" | "allow" | "escalate", # block=void, allow=release, escalate=leave frozen
reason="<why>")A single signal never auto-confirms. A detector only freezes and opens a review — the block/allow/escalateverdict is the agent's (or a human's). Machine-decidable abuse (self-referral, referral cycles, invite rate limits, duplicate-receipt hashing) is blocked synchronously elsewhere and never reaches this queue.
The detectors
Each is an opt-in checkbox under one master switch. Only signals with a real, queryable basis exist — account takeover, points reselling and pure wash-trading are deliberately absent (no counterparty, payment-instrument or device signal to detect them honestly).
same_household_referralA converted referral whose referrer and referee are a confirmed (≥0.9) household — a likely self-referral.
Freezes: Both sides' referral bonus.
refunded_order_unclawed_pointsAn order fully refunded or cancelled whose awarded purchase points are still present (not yet clawed back).
Freezes: The buyer's purchase points for that order.
household_welcome_farmingA confirmed household where two or more members each still hold a welcome bonus — possible multi-account farming.
Freezes: Each flagged member's welcome bonus.
zombie_referralA referral rewarded 30+ days ago whose invited member has never placed an order since — a likely fabricated signup.
Freezes: Both sides' referral bonus.
order_velocity_burstA member who placed an unusually high number of orders in a short window with the points still unspent — a wash-trading proxy.
Freezes: The still-present purchase points from the burst.
behavior_outlierA member whose 30-day points activity — earn transaction count, points earned, redemption count — is an extreme statistical outlier (robust z-score ≥ 6) against the team's own member distribution.
Freezes: The member's still-present points from the outlier window.
Inside behavior_outlier — the statistical detector
Unlike the five rule detectors, behavior_outlier scores each member's 30-day points activity against the team's own distribution— three features per member: earn transaction count, points earned, and redemption count — using a robust z-score (median + MAD, so a few whales can't shift the baseline):
z = (x − median) / (MAD × 1.4826) # per feature, vs the team's own members
flag when z ≥ 6- Floors before anything fires. The member needs ≥ 10 earn transactions in the window, and the team needs ≥ 50 active members for a baseline — below either, the detector emits nothing at all.
- Same freeze → review pipeline. The freeze runs before the review task is enqueued; frozen batches stay on the ledger (unspendable, paused from expiring); the verdict (release / void / escalate) comes from SoClaw or a human — never automatic punishment.
- At most one review per member per month. The subject key is
behavior_outlier:{memberId}:{YYYYMM}, and members who already have a frozen batch are skipped — no pile-on. - Opt-out like the others. A per-detector checkbox, default on when the fraud task kind is enabled for the team.
- Glass-box evidence. Every flagged feature in the reason payload carries
{value, teamMedian, robustZ, flagged}plus the floors that were applied — the reviewer sees exactly why the member was flagged, not a score.
Verdict semantics
| Decision | Effect |
|---|---|
| block | Confirmed fraud — the frozen points are voided (removed for good, never returned to spendable). |
| allow | False alarm — the points are released back to spendable. A lapsed expiry is extended by a grace window so the member isn't penalised for the hold. |
| escalate | Unclear — the points stay frozen and the case is left for a human. Recommended whenever a single signal isn't enough to judge. |
Every effect runs through an existing idempotent write — freeze, void and release are keyed per (action, hold, member), and the effect is applied before the task is finalized, so a lost lease never leaves a half-applied change. There is no new money path for the agent.
Admin controls & the fail-safe
- Master switch — fraud detection is off until an org owner/admin enables the Points-hold job for the team, and a platform kill switch gates it globally. Both must be on for any detection to run.
- Per-detector checklist — each detector is a checkbox (no stored setting = on when the master is on). Disabling one stops just that check.
- Stale-hold escalation— a hold with no verdict after two weeks is auto-escalated to a human. Points stay frozen: they are never auto-released (fraud can't wait out the clock) nor auto-voided (the member may be innocent).
- Full audit — freeze, void, release and escalate are all written to the worklist with their reason; nothing moves silently.