> ## 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 追蹤違規以識別配置有誤的代理。
* **使用速率限制** — 防止代理重複嘗試交易的失控迴圈。
* **每週檢視策略** — 隨著代理行為的演變，更新策略以符合需求。