Skip to main content

​
Security Architecture

Agentic Wallet implements a defense-in-depth security model with multiple trust boundaries and protection layers. The system is designed to ensure that AI agents can execute blockchain transactions autonomously while maintaining strict security controls.

Key Isolation

Private keys never leave the wallet-engine boundary

Policy Enforcement

All spend-capable intents pass policy evaluation

Gateway Protection

API key authentication, scopes, and rate limiting

Capability Governance

Agent permission controls and signed manifests

​
Trust Boundaries

The platform enforces strict trust boundaries at multiple layers:

​
Agent Boundary

Agents operate in a zero-trust model for key material:
  • Agents never receive or hold private keys
  • Agents emit high-level intents only (e.g., “transfer 0.1 SOL to address X”)
  • Intent validation happens server-side before any signing occurs
  • Agents cannot bypass the signing boundary

​
Signing Boundary

The wallet-engine service is the exclusive signing authority:
  • Private key material is isolated within the wallet-engine process
  • Only wallet-engine can access key providers (encrypted-file, KMS, HSM, MPC)
  • All transaction signing requests must go through the wallet-engine API
  • No direct key access from other services or agents
From services/wallet-engine/src/app.ts:67: 
app.post('/wallets/:walletId/sign', async (c) => {
  // Signing is exclusively controlled by wallet-engine
  const keypair = await keyProvider.load(walletId);
  const signature = transaction.sign([keypair]);
  // Keys never leave this boundary
});

​
Policy Boundary

All spend-capable intents pass through policy evaluation before signing:
1

Intent Submission

Agent submits intent via API gateway
2

Schema Validation

Request validated against Zod schemas in packages/common
3

Policy Evaluation

Policy engine evaluates rules and returns allow, deny, or require_approval
4

Approval Gate (if needed)

Transaction pauses at approval_gate status until operator approves/rejects
5

Signing

Only after passing policy checks does wallet-engine sign the transaction
Read-only intents like query_balance and query_positions skip the signing stage and confirm immediately.

​
Protocol Boundary

The protocol-adapters service provides a safe abstraction layer:
  • Agents submit protocol-agnostic intents (e.g., swap, stake, create_escrow)
  • Protocol adapters translate intents into protocol-specific transactions
  • Adapters handle complex DeFi interactions (Jupiter, Marinade, Solend, Orca, etc.)
  • Unsafe operations are blocked at build time

​
Gateway Protections

The API gateway (apps/api-gateway) provides the first line of defense:

​
Authentication

API key-based authentication with configurable enforcement: 
API_GATEWAY_ENFORCE_AUTH=true
API_GATEWAY_API_KEYS=key:tenant:scope1,scope2;key2:*:all
  • Each API key can be scoped to specific tenants
  • Keys can have granular permission scopes (wallets, transactions, policies, agents, etc.)
  • Missing or invalid keys result in 401 Unauthorized
  • Tenant mismatches result in 403 Forbidden
From apps/api-gateway/src/index.ts:284: 
if (enforceAuth) {
  const keyConfig = apiKeys.get(apiKey);
  if (!keyConfig) {
    return machineErrorResponse(c.req.raw, 401, 
      'Unauthorized: missing or invalid x-api-key', 'gateway', 'PIPELINE_ERROR');
  }
}

​
Scope-Based Authorization

The gateway enforces granular scopes for different API surface areas:
ScopeCoverage
walletsWallet creation, balance, token queries
transactionsTransaction lifecycle operations
policiesPolicy creation, evaluation, versioning
agentsAgent runtime, capabilities, manifests
protocolsProtocol adapters, DeFi operations, escrow
riskRisk controls, chaos engineering
strategyBacktesting, paper trading
treasuryBudget allocation, rebalancing
auditAudit events, metrics
mcpMCP tools endpoint
allWildcard access to all scopes
Scope violations return 403 Forbidden with the missing scope name.

​
Rate Limiting

Per-API-key rate limiting prevents abuse: 
API_GATEWAY_RATE_LIMIT_PER_MINUTE=120
  • Sliding window rate limiter tracks requests per API key
  • Exceeding the limit returns 429 Too Many Requests
  • Rate limits reset every 60 seconds
  • Separate counters maintained per API key
From apps/api-gateway/src/index.ts:317: 
if (state.count > rateLimitPerMinute) {
  return machineErrorResponse(c.req.raw, 429, 
    'Too Many Requests', 'gateway', 'PIPELINE_ERROR');
}

