> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto-Freeze

> Automatically suspend agents when behavioral anomalies are detected

# Auto-Freeze

Conto can automatically freeze agents when suspicious behavior is detected. When an agent is frozen, all its transactions are blocked until a human reviews and unfreezes it.

## How It Works

After every transaction or policy evaluation, Conto checks the agent's behavior against configurable thresholds. If a threshold is exceeded:

* **Auto-freeze enabled**: The agent is immediately suspended, its wallets are frozen, and a CRITICAL alert is created.
* **Auto-freeze disabled** (default): An alert is created for visibility, but the agent continues operating.

## Trigger Types

| Trigger                        | What it detects                             | Default threshold         |
| ------------------------------ | ------------------------------------------- | ------------------------- |
| `CONSECUTIVE_VIOLATIONS`       | Repeated policy denials                     | 5 consecutive violations  |
| `CONSECUTIVE_FAILURES`         | Repeated transaction failures               | 5 consecutive failures    |
| `SPEND_VELOCITY`               | Hourly spend rate vs. 30-day average        | 3x the average            |
| `LARGE_TRANSACTION_ANOMALY`    | Single transaction much larger than average | 10x the average           |
| `TRUST_SCORE_BELOW_THRESHOLD`  | Average counterparty trust too low          | Below 0.2                 |
| `TRUST_SCORE_DROP`             | Trust score dropped significantly in 24h    | 30% drop                  |
| `RAPID_COUNTERPARTY_SWITCHING` | Too many unique recipients in one hour      | 10 unique recipients/hour |
| `MANUAL`                       | Admin manually froze the agent              | N/A                       |

### Trigger Details

**Spend Velocity** compares the agent's spend in the last hour against its average hourly spend over 30 days. Requires at least 5 historical transactions to activate.

**Large Transaction Anomaly** compares the most recent transaction amount to the historical average. Requires at least 10 historical transactions.

**Rapid Counterparty Switching** counts distinct `toAddress` values in the last hour. A sudden spike in new recipients can indicate compromised credentials.

## Configuration

Configure thresholds per agent in the dashboard under **Agents > \[Agent] > Freeze Settings**, or
via the freeze configuration endpoint:

```bash theme={null}
curl -X PATCH https://conto.finance/api/agents/AGENT_ID/freeze-config \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "autoFreezeEnabled": true,
    "maxConsecutiveViolations": 3,
    "maxConsecutiveFailures": 3,
    "spendVelocityMultiplier": 2,
    "largeTxMultiplier": 5,
    "minTrustScore": 0.3,
    "trustScoreDropThreshold": 0.2,
    "maxNewCounterpartiesPerHour": 5
  }'
```

### Configuration Fields

| Field                         | Type   | Default | Description                                               |
| ----------------------------- | ------ | ------- | --------------------------------------------------------- |
| `maxConsecutiveViolations`    | number | 5       | Freeze after N consecutive policy violations              |
| `maxConsecutiveFailures`      | number | 5       | Freeze after N consecutive transaction failures           |
| `spendVelocityMultiplier`     | number | 3       | Freeze when hourly spend exceeds Nx the 30-day average    |
| `largeTxMultiplier`           | number | 10      | Freeze when a single tx exceeds Nx the historical average |
| `minTrustScore`               | number | 0.2     | Freeze when average counterparty trust drops below this   |
| `trustScoreDropThreshold`     | number | 0.3     | Freeze on a 30%+ trust score drop in 24h                  |
| `maxNewCounterpartiesPerHour` | number | 10      | Freeze when unique recipients per hour exceeds this       |

## Freezing and Unfreezing

### Manual Freeze

```bash theme={null}
curl -X POST https://conto.finance/api/agents/AGENT_ID/freeze \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Investigating unusual spending pattern",
    "freezeWallets": true
  }'
```

### Manual Unfreeze

```bash theme={null}
curl -X POST https://conto.finance/api/agents/AGENT_ID/unfreeze \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Investigation complete, no issues found",
    "unfreezeWallets": true,
    "resetCounters": true
  }'
```

Setting `resetCounters: true` (the default) resets the consecutive violation and failure counters so the agent doesn't immediately re-trigger after unfreezing.

## What Happens When an Agent Is Frozen

1. Agent status changes to `SUSPENDED`
2. All linked wallets are optionally frozen (`freezeWallets: true`)
3. A `CRITICAL` severity alert is created
4. A freeze event is recorded in the audit log
5. Webhooks fire (`agent.frozen`)
6. All subsequent payment requests return a denial

## Freeze History

View freeze events in the dashboard under **Agents > \[Agent] > Freeze History**, or via the API:

```bash theme={null}
curl https://conto.finance/api/freeze-events?agentId=AGENT_ID \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY"
```

Each freeze event records:

* Trigger type and trigger data
* Who initiated it (user or system)
* Whether wallets were frozen
* Resolution timestamp and notes (after unfreezing)