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

# 策略引擎

> 配置按代理的消费限额、地址白名单、频率控制和人工审批路由。

## 概述

策略引擎在每笔交易到达 MPC 签名层之前对其进行评估。策略按代理设置，可随时通过 SDK 或 REST API 更新。第一个策略违规即立即阻止交易。

## 策略类型

### 消费限额

控制代理的消费额度：

```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
});
```

| 规则                     | 说明            | 窗口   |
| ---------------------- | ------------- | ---- |
| `maxTransactionAmount` | 单笔支付的最大金额     | 按交易  |
| `dailyLimit`           | 滚动 24 小时的最大总额 | 滚动窗口 |
| `monthlyLimit`         | 滚动 30 天的最大总额  | 滚动窗口 |

### 地址控制

限制代理可以发送到的地址：

```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>
  如果设置了 `allowedAddresses`，则仅允许这些地址。如果同时设置了 `allowedAddresses` 和 `blockedAddresses`，则 `allowedAddresses` 优先。
</Note>

### 代币控制

限制代理可以交易的代币：

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

### 频率控制

限制交易频率以防止失控的代理：

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

### 基于时间的控制

限制交易发生的时间：

```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
  },
});
```

### 人工审批

将高价值交易路由至人工审核：

```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>
  人工审批功能在 Growth 和 Enterprise 计划上可用。当交易需要审批时，会发送 Webhook 事件，交易进入 `pending_approval` 状态。
</Info>

## 策略评估顺序

策略按以下顺序检查。第一个失败即阻止交易：

<Steps>
  <Step title="代理状态">
    代理是否处于活跃状态（未冻结）？
  </Step>

  <Step title="代币检查">
    该代币是否在 `allowedTokens` 列表中？
  </Step>

  <Step title="地址检查">
    收款方是否在 `allowedAddresses` 中且不在 `blockedAddresses` 中？
  </Step>

  <Step title="金额检查">
    是否超过 `maxTransactionAmount`？
  </Step>

  <Step title="每日限额">
    是否会超过滚动每日总额？
  </Step>

  <Step title="每月限额">
    是否会超过滚动每月总额？
  </Step>

  <Step title="频率检查">
    代理是否超过了交易频率（`velocityLimit`）？
  </Step>

  <Step title="时间检查">
    是否在允许的时间和日期内？
  </Step>

  <Step title="人工审批">
    是否需要根据阈值进行人工审核？
  </Step>

  <Step title="基础设施安全网">
    Paratro 执行的硬限制（无法覆盖）。
  </Step>
</Steps>

## 策略违规事件

当策略阻止交易时，API 返回详细错误：

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

您还可以通过 Webhook 事件接收违规通知：

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

## 策略模板

使用模板进行常见配置：

```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");
```

## 最佳实践

<Tip>
  从最严格的策略开始，随着对代理行为的信心增强逐步放宽。
</Tip>

* **使用 allowedAddresses** — 白名单受信任地址，而非仅依赖金额限制。
* **为高价值交易启用人工审批** — 设置超过该阈值需要人工审核的金额。
* **监控策略违规** — 通过 Webhook 跟踪违规，以识别配置有误的代理。
* **使用频率限制** — 防止代理反复尝试交易的失控循环。
* **每周审查策略** — 随着代理行为的演变，更新策略以适应。