​
Normalized Error Envelope

The gateway normalizes all responses into a machine-readable format: 
{
  "status": "success|failure",
  "errorCode": "VALIDATION_ERROR|POLICY_VIOLATION|PIPELINE_ERROR|CONFIRMATION_FAILED|null",
  "failedAt": "validation|policy|build|sign|send|confirm|completed|gateway|null",
  "stage": "validation|policy|build|sign|send|confirm|completed|gateway",
  "traceId": "uuid",
  "data": {},
  "error": "optional string",
  "errorMessage": "optional string"
}
This envelope provides:
  • Consistent error reporting across all services
  • Deterministic stage tracking for debugging
  • Trace IDs for request correlation
  • Machine-parseable error codes for automation

​
Capability Governance

Agents are constrained by capability controls at multiple levels:

​
Intent Allowlists

Each agent has an explicit allowedIntents array: 
{
  "agentId": "uuid",
  "name": "trading-bot",
  "allowedIntents": ["transfer_sol", "swap", "query_balance"],
  "executionMode": "autonomous"
}
  • Agents can only execute intents in their allowlist
  • Attempts to execute disallowed intents are rejected at runtime
  • Intent permissions can be updated via PUT /api/v1/agents/:agentId/capabilities

​
Execution Modes

Agents operate in one of two modes:

Autonomous Mode

Agent can execute allowed intents without human approval (subject to policy constraints)

Supervised Mode

All agent executions require human approval before signing

​
Signed Capability Manifests

For high-security environments, agents can be required to present signed capability manifests: 
AGENT_REQUIRE_MANIFEST=true
AGENT_MANIFEST_SIGNING_SECRET=your-secret
AGENT_MANIFEST_ISSUER=your-issuer-id
Manifest issuance: 
npm run cli -- agent manifest-issue <agentId> \
  --intents transfer_sol swap \
  --protocols system-program jupiter \
  --ttl 3600
Manifest verification:
  • The agent-runtime verifies manifest signatures before execution
  • Manifests have time-to-live (TTL) expiration
  • Intent and protocol permissions are enforced at runtime
  • Invalid or expired manifests result in execution rejection
Manifest enforcement is optional but recommended for production deployments with autonomous agents.

​
Security Best Practices

1

Use Strong Encryption Secrets

Set a cryptographically random WALLET_KEY_ENCRYPTION_SECRET for production
2

Choose Production Signer Backend

Use kms, hsm, or mpc signer backends for production (not encrypted-file or memory)
3

Enable Gateway Authentication

Keep API_GATEWAY_ENFORCE_AUTH=true in production
4

Use Scoped API Keys

Grant minimum necessary scopes per API key (avoid all scope)
5

Attach Wallet Policies

Create spending limits, allowlists, and risk rules for every wallet
6

Enable Manifest Signing

Require signed capability manifests for autonomous agents
7

Monitor Audit Events

Regularly review audit events via GET /api/v1/audit/events
8

Test in Supervised Mode

Start new agents in supervised mode before granting autonomous execution

​
Threat Model

​
In Scope

  • Compromised agent logic: Policy enforcement and capability controls limit blast radius
  • API key theft: Rate limiting and scope constraints reduce impact
  • Malicious intents: Policy engine evaluates all spend-capable intents
  • Replay attacks: Idempotency keys prevent duplicate submissions

​
Out of Scope

  • Host compromise: If the wallet-engine process is compromised, keys are at risk
  • RPC manipulation: Agentic Wallet trusts the configured Solana RPC endpoints
  • Smart contract vulnerabilities: Protocol adapter safety depends on upstream contracts
  1. Host Isolation: Run wallet-engine in an isolated environment (separate container, VM, or network segment)
  2. Secret Management: Use external secret managers (AWS Secrets Manager, HashiCorp Vault) for sensitive environment variables
  3. Network Segmentation: Place wallet-engine behind a firewall, accessible only to transaction-engine
  4. Key Rotation: Implement periodic key rotation for KMS/HSM backends
  5. Audit Logging: Enable comprehensive audit logging and forward to a SIEM
  6. Webhook Alerts: Configure AGENT_PAUSE_WEBHOOK_SECRET for real-time breach notifications

Key Management

Private key storage, rotation, and signer backends

Policy Enforcement

Policy evaluation flow and rule types

Signer Backends

Encrypted-file, memory, KMS, HSM, and MPC options

Build docs developers (and LLMs) love

Get started for freeTalk to us