# mercury-detect-anomaly

Flags unusual Mercury transactions by comparing recent activity against a 90 day spending baseline, using the mercury command line tool.

Skill by Mercury. Category: Security.

## Install

Project (for this project only):

```sh
npx skills add mercurytechnologies/mercury-skills --skill mercury-detect-anomaly
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add mercurytechnologies/mercury-skills --skill mercury-detect-anomaly -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 3. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/mercurytechnologies/mercury-skills/mercury-detect-anomaly)

## Source

[Open the source](https://github.com/mercurytechnologies/mercury-skills/tree/HEAD/skills/mercury-detect-anomaly). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: mercury-detect-anomaly
description: "Detect anomalous transactions by building spending baselines from the mercury CLI and flagging pattern breaks."
metadata:
  version: "1.0.0"
  category: agentic
  scopes: [accounts:read, transactions:read]
  requires: [mercury-shared]
---

# Mercury Detect Anomaly

Detect anomalous transactions by building historical spending baselines and flagging pattern breaks. This skill pulls baseline and recent transactions via the `mercury` CLI, computes per-counterparty and per-category norms, and scores recent transactions against those baselines using a weighted anomaly model.

## Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `analysisWindow` | Last 7 days | Time period for transactions to evaluate for anomalies |
| `baselinePeriod` | 90 days | Historical lookback period for building baselines |
| `scoreThreshold` | 0.5 | Minimum weighted score to flag a transaction as anomalous |

## Execution Strategy

### Step 1: Establish Date Windows

```
1. Run `date +%Y-%m-%d` to get today's date.
2. Run `mercury accounts list --max-items -1 --format jsonl` to get all accounts.
3. Compute:
   - baselineStart = today - baselinePeriod   (default: 90 days)
   - baselineEnd   = today - analysisWindow   (default: 7 days ago)
   - analysisStart = today - analysisWindow
   - analysisEnd   = today
```

### Step 2: Fetch Transactions

Run two separate `mercury transactions list` calls — one for the baseline window, one for the analysis window. Both can target every account by repeating `--account-id`, and both should use `--max-items -1` so pagination is complete.

```
# Baseline window
mercury transactions list \
  --account-id <id1> [--account-id <id2> ...] \
  --start <baselineStart> --end <baselineEnd> \
  --status sent \
  --max-items -1 --format jsonl

# Analysis window
mercury transactions list \
  --account-id <id1> [--account-id <id2> ...] \
  --start <analysisStart> --end <analysisEnd> \
  --status sent \
  --max-items -1 --format jsonl
```

If the baseline result is very large (>2,000 rows), split the baseline range into 7-day windows and run one call per window, then merge.

### Step 3: Score Anomalies

```
baselineTransactions = merge(baseline responses)
analysisTransactions = merge(analysis responses)

# Per-counterparty baseline.
counterpartyBaseline = {}
FOR EACH txn IN baselineTransactions:
    cp = txn.counterpartyName
    counterpartyBaseline[cp].amounts.push(abs(txn.amount))
    counterpartyBaseline[cp].dates.push(txn.createdAt || txn.postedAt)
    counterpartyBaseline[cp].count += 1

FOR EACH cp IN counterpartyBaseline:
    cp.avgAmount = mean(cp.amounts)
    cp.frequency = cp.count / baselinePeriodWeeks   # transactions per week
    cp.typicalDays = mode(cp.dates.map(d => dayOfWeek(d)))

# Per-category baseline.
categoryBaseline = {}
FOR EACH txn IN baselineTransactions:
    cat = txn.category || "Uncategorized"
    categoryBaseline[cat].amounts.push(abs(txn.amount))
    categoryBaseline[cat].count += 1

FOR EACH cat IN categoryBaseline:
    cat.avgAmount = mean(cat.amounts)

