Deployment

Prerequisites

Before deploying Agentic Wallet, ensure you have the following installed:

Node.js >= 20
npm >= 10
Solana CLI >= 1.18 (required for devnet funding and escrow deployment)
Anchor CLI >= 0.31 (required for escrow program build and deployment)

Local Development Setup

Clone and Install

Install all dependencies for the monorepo:

npm install

Configure Environment

Copy the example environment file and configure required variables:

cp .env.example .env

Edit .env and set at minimum:

# Encryption secret for wallet key storage
WALLET_KEY_ENCRYPTION_SECRET=replace-with-long-random-secret

# API gateway authentication
API_GATEWAY_API_KEYS=dev-api-key:*:all

# Primary RPC endpoint
SOLANA_RPC_URL=https://api.devnet.solana.com

# RPC pool for failover (comma-separated)
SOLANA_RPC_POOL_URLS=https://api.devnet.solana.com

# Health probe interval (ms)
SOLANA_RPC_HEALTH_PROBE_MS=15000

API_GATEWAY_PORT=3000
WALLET_ENGINE_PORT=3002
POLICY_ENGINE_PORT=3003
AGENT_RUNTIME_PORT=3004
PROTOCOL_ADAPTERS_PORT=3005
TRANSACTION_ENGINE_PORT=3006
AUDIT_OBSERVABILITY_PORT=3007
MCP_SERVER_PORT=3008

For production deployments, generate strong random secrets using:

openssl rand -base64 32

Load Environment Variables

Export environment variables to your shell:

set -a; source .env; set +a

Start All Services

Launch the full stack using the development script:

npm run dev

This starts all services concurrently:

api-gateway (port 3000)
wallet-engine (port 3002)
policy-engine (port 3003)
agent-runtime (port 3004)
protocol-adapters (port 3005)
transaction-engine (port 3006)
audit-observability (port 3007)
mcp-server (port 3008)

Health Check Endpoints

Verify that all services are running correctly:

curl -s http://localhost:3000/health
# Expected: {"status":"ok","service":"api-gateway"}

curl -s http://localhost:3006/health
# Expected: {"status":"ok","service":"transaction-engine"}

curl -s http://localhost:3005/health
# Expected: {"status":"ok","service":"protocol-adapters"}

curl -s http://localhost:3002/health
# Expected: {"status":"ok","service":"wallet-engine"}

The CLI includes a built-in doctor command that checks all service health endpoints:

npm run cli -- doctor

Escrow Program Deployment

The Agentic Wallet includes a real Anchor escrow program that must be deployed to devnet.

Set Deployment Key

Configure your deployment wallet in .env:

# Base58 secret key or JSON byte array
PRIVATE_KEY=your-base58-secret-key

Ensure this wallet has sufficient SOL for program deployment (~5-10 SOL on devnet).

Build Escrow Program

Compile the Anchor program:

npm run escrow:build

This syncs the declare_id! macro and builds the program artifacts.

Deploy to Devnet

Deploy the compiled program:

npm run escrow:deploy:devnet

This command:

Syncs declare_id! and Anchor.toml from the deploy keypair
Builds and deploys via Anchor CLI
Automatically updates .env with ESCROW_PROGRAM_ID=<deployed_id>

Verify Escrow Adapter

Check that the escrow adapter is properly configured:

curl -s -H 'x-api-key: dev-api-key' \
  http://localhost:3000/api/v1/protocols/escrow/health

Expected response:

{
  "ok": true,
  "configured": true,
  "deployed": true
}

Validation and Quality Gates

Run the full validation suite before deploying:

npm run secret:scan

npm run lint

npm run typecheck

npm run test

npm run build

npm run ci:check

Devnet Smoke Tests

Validate the deployment with end-to-end smoke tests:

# Tests wallet creation, SOL transfers, and basic intents
npm run devnet:smoke

# Tests concurrent agent execution
npm run devnet:multi-agent

# Tests all protocol adapters
npm run devnet:protocol-matrix

# Full end-to-end demo with proof artifacts
npm run demo:judge

Environment Configuration Reference

RPC and Execution Tuning

# Primary RPC endpoint
SOLANA_RPC_URL=https://api.devnet.solana.com

# Pool of RPC endpoints for failover (comma-separated)
SOLANA_RPC_POOL_URLS=https://api.devnet.solana.com,https://rpc.ankr.com/solana_devnet

# Health probe interval in milliseconds
SOLANA_RPC_HEALTH_PROBE_MS=15000

# Priority fee bounds (microlamports)
SOLANA_PRIORITY_FEE_MIN_MICROLAMPORTS=2000
SOLANA_PRIORITY_FEE_MAX_MICROLAMPORTS=200000

# Fee percentile for adaptive tuning
SOLANA_PRIORITY_FEE_PERCENTILE=75

# Fee multiplier in basis points (1150 = 1.15x)
SOLANA_PRIORITY_FEE_MULTIPLIER_BPS=1150

# Delta guard tolerance for balance verification
DELTA_GUARD_ABSOLUTE_TOLERANCE_LAMPORTS=10000

Storage and Durability

# Data directories for each service
WALLET_ENGINE_DATA_DIR=services/wallet-engine/data
POLICY_ENGINE_DATA_DIR=services/policy-engine/data
AGENT_RUNTIME_DATA_DIR=services/agent-runtime/data
TRANSACTION_ENGINE_DATA_DIR=services/transaction-engine/data
AUDIT_OBSERVABILITY_DATA_DIR=services/audit-observability/data

# Optional explicit SQLite database paths
TRANSACTION_ENGINE_DB_PATH=
AGENT_RUNTIME_DB_PATH=
POLICY_ENGINE_DB_PATH=
AUDIT_OBSERVABILITY_DB_PATH=
WALLET_ENGINE_DB_PATH=

Outbox Queue Configuration

# Lease duration for outbox jobs (ms)
TX_OUTBOX_LEASE_MS=30000

# Polling interval for outbox worker (ms)
TX_OUTBOX_POLL_MS=2000

# Maximum retry attempts for failed jobs
TX_OUTBOX_MAX_ATTEMPTS=6

See .env.example in the repository root for the complete list of configuration options.

Getting Started

Architecture

Core Concepts

Operations

Security

Integration

Prerequisites

Local Development Setup

Health Check Endpoints

Escrow Program Deployment

Validation and Quality Gates

Devnet Smoke Tests

Environment Configuration Reference

RPC and Execution Tuning

Storage and Durability

Outbox Queue Configuration

​Prerequisites

​Local Development Setup

​Health Check Endpoints

​Escrow Program Deployment

​Validation and Quality Gates

​Devnet Smoke Tests

​Environment Configuration Reference

​RPC and Execution Tuning

​Storage and Durability

​Outbox Queue Configuration

Prerequisites

Local Development Setup

Health Check Endpoints

Escrow Program Deployment

Validation and Quality Gates

Devnet Smoke Tests

Environment Configuration Reference

RPC and Execution Tuning

Storage and Durability

Outbox Queue Configuration