diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000000000000000000000000000000000000..8d6f8da9ed46620c859ffa06a52889c5890af09b
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,150 @@
+# CLAUDE.md - HafSQL API
+
+## Project Overview
+
+HafSQL API is a JSON-RPC 2.0 API providing programmatic access to blockchain data stored in the HAF (Hive Application Framework) PostgreSQL database. It exposes HafSQL-prepared tables and other HAF database tables through a standardized JSON-RPC 2.0 interface.
+
+**Primary use cases:** dApps, blockchain explorers, analytics tools accessing Hive blockchain data.
+
+## Tech Stack
+
+- **Runtime:** Node.js 18
+- **Framework:** Express.js 4.18
+- **Module System:** ES6 modules
+- **Database:** PostgreSQL via `pg` driver with connection pooling
+- **Process Manager:** PM2 (clustering, 4 instances default)
+- **Linter:** Standard (ESLint-based, no semicolons)
+- **Security:** Helmet.js, HPP (HTTP Parameter Pollution protection)
+
+## Directory Structure
+
+```
+src/
+├── main.js                 # Express app entry point
+├── rpcHandler.js           # JSON-RPC 2.0 POST handler
+├── getHandler.js           # GET /info endpoint
+├── extraHandler.js         # Extra data query routing
+├── customQueryHandler.js   # Custom query routing
+├── methods/
+│   ├── rpcMethods.js       # Operation methods (op_*, vo_*)
+│   ├── extraMethods.js     # Extra methods (accounts, blocks, etc.)
+│   └── customMethods.js    # Custom methods (c_* prefix)
+├── helpers/
+│   ├── database.js         # PostgreSQL pool config
+│   ├── errorObject.js      # JSON-RPC 2.0 error formatter
+│   ├── getUserId.js        # User ID lookup helper
+│   ├── validators/         # Parameter validators (20+ files)
+│   ├── extra/              # Extra data handlers (14 files)
+│   └── custom_queries/     # Custom query handlers
+└── docs/                   # API documentation (Operations.md, Extra.md, Custom.md)
+```
+
+## Development Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Start API (PM2 cluster, 4 instances)
+npm run start
+
+# Restart/Stop
+npm run restart
+npm run stop
+
+# View logs
+npm run logs
+
+# List running instances
+npm run list
+```
+
+### Docker
+
+```bash
+# Build
+docker build -t hafsql-api-v1.0.0 .
+
+# Run
+docker run --rm -it -p 9090:9090 --name hafsql-api hafsql-api-v1.0.0
+```
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `ecosystem.config.cjs` | PM2 cluster configuration |
+| `example.env` | Environment variables template |
+| `src/main.js` | Express app initialization |
+| `src/rpcHandler.js` | Main JSON-RPC 2.0 request handler |
+| `src/helpers/database.js` | PostgreSQL pool setup |
+
+## Environment Variables
+
+```bash
+PORT=9090
+HOST=127.0.0.1
+PGDATABASE=haf_block_log
+PGUSER=haf_app_admin
+PGHOST=172.17.0.2
+PGPORT=5432
+PGPOOLSIZE=2  # Connections per instance (4 instances = 8 total)
+```
+
+## Coding Conventions
+
+- **ES6 modules** - Use `import`/`export` syntax
+- **No semicolons** - Standard linter enforces this
+- **2-space indentation**
+- **Single quotes** for strings
+- **Arrow functions** preferred
+- **Parameterized SQL** - Always use `$1, $2` placeholders, never string concatenation
+- **Async/await** for database operations
+
+### Code Patterns
+
+**Validators:** Pure functions returning boolean
+```javascript
+export const validateLimit = (limit) => {
+  return Number.isInteger(limit) && limit >= 1 && limit <= 100
+}
+```
+
+**Database queries:** Parameterized statements
+```javascript
+const result = await pool.query(
+  'SELECT * FROM table WHERE id = $1 LIMIT $2',
+  [id, limit]
+)
+```
+
+**JSON-RPC 2.0 errors:** Use error codes -32600, -32602, -32700
+
+## API Method Types
+
+1. **Operation methods** (`op_*`, `vo_*`) - ~49 blockchain operation types
+2. **Extra methods** (no prefix) - accounts, blocks, comments, delegations, etc.
+3. **Custom methods** (`c_*`) - Advanced queries like `c_comments_by_payout`
+
+### Request Format
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "hafsql.<method_name>",
+  "params": { "limit": 10 },
+  "id": 1
+}
+```
+
+## CI/CD Notes
+
+- **No CI pipeline configured** - Repository hosted on GitLab but no `.gitlab-ci.yml`
+- **No test framework** - Tests not currently implemented
+- **Linting:** Can run `npx standard` to check code style
+
+## Production Notes
+
+- PM2 runs 4 clustered instances by default
+- Each instance maintains 2 PostgreSQL connections (configurable via PGPOOLSIZE)
+- Docker container uses `pm2-runtime` for proper signal handling
+- CORS enabled for all origins