Quickstart

Get a working Agentic Wallet infrastructure up and running in under 5 minutes.

Prerequisites

Before you begin, ensure you have:

Node.js ≥ 20
npm ≥ 10
Solana CLI ≥ 1.18 (for devnet funding)

See the Installation guide for detailed prerequisite setup.

Quick Setup

Clone and Install

git clone https://github.com/aypp23/agentic-wallet.git
cd agentic-wallet
npm install

Configure Environment

cp .env.example .env

Edit .env and set minimum required variables:

# Encryption key for wallet storage (generate with: openssl rand -base64 32)
WALLET_KEY_ENCRYPTION_SECRET=your-secret-key-here

# Default API key for development
API_GATEWAY_API_KEYS=dev-api-key:*:all

Start Services

set -a; source .env; set +a
npm run dev

This starts all 8 services:

API Gateway (3000)
Wallet Engine (3002)
Policy Engine (3003)
Agent Runtime (3004)
Protocol Adapters (3005)
Transaction Engine (3006)
Audit & Observability (3007)
MCP Server (3008)

Verify Health

In a new terminal, check that services are running:

curl http://localhost:3000/health
curl http://localhost:3006/health

Both should return {"ok":true}.

Create a Wallet

npm run cli -- wallet create demo-wallet

Example output:

{
  "walletId": "123e4567-e89b-12d3-a456-426614174000",
  "publicKey": "7vHC...abc",
  "label": "demo-wallet"
}

Save the walletId for the next step.

Execute Your First Transaction

Create a simple SOL transfer:

npm run intent-runner -- --intent '{
  "walletId": "YOUR_WALLET_ID",
  "type": "transfer_sol",
  "protocol": "system-program",
  "intent": {
    "destination": "11111111111111111111111111111111",
    "lamports": 1000
  }
}'

The transaction will flow through:

Validation - Schema and input checks
Simulation - Pre-execution simulation
Policy Evaluation - Rule checks
Signing - Secure key signing
Submission - RPC submission
Confirmation - On-chain confirmation

You’re ready! You now have a working Agentic Wallet infrastructure.

What’s Next?

Installation Guide

Complete installation and production setup

Configuration

Environment variables and advanced configuration

Create Wallets

Learn wallet creation and management

Execute Transactions

Transaction execution workflows

Common Next Steps

Fund a Wallet (Devnet)

For testing on devnet, fund your wallet with SOL:

solana airdrop 2 YOUR_PUBLIC_KEY --url devnet

Or use the auto-fund feature during wallet creation:

npm run wallets -- create --label funded-wallet --auto-fund --fund-lamports 2000000

Query Wallet Balance

npm run cli -- wallet balance YOUR_WALLET_ID

Deploy Escrow Program

To use escrow operations, deploy the Anchor program:

npm run escrow:build
npm run escrow:deploy:devnet

Run Smoke Tests

Verify the full stack with automated tests:

npm run devnet:smoke
npm run devnet:multi-agent
npm run devnet:protocol-matrix

Troubleshooting

Port already in use (EADDRINUSE)

Kill processes using the required ports:

PIDS=$(for p in 3000 3002 3003 3004 3005 3006 3007 3008; do lsof -ti tcp:$p; done | sort -u)
[ -n "$PIDS" ] && kill $PIDS

Then restart: npm run dev

Environment variables not loaded

Make sure you export variables before starting services:

set -a; source .env; set +a
npm run dev

Wallet creation fails

Ensure WALLET_KEY_ENCRYPTION_SECRET is set in .env:

echo "WALLET_KEY_ENCRYPTION_SECRET=$(openssl rand -base64 32)" >> .env

Learn More

Architecture Overview - Understand the system design
Security Model - Learn about trust boundaries
API Reference - Explore the REST API
CLI Integration - Command-line interface guide

Getting Started

Architecture

Core Concepts

Operations

Security

Integration

Prerequisites

Quick Setup

What’s Next?

Installation Guide

Configuration

Create Wallets

Execute Transactions

Common Next Steps

Fund a Wallet (Devnet)

Query Wallet Balance

Deploy Escrow Program

Run Smoke Tests

Troubleshooting

Learn More

​Prerequisites

​Quick Setup

​What’s Next?

Installation Guide

Configuration

Create Wallets

Execute Transactions

​Common Next Steps

​Fund a Wallet (Devnet)

​Query Wallet Balance

​Deploy Escrow Program

​Run Smoke Tests

​Troubleshooting

​Learn More

Prerequisites

Quick Setup

What’s Next?

Common Next Steps

Fund a Wallet (Devnet)

Query Wallet Balance

Deploy Escrow Program

Run Smoke Tests

Troubleshooting

Learn More