# Score each transaction in the analysis window.
FOR EACH txn IN analysisTransactions:
    score = 0
    reasons = []
    cp = txn.counterpartyName
    cat = txn.category || "Uncategorized"
    txnAmount = abs(txn.amount)

    # 1. Amount anomaly (weight: 0.3)
    IF cp IN counterpartyBaseline AND txnAmount > 3 * counterpartyBaseline[cp].avgAmount:
        score += 0.3
        reasons.push("Amount ${txnAmount} is {ratio}x the baseline average ${cp.avgAmount} for {cp}")

    # 2. New counterparty (weight: 0.2)
    IF cp NOT IN counterpartyBaseline:
        score += 0.2
        reasons.push("First transaction with counterparty '{cp}'")

    # 3. Frequency spike (weight: 0.2)
    IF cp IN counterpartyBaseline:
        analysisWindowWeeks = analysisWindow / 7
        currentFrequency = count(analysisTransactions where counterparty == cp) / analysisWindowWeeks
        IF currentFrequency > 2 * counterpartyBaseline[cp].frequency:
            score += 0.2
            reasons.push("Frequency {currentFrequency}/week vs baseline {cp.frequency}/week")

    # 4. Category outlier (weight: 0.15)
    IF cat IN categoryBaseline AND txnAmount > 2 * categoryBaseline[cat].avgAmount:
        score += 0.15
        reasons.push("Amount is {ratio}x the category average of ${cat.avgAmount}")

    # 5. Time anomaly (weight: 0.15)
    IF cp IN counterpartyBaseline AND dayOfWeek(txn.date) NOT IN counterpartyBaseline[cp].typicalDays:
        score += 0.15
        reasons.push("Transaction on {day} -- typically occurs on {typicalDays}")

    txn.anomalyScore = score
    txn.anomalyReasons = reasons

flagged = analysisTransactions.filter(t => t.anomalyScore >= scoreThreshold)
flagged.sortBy(anomalyScore, descending)
```

### Step 4: Present

```
1. Summary header:
   - Analysis window and baseline period
   - Total transactions analyzed
   - Number of anomalies detected
   - Highest anomaly score

2. Ranked anomaly list:
   FOR EACH txn IN flagged (sorted by score descending):
       | Score | Date | Counterparty | Amount | Category |
       Reasons: bullet list of what triggered the flag.
       Baseline context: historical average, frequency, typical timing.

3. Anomaly breakdown by signal type:
   - Amount anomalies
   - New counterparties
   - Frequency spikes
   - Category outliers
   - Time anomalies
```

## Example Output

```
Anomaly Detection: Apr 22 - Apr 29, 2026
Baseline: Jan 29, 2026 - Apr 22, 2026 (90 days)
Transactions analyzed: 142 | Anomalies flagged: 3

Flagged Transactions:

1. Score: 0.65 | Apr 25 | "NewTech Solutions" | $18,500.00 | Software
   - First transaction with counterparty 'NewTech Solutions' (+0.2)
   - Amount is 3.2x the Software category average of $1,622.50 (+0.15)
   - Amount $18,500.00 is 4.1x the average for similar vendors (+0.3)

2. Score: 0.50 | Apr 27 | "AWS" | $28,900.00 | Cloud Services
   - Amount $28,900.00 is 3.4x the average $8,500.00 for AWS (+0.3)
   - Frequency 3/week vs baseline 0.8/week (+0.2)

3. Score: 0.50 | Apr 23 | "Office Depot" | $4,200.00 | Office Supplies
   - Amount is 2.8x the category average of $617.00 (+0.15)
   - Transaction on Saturday -- typically occurs on Mon, Wed (+0.15)
   - Frequency 4/week vs baseline 1.5/week (+0.2)

Signal Breakdown:
  Amount anomalies:    2
  New counterparties:  1
  Frequency spikes:    2
  Category outliers:   2
  Time anomalies:      1
```

## Tips

- A 90-day baseline gives reliable averages for most counterparties. For newer accounts with less history, surface that reduced confidence in the output.
- Transactions with multiple anomaly signals are far more likely to be genuinely anomalous — prioritize composite scores.
- Use `--transform 'transactions.#.{id,amount,counterpartyName,category,createdAt,postedAt}'` on both list calls to keep token usage down on a 90-day window.
````

- Previous: [mercury-cash-reconciliation](https://syn4pse.dev/terminal/mercury-cash-reconciliation.md)
- Next: [mercury-journal-entry-prep](https://syn4pse.dev/terminal/mercury-journal-entry-prep.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
