Security Architecture

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.

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

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

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

Key Management Lifecycle

Key Generation

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

Each of the 3 MPC nodes generates a random share.
Shares are combined cryptographically to produce a public key.
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:

await aw.agents.freeze("agent_abc123");

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

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:

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"

Getting Started

Platform

Core Features

Guides

Security Architecture

Overview

Four Layers of Security

Layer 1: Identity and Authentication

Layer 2: Policy Engine

Layer 3: MPC Signing (Paratro)

Layer 4: Human-in-the-Loop

Two-Layer Policy Architecture

Business Layer (Developer-Configured)

Infrastructure Safety Net (Paratro-Enforced)

Key Management Lifecycle

Key Generation

Key Rotation

Emergency Freeze

Audit Logging

​Overview

​Four Layers of Security

​Layer 1: Identity and Authentication

​Layer 2: Policy Engine

​Layer 3: MPC Signing (Paratro)

​Layer 4: Human-in-the-Loop

​Two-Layer Policy Architecture

​Business Layer (Developer-Configured)

​Infrastructure Safety Net (Paratro-Enforced)

​Key Management Lifecycle

​Key Generation

​Key Rotation

​Emergency Freeze

​Audit Logging

Overview

Four Layers of Security

Layer 1: Identity and Authentication

Layer 2: Policy Engine

Layer 3: MPC Signing (Paratro)

Layer 4: Human-in-the-Loop

Two-Layer Policy Architecture

Business Layer (Developer-Configured)

Infrastructure Safety Net (Paratro-Enforced)

Key Management Lifecycle

Key Generation

Key Rotation

Emergency Freeze

Audit Logging