Skip to main content

​
Service Map

Agentic Wallet consists of 7 services + 2 apps orchestrated through a central API Gateway:
ServicePortResponsibility
apps/api-gateway3000Auth, tenant scope checks, rate limiting, response normalization, routing
services/wallet-engine3002Wallet creation, key custody, signing APIs, SOL/SPL balance reads
services/policy-engine3003Allow/deny/require_approval rule evaluation
services/agent-runtime3004Agent lifecycle, capabilities, execution modes, treasury/strategy endpoints
services/protocol-adapters3005Protocol registry, quote/build endpoints, escrow adapter
services/transaction-engine3006Transaction lifecycle, simulation, policy gate, submit/confirm, proofs, outbox
services/audit-observability3007Audit events and metrics aggregation
services/mcp-server3008MCP-compatible tools and generic gateway proxy tool
packages/commonN/AShared schemas, types, validation
packages/sdkN/ATyped client for API gateway

​
API Gateway (Port 3000)

apps/api-gateway

Entry point for all external requests

​
Responsibilities

  • Authentication: API key validation (x-api-key header)
  • Authorization: Route-based scope checking (wallets, transactions, policies, agents, protocols, etc.)
  • Tenant Isolation: Optional tenant boundary enforcement (x-tenant-id header)
  • Rate Limiting: Per-key rate limiting (default 120 req/min)
  • Response Normalization: Converts all upstream responses to stable machine envelope
  • Routing: Proxies requests to appropriate backend services

​
Technology Stack

  • Framework: Hono
  • Runtime: Node.js
  • State: In-memory rate limit tracking

​
Configuration

API_GATEWAY_PORT=3000
API_GATEWAY_ENFORCE_AUTH=true
API_GATEWAY_API_KEYS=dev-api-key:*:all
API_GATEWAY_RATE_LIMIT_PER_MINUTE=120

​
Normalized Response Envelope

Every response includes: 
{
  "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": { /* actual response payload */ },
  "error": "error message (if failure)",
  "errorMessage": "error message (if failure)"
}

​
Routing Table

