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.

Four Layers of Security

Layer 1: Identity & 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:

• API keys can be rotated without downtime
• Session tokens auto-expire (configurable: 1-24 hours)
• Per-agent permission scoping
• IP allowlisting available on 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.

await aw.policies.update("agent_abc123", {
  // Spending limits
  maxTransactionAmount: "500",      // Per-transaction cap
  dailyLimit: "5000",               // Rolling 24-hour limit
 
  // Address controls
  allowedAddresses: ["0x..."],      // Whitelist (if set, only these)
  blockedAddresses: ["0x..."],      // Blacklist
 
  // Token controls
  allowedTokens: ["USDC", "USDT"], // Restrict token types
 
  // Velocity controls
  velocityLimit: {
    maxCount: 100,                  // Max transactions
    windowSeconds: 3600,            // Per hour
  },
 
  // Human approval
  requireHumanApproval: true,       // For high-value tx
  humanApprovalThreshold: "1000",   // Amount that triggers approval
});

Layer 3: MPC Signing (Paratro)

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

• Shard 1 — Held by the AgentWallex signing service
• Shard 2 — Held by an independent custodian node
• Shard 3 — Held in cold storage for recovery

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:

Even if your API key is compromised, the infrastructure safety net prevents catastrophic loss.

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:

// Via SDK
await aw.agents.freeze("agent_abc123");
 
// Via dashboard — one-click freeze
// Via API — PUT /agents/:id/status

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

Logs are retained for 90 days (Starter), 1 year (Growth), or custom (Enterprise).