Automatic Agent Protection

# Automatic Agent Protection

> Configure automatic freezes, review why an agent was stopped, and restore access safely

- Human URL: https://conto.finance/docs/guides/auto-freeze
- Raw Markdown: https://conto.finance/docs/guides/auto-freeze.md
- Terminal view: https://conto.finance/ai/docs/guides/auto-freeze

Documentation group: Guides

# Automatic Agent Protection

Automatic protection can freeze an agent when its payment behavior reaches one of your configured safety thresholds. A frozen agent cannot start new payments until a team member restores it. When an automatic freeze occurs, associated wallets are frozen as well.

Use this control as a backstop alongside payment policies and approval rules. Policies decide whether an individual payment is allowed; automatic protection can stop the agent when a pattern of activity needs review.

## Protection settings

Read the current settings with `GET /api/agents/{id}/freeze-config`:

```json
{
  "enabled": true,
  "thresholds": {
    "maxConsecutivePolicyViolations": 5,
    "maxConsecutivePaymentFailures": 5,
    "spendVelocityMultiplier": 3,
    "largePaymentMultiplier": 10,
    "minimumTrustScore": 0.2,
    "trustScoreDropThreshold": 0.3,
    "maxNewCounterpartiesPerHour": 10
  }
}
```

| Threshold                        | What it controls                                                                 |
| -------------------------------- | -------------------------------------------------------------------------------- |
| `maxConsecutivePolicyViolations` | Number of consecutive policy-denied payments allowed before protection activates |
| `maxConsecutivePaymentFailures`  | Number of consecutive failed payments allowed before protection activates        |
| `spendVelocityMultiplier`        | How far recent payment activity may rise above the agent's established rate      |
| `largePaymentMultiplier`         | How large one payment may be relative to the agent's established payment size    |
| `minimumTrustScore`              | Lowest acceptable average counterparty trust score, from `0` to `1`              |
| `trustScoreDropThreshold`        | Largest acceptable trust-score drop, from `0.01` to `1`                          |
| `maxNewCounterpartiesPerHour`    | Number of new counterparties the agent may pay within one hour                   |

New agents may not have enough payment history for relative activity thresholds to produce a meaningful comparison. Consecutive failures and policy violations can still provide protection while history develops.

## Update settings

Send only the values you want to change. Omitted values retain their current setting.

```bash
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 '{
    "enabled": true,
    "thresholds": {
      "maxConsecutivePolicyViolations": 3,
      "maxConsecutivePaymentFailures": 3,
      "maxNewCounterpartiesPerHour": 5
    }
  }'
```

The API key needs the `agents:write` scope. In the dashboard, owners, admins, and managers can manage this setting.

## Freeze or restore an agent manually

Add an optional customer note so other team members can understand the decision later.

```bash
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": "Reviewing an unexpected supplier payment",
    "freezeWallets": true
  }'
```

```bash
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": "Supplier details verified",
    "unfreezeWallets": true
  }'
```

## Review status history

Use `GET /api/agents/{id}/freeze-history` to reconcile when and why access changed:

```json
{
  "items": [
    {
      "id": "freeze_01JZ...",
      "action": "FROZEN",
      "actionLabel": "Frozen",
      "source": "AUTOMATIC_PROTECTION",
      "sourceLabel": "Automatic protection",
      "reason": "Several payments failed in succession.",
      "occurredAt": "2026-07-15T18:24:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
```

Use each event `id` as a stable reconciliation or support reference. Automatic events use stable,
customer-readable explanations. Team actions include the optional note supplied with the freeze or
restore request.