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

# Motor de políticas

> Configure límites de gasto por agente, listas blancas de direcciones, controles de velocidad y enrutamiento de aprobación humana.

## Descripción general

El motor de políticas evalúa cada transacción antes de que llegue a la capa de firma MPC. Las políticas son por agente y pueden actualizarse en cualquier momento mediante el SDK o la API REST. La primera violación de política detiene la transacción inmediatamente.

## Tipos de políticas

### Límites de gasto

Controle cuánto puede gastar un agente:

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

| Regla                  | Descripción                        | Ventana            |
| ---------------------- | ---------------------------------- | ------------------ |
| `maxTransactionAmount` | Monto máximo para un solo pago     | Por transacción    |
| `dailyLimit`           | Máximo total en 24 horas continuas | Ventana deslizante |
| `monthlyLimit`         | Máximo total en 30 días continuos  | Ventana deslizante |

### Controles de direcciones

Restrinja a qué direcciones un agente puede enviar:

```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>
  Si `allowedAddresses` está configurado, solo se permiten esas direcciones. Si tanto `allowedAddresses` como `blockedAddresses` están configurados, `allowedAddresses` tiene prioridad.
</Note>

### Controles de tokens

Restrinja con qué tokens puede transaccionar un agente:

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

### Controles de velocidad

Limite la frecuencia de transacciones para prevenir agentes descontrolados:

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

### Controles basados en tiempo

Restrinja cuándo pueden ocurrir las transacciones:

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

### Aprobación humana

Dirija transacciones de alto valor a revisión humana:

```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>
  La aprobación humana está disponible en los planes Growth y Enterprise. Cuando una transacción requiere aprobación, se envía un evento webhook y la transacción entra en estado `pending_approval`.
</Info>

## Orden de evaluación de políticas

Las políticas se verifican en este orden. La primera falla detiene la transacción:

<Steps>
  <Step title="Estado del agente">
    ¿Está el agente activo (no congelado)?
  </Step>

  <Step title="Verificación de token">
    ¿Está este token en la lista `allowedTokens`?
  </Step>

  <Step title="Verificación de dirección">
    ¿Está el destinatario en `allowedAddresses` y no en `blockedAddresses`?
  </Step>

  <Step title="Verificación de monto">
    ¿Excede esto el `maxTransactionAmount`?
  </Step>

  <Step title="Límite diario">
    ¿Excedería esto el total diario acumulado?
  </Step>

  <Step title="Límite mensual">
    ¿Excedería esto el total mensual acumulado?
  </Step>

  <Step title="Verificación de velocidad">
    ¿Ha excedido el agente su tasa de transacciones (`velocityLimit`)?
  </Step>

  <Step title="Verificación de horario">
    ¿Está esto dentro de las horas y días permitidos?
  </Step>

  <Step title="Aprobación humana">
    ¿Requiere esto revisión humana según el umbral?
  </Step>

  <Step title="Red de seguridad de infraestructura">
    Límites estrictos aplicados por Paratro (no pueden ser anulados).
  </Step>
</Steps>

## Eventos de violación de políticas

Cuando una política bloquea una transacción, la API devuelve un error detallado:

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

También puede recibir violaciones como eventos webhook:

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

## Plantillas de políticas

Use plantillas para configuraciones comunes:

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

## Mejores prácticas

<Tip>
  Comience con restricciones estrictas y amplíe gradualmente. Empiece con límites ajustados y auméntelos a medida que gane confianza en el comportamiento de su agente.
</Tip>

* **Use allowedAddresses** — Incluya en lista blanca las direcciones de confianza en lugar de depender únicamente de los límites de monto.
* **Habilite la aprobación humana para alto valor** — Establezca un umbral por encima del cual los humanos revisen las transacciones.
* **Monitoree las violaciones de políticas** — Rastree las violaciones mediante webhooks para identificar agentes mal configurados.
* **Use límites de velocidad** — Evite bucles descontrolados donde un agente intente transacciones repetidamente.
* **Revise las políticas semanalmente** — A medida que los comportamientos de los agentes evolucionen, actualice las políticas para adaptarse.