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

# Arquitectura de seguridad

> Cuatro capas de seguridad — identidad, motor de políticas, firma MPC e intervención humana — protegen a sus agentes.

## Descripción general

AgentWallex está construido sobre el principio de que los agentes de IA **nunca deben tener acceso a claves privadas**. En su lugar, las transacciones se firman utilizando Computación Multi-Parte (MPC), donde ninguna parte individual posee jamás la clave completa.

La plataforma aplica seguridad a través de cuatro capas independientes. Una transacción debe pasar por todas ellas antes de ser difundida a la blockchain.

## Cuatro capas de seguridad

### Capa 1: Identidad y autenticación

Cada solicitud de API se autentica utilizando un sistema de dos tokens:

* **Clave API** (`awx_...`) — De larga duración, identifica su cuenta. Almacene de forma segura en variables de entorno.
* **Token de sesión** — De corta duración, limitado a agentes y operaciones específicas. Se rota automáticamente.

```typescript theme={null}
// API key authenticates your account
const aw = new AgentWallex({ apiKey: process.env.AGENTWALLEX_API_KEY! });

// Session tokens are managed internally by the SDK
// Each agent gets its own scoped session
```

**Propiedades clave:**

| Propiedad               | Detalle                    |
| ----------------------- | -------------------------- |
| Rotación de claves      | Sin tiempo de inactividad  |
| Expiración de sesión    | Configurable: 1-24 horas   |
| Alcance de permisos     | Por agente                 |
| Lista de IPs permitidas | Planes Growth y Enterprise |

### Capa 2: Motor de políticas

Cada transacción debe pasar por el motor de políticas antes de la firma. Las políticas se evalúan en orden — la primera violación detiene la transacción.

El motor de políticas soporta:

* Límites de gasto (por transacción, diarios, mensuales)
* Listas blancas y negras de direcciones
* Restricciones de tokens
* Controles de velocidad (limitación de tasa)
* Reglas de horario basadas en tiempo
* Enrutamiento de aprobación humana

Consulte [Motor de políticas](/es/features/policy-engine) para detalles completos de configuración.

### Capa 3: Firma MPC (Paratro)

AgentWallex utiliza el protocolo MPC de umbral 2-de-3 de Paratro:

| Fragmento   | Titular                          | Propósito         |
| ----------- | -------------------------------- | ----------------- |
| Fragmento 1 | Servicio de firma de AgentWallex | Firma activa      |
| Fragmento 2 | Nodo custodio independiente      | Firma activa      |
| Fragmento 3 | Almacenamiento en frío           | Solo recuperación |

**Propiedades críticas de seguridad:**

* La clave privada completa **nunca se reconstruye** en memoria
* Cualquier 2 de 3 fragmentos pueden firmar una transacción
* El compromiso de un solo fragmento no compromete la billetera
* La generación de claves usa Generación de Claves Distribuida (DKG) — ninguna parte individual ve jamás la clave completa

### Capa 4: Intervención humana

Para transacciones de alto valor o inusuales, AgentWallex puede dirigirlas a aprobación humana:

* Transacciones por encima de un umbral configurable
* Transacciones a direcciones nuevas (no vistas antes)
* Patrones inusuales detectados por monitoreo de anomalías

```json theme={null}
{
  "event": "approval.requested",
  "data": {
    "transactionId": "tx_pending_123",
    "agentId": "agent_abc123",
    "amount": "2500.00",
    "reason": "Amount exceeds humanApprovalThreshold (1000)",
    "expiresAt": "2025-01-15T11:00:00Z"
  }
}
```

Las aprobaciones pueden gestionarse mediante el panel de control, la API o la integración de webhooks.

## Arquitectura de políticas de dos capas

AgentWallex aplica políticas en dos niveles independientes:

### Capa de negocio (configurada por el desarrollador)

Sus reglas personalizadas — límites de gasto, listas blancas, controles de velocidad. Se configuran mediante la API o el panel de control y pueden actualizarse en cualquier momento.

### Red de seguridad de infraestructura (aplicada por Paratro)

Límites estrictos aplicados a nivel de firma MPC que **no pueden ser anulados** por llamadas a la API:

| Control                     | Valor predeterminado | Descripción                                                       |
| --------------------------- | -------------------- | ----------------------------------------------------------------- |
| Límite diario absoluto      | \$50,000             | Techo fijo independiente de la política de negocio                |
| Detección de anomalías      | Habilitada           | Análisis de patrones basado en ML                                 |
| Congelamiento de emergencia | Siempre disponible   | Bloqueo instantáneo de billetera                                  |
| Período de enfriamiento     | 10 minutos           | Después del congelamiento, no se puede descongelar inmediatamente |

<Warning>
  Incluso si su clave API se ve comprometida, la red de seguridad de infraestructura previene pérdidas catastróficas. El atacante no puede anular los límites aplicados por Paratro.
</Warning>

## Ciclo de vida de gestión de claves

### Generación de claves

Las claves se generan utilizando Generación de Claves Distribuida (DKG). En ningún momento ninguna parte ve la clave privada completa:

1. Cada uno de los 3 nodos MPC genera un fragmento aleatorio.
2. Los fragmentos se combinan criptográficamente para producir una clave pública.
3. La clave privada correspondiente existe solo como fragmentos distribuidos.

### Rotación de claves

Los fragmentos de claves se rotan periódicamente sin cambiar la dirección de la billetera. Esto se llama "compartición proactiva de secretos" — los fragmentos antiguos se vuelven inútiles después de la rotación.

### Congelamiento de emergencia

Cualquier parte autorizada puede congelar instantáneamente una billetera:

<CodeGroup>
  ```typescript SDK theme={null}
  await aw.agents.freeze("agent_abc123");
  ```

  ```bash API theme={null}
  curl -X PUT https://api.agentwallex.com/api/v1/agents/agent_abc123/status \
    -H "X-API-Key: awx_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"status": "inactive"}'
  ```
</CodeGroup>

Las billeteras congeladas no pueden firmar ninguna transacción hasta que se descongelen explícitamente (con un período obligatorio de enfriamiento).

## Registro de auditoría

Cada acción se registra de forma inmutable:

* Todas las solicitudes de API (con IP, user agent, marca de tiempo)
* Todas las evaluaciones de políticas (aprobado/rechazado con motivo)
* Todas las operaciones de firma
* Todos los eventos de congelamiento/descongelamiento
* Todas las entregas de webhooks

| Plan       | Retención de registros |
| ---------- | ---------------------- |
| Starter    | 90 días                |
| Growth     | 1 año                  |
| Enterprise | Personalizado          |

Consulte los registros de auditoría mediante la API:

```bash theme={null}
curl -X GET "https://api.agentwallex.com/api/v1/audit-logs?page_num=1&page_size=20" \
  -H "X-API-Key: awx_your_api_key"
```