Merlin Developer Documentation

Developer documentation for the Merlin platform. These docs cover architecture, implementation details, and how to extend the system.

Merlin is a privacy-preserving non-custodial wallet for Ethereum. Users trade tokenized stocks (xStocks) and crypto through conversational AI agents. Every transaction can be public, shielded (Railgun), or compliant (Privacy Pools).

Table of Contents

System Design

• Architecture Overview — Module map, data flow diagrams, key design decisions

Frontend

• Frontend Guide — Pages, components, state management, auth flow, design system

Backend

• Backend Guide — Project structure, routers, services, Firestore schema, patterns

Feature Pipelines

• Auth Flow — Passkey registration, WebAuthn ceremonies, seed encryption, session management
• Chat Pipeline — SSE streaming, OpenAI function calling, intent parsing, confirmation loop
• Trading Pipeline — Quote → simulate → policy → execute → confirm → persist
• Privacy System — Railgun shielding, private swaps, Privacy Pools compliance mode

Reference

• API Reference — All HTTP endpoints, request/response shapes
• Deployment Guide — GCP Cloud Run (backend) + Firebase Hosting (frontend)

Quick Start

# Frontend
cd frontend
pnpm install
pnpm dev          # Turbopack dev server on :3000

# Backend
cd backend
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

# SDK
pnpm install
pnpm dev          # tsup watch mode

Environment Variables

Copy .env.example to .env and fill in real values. Never commit .env.

Key variables:

Repository Layout

merlin/
  frontend/       Next.js 15 PWA
  backend/        FastAPI Python API
  src/            TypeScript SDK (wallet, provider, privacy, transaction)
  agents/         Agent definition files
  specs/          Project specification
  sources/        Upstream reference codebases
  dev/            This documentation
  infra/          Terraform IaC