🧠 OnchainMind × AGL

A production-grade Web3 AI SaaS platform for deploying AI-powered NPCs with persistent memory and tokenized compute — powered by the AGL token on Base.

Live Demo · API Docs · Quick Start · Report Bug

---

📖 Table of Contents

• Overview
• Features
• Architecture
• Tech Stack
• Monorepo Structure
• Quick Start
• Environment Variables
• API Reference
• Database Schema
• AGL Token Billing
• Deployment
• Roadmap
• Contributing
• License

---

Overview

OnchainMind × AGL is a developer platform that lets you spin up AI-powered Non-Player Characters (NPCs) with persistent cross-session memory, all billed in the AGL token on Base mainnet. Think of it as OpenAI meets Unity meets Web3 — a fully observable, auditable AI runtime where every inference is an on-chain transaction.

Developers interact via a clean dashboard or directly through the REST API to:

• Create projects and manage multiple NPC agents
• Configure NPC personalities and system prompts
• Chat with NPCs that recall past conversations
• Monitor usage, spending, and analytics in real time
• Generate scoped API keys for programmatic access

---

Features

🤖 AI NPC Engine

• Create NPCs with custom personalities and system prompts
• Real AI responses via OpenAI GPT models
• NPCs naturally reference past memories mid-conversation ("I remember you asked about...")
• Per-NPC chat history with full message log

🧩 Persistent Memory System

• Every meaningful conversation is stored as a memory entry
• NPC memories are scoped per-project for multi-tenant isolation
• Memory entries include category, importance score, and optional wallet attribution
• Designed for future upgrade to vector/semantic search (pgvector-ready schema)

💰 AGL Token Billing Engine

• Pay-per-use pricing denominated in AGL tokens
  • 2 AGL per NPC chat
  • 1 AGL per memory write
  • 1 AGL per memory search
• Real-time balance tracking with transaction history
• Deposit and balance management endpoints

🔑 API Key Authentication

• Generate and revoke scoped API keys per project
• Multi-tenant isolation — each project’s data is fully separated
• Zod-validated inputs on every endpoint

📊 Analytics & Dashboard

• 7-day API usage timeline (area chart)
• Real-time activity feed with AGL cost per action
• Dashboard summary: projects, active NPCs, total API calls, memories stored, AGL spent

⛓️ Blockchain Indexer (Simulated)

• Simulates on-chain events: Transfer, Mint, Stake, GovernanceVote
• Indexes events to NPC memory for context-aware agent behavior
• Extensible to real RPC event polling

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     OnchainMind × AGL                       │
│                                                             │
│  ┌──────────────────┐        ┌──────────────────────────┐  │
│  │  React Frontend  │◄──────►│    Express 5 API Server  │  │
│  │  (Vite + shadcn) │        │    (Node.js 24 / ESM)    │  │
│  └──────────────────┘        └──────────┬───────────────┘  │
│                                         │                   │
│                              ┌──────────▼───────────────┐  │
│                              │   PostgreSQL 16 Database  │  │
│                              │   (Drizzle ORM + Zod)     │  │
│                              └──────────┬───────────────┘  │
│                                         │                   │
│                    ┌────────────────────┼──────────────┐   │
│                    │                    │              │   │
│             ┌──────▼──────┐  ┌──────────▼───┐  ┌──────▼──┐│
│             │  OpenAI API │  │  AGL Token   │  │ Indexer ││
│             │  (GPT-4o)   │  │  (Base L2)   │  │ Engine  ││
│             └─────────────┘  └──────────────┘  └─────────┘│
└─────────────────────────────────────────────────────────────┘

Request flow for NPC chat:

1. Client sends POST /api/v1/npc/chat with { npcId, message, wallet }
2. API server loads NPC config + top-5 recent memories
3. OpenAI completion runs with memory context injected into system prompt
4. Response + new memory entry written to PostgreSQL
5. 3 AGL deducted from balance; activity + transaction rows created
6. Response returned with memoryRecalled[] and aglCharged

---

Tech Stack

