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.
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.