Developer Portal

Internal documentation for posit. development team

Confidential: This documentation is for internal use only. Do not share externally.
Build Status: Phase 5 complete. Parser accuracy: 96.3% | 28 tests passing | Multi-chain ready

Quick Links

Local Setup

Get your dev environment running

Architecture

System design and data flow

API Reference

v1 Public API + Internal endpoints

DEX Parsers

Transaction normalizers (96.3% accuracy)

System Status

Solana Parser
Base Parser
Hyperliquid Parser
Cost Basis Engine
Intelligence Layer
Public API (v1)

Repository Structure

positlabs/
├── apps/
│   ├── api/              # Hono API + Graphile Worker
│   ├── web/              # Next.js 16 frontend
│   └── cli/              # Development CLI tools
├── packages/
│   ├── auth/             # Authentication (Privy, JWT, encryption)
│   ├── config/           # Shared configuration (zod)
│   ├── db/               # Drizzle ORM + migrations
│   ├── parser/           # Transaction parsing engine (THE MOAT)
│   │   └── src/chains/   # Multi-chain parsers
│   │       ├── solana/   # Helius + DEX normalizers
│   │       ├── base/     # EVM parser
│   │       └── hyperliquid/ # Perpetuals parser
│   ├── storage/          # S3/MinIO abstraction
│   └── types/            # Shared TypeScript types
├── docs/                 # Documentation
└── docker-compose.yml

Tech Stack

Layer Technology Version
Frontend Next.js + React 16.x / 19.x
API Hono 4.x
Database PostgreSQL + Drizzle ORM 16.x
Job Queue Graphile Worker 0.16.x
Auth Privy (Sign-in-with-Solana) -
Payments Lemon Squeezy -
Blockchain Helius (Solana), Alchemy (Base) -
Pricing Jupiter + Birdeye -
Language TypeScript (strict) 5.x

Key Features

Feature Status Phase
Parser (6 DEX normalizers) ✅ Complete Phase 0
Cost Basis (FIFO/HIFO) ✅ Complete Phase 0
Books MVP (Dashboard, Tax) ✅ Complete Phase 1
Wallet Intelligence Layer ✅ Complete Phase 2
Copy Detection ✅ Complete Phase 3
Scorecard (Ratings, Cohorts) ✅ Complete Phase 4
Public API v1 ✅ Complete Phase 4
Multi-Chain (Base, Hyperliquid) ✅ Complete Phase 4
API Key Management ✅ Complete Phase 5
Webhooks + Signatures ✅ Complete Phase 5
MEV/Slippage Detection ✅ Complete Phase 4
AWS Deployment 🔄 Pending Phase 5

Environment Variables

All env vars are loaded from the root .env file. See Environments for full list.
Variable Description Required
DATABASE_URL PostgreSQL connection string Yes
HELIUS_API_KEY Solana RPC + Enhanced Transactions Yes
PRIVY_APP_ID Privy authentication Yes
PRIVY_APP_SECRET Privy server secret Yes
BASE_RPC_URL Base chain RPC (optional) No
ALCHEMY_API_KEY Multi-chain RPC provider No

Getting Started

  1. Clone the repository: git clone git@github.com:positlabs/positlabs.git
  2. Install dependencies: pnpm install
  3. Start Docker services: docker-compose up -d
  4. Run migrations: pnpm --filter @posit/db db:migrate
  5. Copy env file: cp .env.example .env
  6. Start development: pnpm dev

For detailed setup instructions, see Local Setup.

Useful Commands

# Type check all packages
pnpm typecheck

# Run ESLint
cd apps/web && npx eslint . --ext .ts,.tsx

# Test parser against a wallet
HELIUS_API_KEY="xxx" pnpm --filter cli test-wallet <wallet-address>

# Open database browser
pnpm --filter @posit/db db:studio