Layer	Technology
Runtime	Node.js 24 (ESM)
Language	TypeScript 5.9
Package Manager	pnpm workspaces
API Framework	Express 5
Database	PostgreSQL 16
ORM	Drizzle ORM + drizzle-zod
Validation	Zod v4
API Spec	OpenAPI 3.1 → Orval codegen
AI Provider	OpenAI (GPT-4o)
Frontend Framework	React 19 + Vite 6
UI Components	shadcn/ui + Radix UI
Styling	Tailwind CSS v4
Data Fetching	TanStack Query v5
Charts	Recharts
Router	Wouter
Build Tool	esbuild (CJS bundle)
Logger	Pino + pino-http
Blockchain	Base Mainnet (Chain ID: 8453)
Hosting	Replit Autoscale

---

Monorepo Structure

onchain-mind/
├── artifacts/
│   ├── api-server/                 # Express 5 backend
│   │   └── src/
│   │       ├── app.ts              # Express app setup
│   │       ├── index.ts            # Server entrypoint
│   │       └── routes/
│   │           ├── analytics.ts    # Usage + dashboard routes
│   │           ├── api-keys.ts     # API key CRUD
│   │           ├── billing.ts      # AGL balance + transactions
│   │           ├── indexer.ts      # Blockchain event simulation
│   │           ├── memory.ts       # NPC memory CRUD + search
│   │           ├── npc-chat.ts     # POST /v1/npc/chat
│   │           ├── npcs.ts         # NPC CRUD
│   │           └── projects.ts     # Project CRUD
│   └── onchainmind/                # React frontend (Vite)
│       └── src/
│           ├── pages/
│           │   ├── landing.tsx
│           │   ├── dashboard.tsx
│           │   ├── projects.tsx
│           │   ├── project-detail.tsx
│           │   ├── npcs.tsx
│           │   ├── npc-detail.tsx  # NPC chat UI + memory log
│           │   ├── api-keys.tsx
│           │   ├── billing.tsx
│           │   └── analytics.tsx
│           └── components/
│               └── layout/
│                   └── sidebar-layout.tsx
├── lib/
│   ├── api-spec/                   # OpenAPI 3.1 spec (source of truth)
│   │   └── openapi.yaml
│   ├── api-client-react/           # Orval-generated typed React hooks
│   │   └── src/generated/api.ts
│   ├── api-zod/                    # Orval-generated Zod schemas
│   │   └── src/generated/
│   ├── db/                         # Drizzle schema + client
│   │   └── src/schema/
│   │       ├── npcs.ts
│   │       ├── memories.ts
│   │       ├── billing.ts
│   │       ├── chat-messages.ts
│   │       ├── activity.ts
│   │       ├── api-keys.ts
│   │       └── projects.ts
│   └── integrations-openai-ai-server/  # OpenAI client wrapper
├── scripts/                        # Workspace utility scripts
├── package.json                    # Workspace root
├── pnpm-workspace.yaml
└── tsconfig.base.json

---

Quick Start

Prerequisites

• Node.js >= 24
• pnpm >= 9
• PostgreSQL 16 instance
• OpenAI API key

1. Clone & Install

git clone https://github.com/Agunnaya-Labs/onchain-mind.git
cd onchain-mind
pnpm install

2. Configure Environment

cp .env.example .env
# Fill in DATABASE_URL, OPENAI_API_KEY, PORT, BASE_PATH

3. Push Database Schema

pnpm --filter @workspace/db run push

4. Run the API Server

pnpm --filter @workspace/api-server run dev

5. Run the Frontend

pnpm --filter @workspace/onchainmind run dev

The dashboard will be available at http://localhost:8080.

---

Environment Variables

Variable	Required	Description
DATABASE_URL	✅	PostgreSQL connection string
OPENAI_API_KEY	✅	OpenAI API key for NPC completions
PORT	✅	Port for the API server (e.g. 8080)
BASE_PATH	✅	Vite base path (e.g. /)
NODE_ENV	✅	development or production

---

API Reference

Base path: /api

Health

Method	Endpoint	Description
GET	/healthz	Server health check

Projects

Method	Endpoint	Description
GET	/projects	List all projects
POST	/projects	Create a project
GET	/projects/:id	Get project by ID
PATCH	/projects/:id	Update project
DELETE	/projects/:id	Delete project

NPCs

Method	Endpoint	Description
GET	/projects/:projectId/npcs	List NPCs in a project
POST	/projects/:projectId/npcs	Create an NPC
GET	/npcs/:id	Get NPC by ID
PATCH	/npcs/:id	Update NPC
DELETE	/npcs/:id	Delete NPC

