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

# Security Architecture

> Four layers of security — identity, policy engine, MPC signing, and human-in-the-loop — protect your agents.

## Overview

AgentWallex is built on the principle that AI agents should **never have access to private keys**. Instead, transactions are signed using Multi-Party Computation (MPC), where no single party ever holds the complete key.

The platform enforces security through four independent layers. A transaction must pass through all of them before it is broadcast to the blockchain.

## Four Layers of Security

### Layer 1: Identity and Authentication

Every API request is authenticated using a two-token system:

* **API Key** (`awx_...`) — Long-lived, identifies your account. Store securely in environment variables.
* **Session Token** — Short-lived, scoped to specific agents and operations. Automatically rotated.

```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
```

**Key properties:**

| Property           | Detail                      |
| ------------------ | --------------------------- |
| Key rotation       | Without downtime            |
| Session expiry     | Configurable: 1-24 hours    |
| Permission scoping | Per-agent                   |
| IP allowlisting    | Growth and Enterprise plans |

### Layer 2: Policy Engine

Every transaction must pass through the policy engine before signing. Policies are evaluated in order — the first violation stops the transaction.

The policy engine supports:

* Spending limits (per-transaction, daily, monthly)
* Address whitelists and blacklists
* Token restrictions
* Velocity controls (rate limiting)
* Time-based schedule rules
* Human approval routing

See [Policy Engine](/features/policy-engine) for full configuration details.

### Layer 3: MPC Signing (Paratro)

AgentWallex uses Paratro's 2-of-3 threshold MPC protocol:

| Shard   | Holder                      | Purpose        |
| ------- | --------------------------- | -------------- |
| Shard 1 | AgentWallex signing service | Active signing |
| Shard 2 | Independent custodian node  | Active signing |
| Shard 3 | Cold storage                | Recovery only  |

**Critical security properties:**

* The full private key is **never reconstructed** in memory
* Any 2 of 3 shards can sign a transaction
* Compromise of a single shard does not compromise the wallet
* Key generation uses Distributed Key Generation (DKG) — no single party ever sees the full key

### Layer 4: Human-in-the-Loop

For high-value or unusual transactions, AgentWallex can route to human approval:

* Transactions above a configurable threshold
* Transactions to new (unseen) addresses
* Unusual patterns detected by anomaly monitoring

```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"
  }
}
```

Approvals can be handled via the dashboard, API, or webhook integration.

## Two-Layer Policy Architecture

AgentWallex enforces policies at two independent levels:

### Business Layer (Developer-Configured)

Your custom rules — spending limits, whitelists, velocity controls. These are set via the API or dashboard and can be updated at any time.

### Infrastructure Safety Net (Paratro-Enforced)

Hard limits enforced at the MPC signing level that **cannot be overridden** by API calls:

| Control            | Default          | Description                                |
| ------------------ | ---------------- | ------------------------------------------ |
| Absolute daily cap | \$50,000         | Hard ceiling regardless of business policy |
| Anomaly detection  | Enabled          | ML-based pattern analysis                  |
| Emergency freeze   | Always available | Instant wallet lockdown                    |
| Cool-down period   | 10 minutes       | After freeze, cannot unfreeze immediately  |

<Warning>
  Even if your API key is compromised, the infrastructure safety net prevents catastrophic loss. The attacker cannot override Paratro-enforced limits.
</Warning>

## Key Management Lifecycle

### Key Generation

Keys are generated using Distributed Key Generation (DKG). At no point does any party see the full private key:

1. Each of the 3 MPC nodes generates a random share.
2. Shares are combined cryptographically to produce a public key.
3. The corresponding private key exists only as distributed shards.

### Key Rotation

Key shards are rotated periodically without changing the wallet address. This is called "proactive secret sharing" — old shards become useless after rotation.

### Emergency Freeze

Any authorized party can instantly freeze a wallet:

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

Frozen wallets cannot sign any transactions until explicitly unfrozen (with a mandatory cool-down period).

## Audit Logging

Every action is logged immutably:

* All API requests (with IP, user agent, timestamp)
* All policy evaluations (pass/fail with reason)
* All signing operations
* All freeze/unfreeze events
* All webhook deliveries

| Plan       | Log Retention |
| ---------- | ------------- |
| Starter    | 90 days       |
| Growth     | 1 year        |
| Enterprise | Custom        |

Query audit logs via the 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"
```