Route PatternTarget ServiceScope
/api/v1/wallets/**wallet-enginewallets
/api/v1/transactions/**transaction-enginetransactions
/api/v1/policies/**policy-enginepolicies
/api/v1/agents/**agent-runtimeagents
/api/v1/protocols/**protocol-adaptersprotocols
/api/v1/risk/**transaction-enginerisk
/api/v1/audit/**audit-observabilityaudit
/mcp/**mcp-servermcp

​
Wallet Engine (Port 3002)

services/wallet-engine

Key custody and signing boundary

​
Responsibilities

  • Wallet Creation: Generate new Solana keypairs
  • Key Storage: Persist encrypted private keys
  • Transaction Signing: Sign legacy and versioned transactions
  • Message Signing: Sign arbitrary messages (not yet exposed)
  • Balance Queries: Fetch SOL balance and SPL token balances
  • Signer Backend Abstraction: Support multiple custody strategies

​
Key Features

Pluggable Backends

  • encrypted-file: AES-256-GCM on disk
  • memory: Ephemeral in-memory
  • kms: Key management service
  • hsm: Hardware security module
  • mpc: Multi-party computation

Encryption Details

  • Algorithm: AES-256-GCM
  • Key Derivation: scrypt
  • Per-record: Random salt + IV
  • Auth Tag: Verified on decrypt

​
Technology Stack

  • Framework: Hono
  • Storage: SQLite (metadata) + file storage (encrypted keys)
  • Crypto: Node.js crypto module
  • RPC: @solana/web3.js, @solana/spl-token

​
Configuration

WALLET_ENGINE_PORT=3002
WALLET_ENGINE_DATA_DIR=./data/wallet-engine
WALLET_SIGNER_BACKEND=encrypted-file
WALLET_KEY_ENCRYPTION_SECRET=your-secret-here

# KMS backend
WALLET_KMS_MASTER_SECRET=...
WALLET_KMS_KEY_ID=...

# HSM backend
WALLET_HSM_PIN=...
WALLET_HSM_MODULE_SECRET=...
WALLET_HSM_SLOT=0

# MPC backend (requires 3 node secrets)
WALLET_MPC_NODE_SECRETS=secret1,secret2,secret3

​
Key Endpoints

  • POST /api/v1/wallets - Create new wallet
  • GET /api/v1/wallets/:walletId - Get wallet info
  • GET /api/v1/wallets/:walletId/balance - Get SOL balance
  • GET /api/v1/wallets/:walletId/tokens - Get SPL token balances
  • POST /api/v1/wallets/:walletId/sign - Sign transaction
The wallet-engine is the only service that can read private keys and sign transactions. This creates a security boundary where agents and external clients never have access to key material.

​
Policy Engine (Port 3003)

services/policy-engine

Policy evaluation and rule engine

​
Responsibilities

  • Policy Creation: Define wallet-specific policies with versioned rules
  • Policy Evaluation: Execute rule evaluation for transaction requests
  • Rule Types: Support 11 rule types (spending limits, allowlists, rate limits, etc.)
  • Versioning: Track policy version history with migration support
  • Fail-Secure: Return deny on evaluation errors

​
Supported Rule Types

  • spending_limit: Max lamports per transaction or time window
  • rate_limit: Max transactions per time period
  • time_window: Restrict execution to specific hours/days
  • address_allowlist: Permitted destination addresses
  • address_blocklist: Blocked destination addresses
  • program_allowlist: Permitted Solana program IDs
  • token_allowlist: Permitted SPL token mints
  • protocol_allowlist: Permitted protocol names
  • max_slippage: Maximum slippage tolerance for swaps
  • protocol_risk: Protocol-specific risk parameters
  • portfolio_risk: Portfolio-level exposure limits

​
Technology Stack

  • Framework: Hono
  • Storage: SQLite (policies + evaluation state)
  • Validation: Zod schemas from @agentic-wallet/common

​
Configuration

POLICY_ENGINE_PORT=3003
POLICY_ENGINE_DATA_DIR=./data/policy-engine

​
Key Endpoints

  • POST /api/v1/policies - Create policy
  • PUT /api/v1/policies/:policyId - Update policy
  • GET /api/v1/wallets/:walletId/policies - List wallet policies
  • POST /api/v1/evaluate - Evaluate transaction against policies
  • GET /api/v1/policies/:policyId/versions - Get policy version history
  • POST /api/v1/policies/:policyId/migrate - Migrate policy to new version

​
Decision Output

{
  decision: 'allow' | 'deny' | 'require_approval',
  reasons: string[],
  riskTier: 'low' | 'medium' | 'high'
}

​
Transaction Engine (Port 3006)

services/transaction-engine

Transaction orchestration and execution pipeline

​
Responsibilities

  • Transaction Lifecycle Management: Orchestrate full execution pipeline
  • Build: Construct unsigned transactions (local or via protocol-adapters)
  • Simulation: Pre-execution validation via Solana RPC
  • Risk Evaluation: Protocol risk and portfolio risk checks
  • Policy Gate: Call policy-engine for evaluation
  • Approval Gate: Pause for manual approval when required
  • Signing: Request signature from wallet-engine
  • Submission: Submit to Solana RPC (or Kora for gasless)
  • Confirmation: Wait for transaction confirmation
  • Proof Generation: Create execution proof with hashes
  • Position Tracking: Index DeFi positions (stake, lend, escrow)
  • Durable Outbox: Queue with lease/retry for reliability

​
Transaction Lifecycle States

pending -> simulating -> policy_eval -> approval_gate -> signing -> submitting -> confirmed
                                    |
                                    v
                                 failed

​
Technology Stack

  • Framework: Hono
  • Storage: SQLite (transactions, outbox, risk configs, positions, escrows, proofs)
  • RPC: @solana/web3.js with failover pool
  • Execution Tuning: Adaptive priority fee and compute budget

​
Configuration

TRANSACTION_ENGINE_PORT=3006
TRANSACTION_ENGINE_DATA_DIR=./data/transaction-engine
SOLANA_RPC_URL=https://api.devnet.solana.com
SOLANA_RPC_POOL_URLS=https://api.devnet.solana.com,https://rpc.ankr.com/solana_devnet
SOLANA_RPC_HEALTH_PROBE_MS=15000
SOLANA_PRIORITY_FEE_MIN_MICROLAMPORTS=2000
SOLANA_PRIORITY_FEE_MAX_MICROLAMPORTS=200000
SOLANA_PRIORITY_FEE_PERCENTILE=75
SOLANA_PRIORITY_FEE_MULTIPLIER_BPS=1150
DELTA_GUARD_ABSOLUTE_TOLERANCE_LAMPORTS=10000
TX_OUTBOX_LEASE_MS=30000
TX_OUTBOX_POLL_MS=2000
TX_OUTBOX_MAX_ATTEMPTS=6

​
Key Endpoints

  • POST /api/v1/transactions - Create transaction
  • GET /api/v1/transactions/:txId - Get transaction status
  • POST /api/v1/transactions/:txId/retry - Retry failed transaction
  • POST /api/v1/transactions/:txId/approve - Approve pending transaction
  • POST /api/v1/transactions/:txId/reject - Reject pending transaction
  • GET /api/v1/transactions/:txId/proof - Get execution proof
  • GET /api/v1/transactions/:txId/replay - Get replay data
  • GET /api/v1/wallets/:walletId/transactions - List wallet transactions
  • GET /api/v1/wallets/:walletId/pending-approvals - List pending approvals
  • GET /api/v1/wallets/:walletId/positions - List DeFi positions
  • GET /api/v1/wallets/:walletId/escrows - List escrow positions
  • GET /api/v1/risk/protocols - List protocol risk configs
  • GET /api/v1/risk/protocols/:protocol - Get protocol risk config
  • PUT /api/v1/risk/protocols/:protocol - Update protocol risk config
  • GET /api/v1/risk/portfolio - List portfolio risk configs
  • GET /api/v1/risk/portfolio/:walletId - Get wallet portfolio risk
  • PUT /api/v1/risk/portfolio/:walletId - Update wallet portfolio risk
  • GET /api/v1/chaos - Get chaos switchboard config
  • PUT /api/v1/chaos - Update chaos switchboard config

​
Execution Proof Structure

{
  intentHash: string,      // SHA-256 of intent
  policyHash: string,      // SHA-256 of policy decision
  simulationHash: string,  // SHA-256 of simulation result
  proofHash: string,       // SHA-256 of combined proof
  signature: string,       // Solana transaction signature
  txId: string,
  walletId: string,
  agentId?: string,
  timestamp: string
}

​
Agent Runtime (Port 3004)

services/agent-runtime

Agent lifecycle and autonomous execution

​
Responsibilities

  • Agent Management: Create, start, stop, pause, resume agents
  • Capability Control: Intent and protocol allowlists per agent
  • Execution Modes: Supervised vs autonomous operation
  • Autonomous Decision Engine: Rule-based autonomous strategy execution
  • Budget Management: Per-agent spending budgets
  • Capability Manifests: Issue and verify signed capability manifests
  • Strategy Execution: Backtesting and paper trading
  • Treasury Operations: Budget allocation and rebalancing

​
Execution Modes

Supervised

Agent executes only when explicitly called via API. Used for agent-driven execution where the agent makes all decisions.

Autonomous

Agent runs on a scheduler with built-in decision engine. Executes strategies based on conditions, cadence, and cooldowns.

​
Technology Stack

  • Framework: Hono
  • Storage: SQLite (agents, budgets, strategies, paper trades)
  • Scheduler: Interval-based loop with per-agent decision state
  • Manifest Signing: HMAC-SHA256 with secret

​
Configuration

AGENT_RUNTIME_PORT=3004
AGENT_RUNTIME_DATA_DIR=./data/agent-runtime
AGENT_LOOP_INTERVAL_MS=5000
AGENT_MANIFEST_SIGNING_SECRET=dev-manifest-secret
AGENT_MANIFEST_ISSUER=agent-runtime
AGENT_REQUIRE_MANIFEST=false
AGENT_REQUIRE_BACKTEST_PASS=false
AGENT_PAUSE_WEBHOOK_SECRET=

​
Key Endpoints

  • POST /api/v1/agents - Create agent
  • GET /api/v1/agents - List agents
  • GET /api/v1/agents/:agentId - Get agent
  • PUT /api/v1/agents/:agentId/capabilities - Update capabilities
  • POST /api/v1/agents/:agentId/start - Start agent
  • POST /api/v1/agents/:agentId/stop - Stop agent
  • POST /api/v1/agents/:agentId/pause - Pause agent
  • POST /api/v1/agents/:agentId/resume - Resume agent
  • GET /api/v1/agents/:agentId/budget - Get agent budget
  • POST /api/v1/treasury/allocate - Allocate funds to agent
  • POST /api/v1/treasury/rebalance - Rebalance between agents
  • POST /api/v1/strategy/backtest - Run backtest
  • POST /api/v1/strategy/paper/execute - Paper trade execution
  • GET /api/v1/strategy/paper/:agentId - List paper trades
  • POST /api/v1/agents/:agentId/manifest/issue - Issue signed manifest
  • POST /api/v1/agents/:agentId/manifest/verify - Verify manifest
  • POST /api/v1/agents/:agentId/execute - Execute agent intent
  • GET /api/v1/agents/:agentId/autonomy/state - Get autonomy state

​
Protocol Adapters (Port 3005)

services/protocol-adapters

Protocol-specific transaction building

​
Responsibilities

  • Adapter Registry: Register and manage protocol adapters
  • Quote Fetching: Get swap quotes from DEX protocols
  • Transaction Building: Construct protocol-specific instructions
  • Health Checks: Verify protocol adapter health and dependencies
  • Version Management: Track adapter versions and migrations
  • Intent Migration: Migrate intents between adapter versions

​
Supported Protocols (7 + system)

System Program

transfer_sol - Native SOL transfers

SPL Token

transfer_spl, create_mint, mint_token - Token operations

Jupiter

swap - Aggregated DEX swaps with quote API

Marinade

stake, unstake - Liquid staking (mSOL)

Solend

lend_supply, lend_borrow - Lending protocol

Metaplex

NFT minting intents (static builder)

Orca

DEX swap intents (static builder)

Raydium

DEX swap intents (static builder)

Escrow (Anchor)

9 escrow instructions backed by real on-chain program:
  • create_escrow, accept_escrow, release_escrow
  • refund_escrow, dispute_escrow, resolve_dispute
  • create_milestone_escrow, release_milestone, x402_pay

​
Technology Stack

  • Framework: Hono
  • Storage: In-memory adapter registry
  • External APIs: Jupiter API for quotes, protocol-specific APIs

​
Configuration

PROTOCOL_ADAPTERS_PORT=3005
JUPITER_API_URL=https://lite-api.jup.ag/swap/v1
ESCROW_PROGRAM_ID=<deployed_program_id>
KORA_RPC_URL=http://localhost:8080

​
Key Endpoints

  • GET /api/v1/protocols - List all protocols
  • GET /api/v1/protocols/:protocol/capabilities - Get protocol capabilities
  • GET /api/v1/protocols/:protocol/version - Get protocol version
  • GET /api/v1/protocols/health - Health check all protocols
  • GET /api/v1/protocols/:protocol/health - Health check specific protocol
  • POST /api/v1/protocols/:protocol/compatibility-check - Check version compatibility
  • POST /api/v1/protocols/:protocol/migrate-intent - Migrate intent between versions
  • POST /api/v1/defi/quote - Get swap quote
  • POST /api/v1/defi/swap - Build swap transaction
  • POST /api/v1/defi/stake - Build stake transaction
  • POST /api/v1/defi/unstake - Build unstake transaction
  • POST /api/v1/defi/lend/supply - Build lend supply transaction
  • POST /api/v1/defi/lend/borrow - Build lend borrow transaction
  • POST /api/v1/escrow/create - Create escrow
  • POST /api/v1/escrow/:id/accept - Accept escrow
  • POST /api/v1/escrow/:id/release - Release escrow
  • POST /api/v1/escrow/:id/refund - Refund escrow
  • POST /api/v1/escrow/:id/dispute - Dispute escrow
  • POST /api/v1/escrow/:id/resolve - Resolve dispute
  • POST /api/v1/build - Generic intent builder (used by transaction-engine)

​
Audit & Observability (Port 3007)

services/audit-observability

Audit event stream and metrics aggregation

​
Responsibilities

  • Audit Event Ingestion: Accept audit events from all services
  • Event Storage: Persist events to SQLite
  • Event Querying: Query audit log by entity, type, or time range
  • Metrics Counting: Increment counters for operational metrics
  • Metrics Retrieval: Retrieve counter values

​
Technology Stack

  • Framework: Hono
  • Storage: SQLite (audit events + metrics)

​
Configuration

AUDIT_OBSERVABILITY_PORT=3007
AUDIT_OBSERVABILITY_DATA_DIR=./data/audit-observability

​
Key Endpoints

  • POST /api/v1/audit/events - Submit audit event
  • GET /api/v1/audit/events - Query audit events
  • POST /api/v1/metrics/inc - Increment metric counter
  • GET /api/v1/metrics - Get all metric counters

​
Audit Event Schema

{
  id: string,
  entityType: 'transaction' | 'agent' | 'wallet' | 'policy',
  entityId: string,
  eventType: string,
  timestamp: string,
  payload: Record<string, unknown>,
  txId?: string,
  walletId?: string,
  agentId?: string,
  protocol?: string,
  escrowId?: string
}

​
MCP Server (Port 3008)

services/mcp-server

Model Context Protocol tool interface

​
Responsibilities

  • MCP Tools: Expose wallet operations as MCP tools
  • Gateway Proxy: Generic gateway.request tool for arbitrary API calls
  • Tool Discovery: List available tools with schemas

​
Technology Stack

  • Framework: Hono
  • Protocol: MCP (Model Context Protocol)

​
Configuration

MCP_SERVER_PORT=3008

​
Key Endpoints

  • GET /mcp/tools - List available MCP tools
  • POST /mcp/call - Call MCP tool

​
Available MCP Tools

  • wallet.create - Create new wallet
  • wallet.balance - Get wallet balance
  • tx.create - Create transaction
  • tx.get - Get transaction
  • policy.evaluate - Evaluate policy
  • protocol.quote - Get protocol quote
  • agent.execute - Execute agent intent
  • risk.get_protocol - Get protocol risk config
  • risk.set_protocol - Set protocol risk config
  • gateway.request - Generic gateway proxy (validated routes only)

​
Shared Packages

​
packages/common

@agentic-wallet/common

Shared schemas, types, and validation
  • Zod Schemas: All request/response schemas
  • Type Exports: TypeScript types for all entities
  • Validation: Centralized validation logic

​
packages/sdk

@agentic-wallet/sdk

Typed TypeScript client
  • Type-Safe Client: Fully typed API client
  • Error Handling: Normalized error responses
  • Request Building: Helper methods for all endpoints

​
Inter-Service Communication

​
Communication Pattern

All services communicate via HTTP REST APIs on localhost: 
// Transaction Engine calling Wallet Engine
const wallet = await fetch(`${walletEngineUrl}/api/v1/wallets/${walletId}`);

// Transaction Engine calling Policy Engine
const decision = await fetch(`${policyEngineUrl}/api/v1/evaluate`, {
  method: 'POST',
  body: JSON.stringify(evaluationRequest)
});

​
Service Discovery

Services are discovered via environment variables: 
WALLET_ENGINE_URL=http://localhost:3002
POLICY_ENGINE_URL=http://localhost:3003
AGENT_RUNTIME_URL=http://localhost:3004
PROTOCOL_ADAPTERS_URL=http://localhost:3005
TRANSACTION_ENGINE_URL=http://localhost:3006
AUDIT_OBSERVABILITY_URL=http://localhost:3007
MCP_SERVER_URL=http://localhost:3008

​
Error Handling

Services use fail-secure error handling:
  • If policy-engine is unreachable → transaction-engine returns deny
  • If wallet-engine signing fails → transaction-engine marks transaction as failed
  • If RPC is unavailable → RPC pool failover kicks in

​
Best-Effort Sinks

Audit and metrics calls are best-effort: 
try {
  await fetch(`${auditUrl}/api/v1/audit/events`, { ... });
} catch {
  // Audit failure does not block transaction execution
}

​
Next Steps

Execution Flow

Deep dive into transaction and escrow lifecycles

Trust Boundaries

Security model and control boundaries

Build docs developers (and LLMs) love

Get started for freeTalk to us