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

# Policy Engine

> Configure per-agent spending limits, address whitelists, velocity controls, and human approval routing.

## Overview

The policy engine evaluates every transaction before it reaches the MPC signing layer. Policies are per-agent and can be updated at any time via the SDK or REST API. The first policy violation stops the transaction immediately.

## Policy Types

### Spending Limits

Control how much an agent can spend:

```typescript theme={null}
await aw.policies.update("agent_abc123", {
  maxTransactionAmount: "500",   // Max per single transaction (USDC)
  dailyLimit: "5000",            // Rolling 24-hour total
  monthlyLimit: "50000",         // Rolling 30-day total
});
```

| Rule                   | Description                         | Window          |
| ---------------------- | ----------------------------------- | --------------- |
| `maxTransactionAmount` | Maximum amount for a single payment | Per transaction |
| `dailyLimit`           | Maximum total over rolling 24 hours | Rolling window  |
| `monthlyLimit`         | Maximum total over rolling 30 days  | Rolling window  |

### Address Controls

Restrict which addresses an agent can send to:

```typescript theme={null}
await aw.policies.update("agent_abc123", {
  // Whitelist mode: only send to these addresses
  allowedAddresses: [
    "0xTrustedVendor1",
    "0xTrustedVendor2",
    "0xTrustedExchange",
  ],

  // Blacklist mode: block specific addresses
  blockedAddresses: [
    "0xKnownScam",
  ],
});
```

<Note>
  If `allowedAddresses` is set, only those addresses are permitted. If both `allowedAddresses` and `blockedAddresses` are set, `allowedAddresses` takes priority.
</Note>

### Token Controls

Restrict which tokens an agent can transact with:

```typescript theme={null}
await aw.policies.update("agent_abc123", {
  allowedTokens: ["USDC", "USDT"],  // Only stablecoins
});
```

### Velocity Controls

Limit transaction frequency to prevent runaway agents:

```typescript theme={null}
await aw.policies.update("agent_abc123", {
  velocityLimit: {
    maxCount: 100,        // Max number of transactions
    windowSeconds: 3600,  // Per hour
  },
});
```

### Time-Based Controls

Restrict when transactions can occur:

```typescript theme={null}
await aw.policies.update("agent_abc123", {
  schedule: {
    timezone: "America/New_York",
    allowedHours: { start: 9, end: 17 },  // 9 AM - 5 PM
    allowedDays: [1, 2, 3, 4, 5],         // Monday - Friday
  },
});
```

### Human Approval

Route high-value transactions to human review:

```typescript theme={null}
await aw.policies.update("agent_abc123", {
  requireHumanApproval: true,
  humanApprovalThreshold: "1000",  // Transactions above $1000
  approvalTimeout: 3600,           // 1 hour to approve before auto-reject
  approvers: [
    "user_admin1@company.com",
    "user_admin2@company.com",
  ],
});
```

<Info>
  Human approval is available on Growth and Enterprise plans. When a transaction requires approval, a webhook event is sent and the transaction enters a `pending_approval` state.
</Info>

## Policy Evaluation Order

Policies are checked in this order. The first failure stops the transaction:

<Steps>
  <Step title="Agent Status">
    Is the agent active (not frozen)?
  </Step>

  <Step title="Token Check">
    Is this token in the `allowedTokens` list?
  </Step>

  <Step title="Address Check">
    Is the recipient in `allowedAddresses` and not in `blockedAddresses`?
  </Step>

  <Step title="Amount Check">
    Does this exceed `maxTransactionAmount`?
  </Step>

  <Step title="Daily Limit">
    Would this exceed the rolling daily total?
  </Step>

  <Step title="Monthly Limit">
    Would this exceed the rolling monthly total?
  </Step>

  <Step title="Velocity Check">
    Has the agent exceeded its transaction rate (`velocityLimit`)?
  </Step>

  <Step title="Schedule Check">
    Is this within allowed hours and days?
  </Step>

  <Step title="Human Approval">
    Does this require human review based on the threshold?
  </Step>

  <Step title="Infrastructure Safety Net">
    Paratro-enforced hard limits (cannot be overridden).
  </Step>
</Steps>

## Policy Violation Events

When a policy blocks a transaction, the API returns a detailed error:

```json theme={null}
{
  "code": "policy_violation",
  "type": "invalid_request_error",
  "message": "Transaction would exceed daily limit"
}
```

You can also receive violations as webhook events:

```typescript theme={null}
await aw.webhooks.create({
  url: "https://your-app.com/webhooks",
  events: ["policy.violated"],
});
```

## Policy Templates

Use templates for common configurations:

```typescript theme={null}
// Conservative: tight limits for testing
await aw.policies.applyTemplate("agent_abc123", "conservative");

// Standard: balanced limits for production
await aw.policies.applyTemplate("agent_abc123", "standard");

// Custom: define and reuse your own templates
await aw.policies.createTemplate("my-template", {
  maxTransactionAmount: "200",
  dailyLimit: "2000",
  allowedTokens: ["USDC"],
  velocityLimit: { maxCount: 50, windowSeconds: 3600 },
});

await aw.policies.applyTemplate("agent_abc123", "my-template");
```

## Best Practices

<Tip>
  Start restrictive, expand gradually. Begin with tight limits and increase as you gain confidence in your agent's behavior.
</Tip>

* **Use allowedAddresses** — Whitelist trusted addresses rather than relying solely on amount limits.
* **Enable human approval for high-value** — Set a threshold above which humans review transactions.
* **Monitor policy violations** — Track violations via webhooks to identify misconfigured agents.
* **Use velocity limits** — Prevent runaway loops where an agent repeatedly attempts transactions.
* **Review policies weekly** — As agent behaviors evolve, update policies to match.