NPC Chat ⭐

Method	Endpoint	Description
POST	/v1/npc/chat	Chat with an NPC
GET	/npcs/:npcId/chat-history	Get NPC message history

Request body for /v1/npc/chat:

{
  "npcId": 1,
  "message": "Hello, who are you?",
  "wallet": "0x742d35Cc6634C0532925a3b8D4C9bD73"
}

Response:

{
  "response": "I'm Arena Guide! I remember you asked about game mechanics last time...",
  "npcId": 1,
  "memoryRecalled": ["User asked about game mechanics"],
  "aglCharged": 3,
  "timestamp": "2026-04-15T00:00:00.000Z"
}

Memory

Method	Endpoint	Description
GET	/npcs/:npcId/memory	Get NPC memories
POST	/npcs/:npcId/memory/search	Semantic memory search

API Keys

Method	Endpoint	Description
GET	/api-keys	List API keys
POST	/api-keys	Generate new API key
DELETE	/api-keys/:id	Revoke API key

Billing

Method	Endpoint	Description
GET	/billing/balance	Get AGL balance
GET	/billing/transactions	Transaction history
POST	/billing/deposit	Deposit AGL

Analytics

Method	Endpoint	Description
GET	/v1/usage	Usage statistics
GET	/analytics/timeline	Daily usage timeline (7d default)
GET	/dashboard/summary	Dashboard KPI summary
GET	/dashboard/recent-activity	Recent activity feed

Indexer

Method	Endpoint	Description
GET	/indexer/events	List indexed blockchain events
POST	/indexer/simulate	Simulate a blockchain event

---

Database Schema

projects ──┬── npcs ──┬── chat_messages
           │          └── memories
           ├── api_keys
           └── activity

balances
transactions

Key tables:

• npcs — NPC config: name, personality, system_prompt, model, status
• memories — Per-NPC memory entries with importance scoring and wallet attribution
• chat_messages — Full conversation history with role (user / assistant)
• balances — AGL token balance (wallet-scoped)
• transactions — Immutable ledger of all AGL charges and deposits
• activity — Human-readable activity log for the dashboard feed
• api_keys — Hashed API keys with project scope

Codegen

API types are generated from the OpenAPI spec. After modifying lib/api-spec/openapi.yaml, regenerate hooks and Zod schemas:

pnpm --filter @workspace/api-spec run codegen

---

AGL Token Billing

Action	AGL Cost
NPC Chat	2 AGL
Memory Write	1 AGL
Memory Search	1 AGL
Deposit	—

AGL Token Contract (Base Mainnet):

0xea1221b4d80a89bd8c75248fae7c176bd1854698

Chain ID: 8453 · Network: Base Mainnet · Standard: ERC-20

---

Deployment

Replit (Current)

This project is configured for Replit Autoscale deployment via .replit:

[deployment]
router = "application"
deploymentTarget = "autoscale"

Ports: 8080 (API + Frontend), 8081 (dev)

Manual / VPS

# Build all packages
pnpm run build

# Start API server
pnpm --filter @workspace/api-server run start

Docker (Coming Soon)

Docker configuration is planned. The monorepo structure is Docker-ready — each artifact can be independently containerized.

---

Roadmap

• NPC AI engine with OpenAI integration
• Persistent memory system (recency-based)
• AGL token billing engine
• API key management
• Blockchain event indexer (simulated)
• React dashboard with analytics
• OpenAPI spec + Orval codegen pipeline
• API key authentication middleware
• Per-wallet balance isolation
• pgvector semantic memory search
• SIWE (Sign-In with Ethereum) wallet auth
• Real AGL token balance reads via Base RPC
• WebSocket streaming for NPC chat
• Docker + Kubernetes configs
• Redis queue for indexer events
• Rate limiting + Helmet.js hardening

---

Contributing

Contributions are welcome! Please open an issue first to discuss what you’d like to change.

# Fork → clone → branch
git checkout -b feature/your-feature

# Make changes, then
pnpm run typecheck
pnpm run build

# Submit a PR

---

License

MIT © Agunnaya Labs

---

Built with 🧠 by Agunnaya Labs · @Agunnaya001 on X

AGL Token · Base Mainnet · 0xea1221b4d80a89bd8c75248fae7c176bd1854698