Development Quick Start

Use this page to run the local backend API, the rewritten frontend, optional workers, and the VitePress docs.

Run The App

Use two terminals from the repo root. Plain local development does not require an env file.

Terminal 1: backend API

cd backend
npm install
npm run db:migrate
npm run api

Terminal 2: frontend

cd frontend
pnpm install
pnpm run dev

Open http://localhost:3000.

Prerequisites

Tool	Used by
Node.js 20 or 22	Backend, frontend, docs
npm	Backend package install and backend commands
pnpm	Frontend package install, root OpenAPI scripts, and VitePress docs
Local env files	Optional frontend proxy override and optional backend secrets

Local Stack

Process	Default	Required
Backend API	http://127.0.0.1:8787	Yes
Frontend	http://localhost:3000	Yes
Market ingestion	Writes local market memory	Optional
Worker group	Runs background queues	Optional
VitePress docs	http://127.0.0.1:5174	Optional

Environment Variables

For plain local development, no env file is required. The backend and frontend have defaults that let a new checkout run the API, database migrations, frontend proxy, no-op decision engine, and in-memory decision artifacts.

Use backend/.env.example as a reference when enabling optional integrations, not as a required local checklist.

Context	Minimal variables	Notes
Local backend API	None	Defaults to 127.0.0.1:8787, backend/data/db.sqlite, local auth settings, MegaETH 4326,6343, DECISION_MODEL_PROVIDER=noop, and in-memory artifact storage.
Local frontend	None	Defaults backend proxy calls to http://127.0.0.1:8787. Set PUMP_PARTY_BACKEND_API_URL only when pointing at a different backend.
Production/staging backend	AUTH_JWT_SECRET, AUTH_ALLOWED_DOMAINS, MEGAETH_VAULT_ADDRESS, MEGAETH_PUMP_PARTY_VAULT_RESOLVER_ADDRESS	AUTH_JWT_SECRET must be at least 32 characters. AUTH_ALLOWED_DOMAINS is the wallet-facing host, such as app.example.com. SignedVault address settings are required in production startup.
Production/staging frontend	PUMP_PARTY_BACKEND_API_URL	Use the deployed backend origin. Browser code still calls the frontend BFF routes.

Common optional variables:

Need	Variables
Persistent SQLite path	PUMP_PARTY_DB_PATH
Service-to-service routes in production	PUMP_PARTY_BACKEND_SERVICE_TOKEN
Testnet versus mainnet vault	MEGAETH_VAULT_CHAIN_ID=6343 for testnet, 4326 for mainnet
Custom MegaETH RPC	MEGAETH_RPC_URL
Backend-signed refund authorizations	MEGAETH_PUMP_PARTY_VAULT_RESOLVER_PRIVATE_KEY
Real model calls	DECISION_MODEL_PROVIDER=auto or a pinned provider, plus the matching API key such as OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY, XAI_API_KEY, or GOOGLE_AI_API_KEY
Persistent artifact storage	ARTIFACT_STORAGE_PROVIDER plus provider-specific settings such as ARTIFACT_STORAGE_ROOT_DIR, ARTIFACT_STORAGE_BUCKET, and ARTIFACT_STORAGE_ENDPOINT

Backend Notes

The default SQLite database is backend/data/db.sqlite. Override the API host or port with PUMP_PARTY_BACKEND_API_HOST and PUMP_PARTY_BACKEND_API_PORT.

Frontend Notes

The frontend defaults to http://127.0.0.1:8787 for backend proxy calls. Create frontend/.env.local only if you want to make that default explicit or point at another backend:

PUMP_PARTY_BACKEND_API_URL=http://127.0.0.1:8787

The frontend authenticates product API calls with the Pump Party access JWT returned by POST /api/v1/auth/siwe/verify.

Wallet login must sign on MegaETH mainnet (4326) or MegaETH testnet (6343). Local development should normally use testnet. If the wallet is on another chain, the frontend requests a switch to MegaETH testnet and adds the network if the wallet does not know it yet. The backend allowlist is controlled by AUTH_ALLOWED_CHAIN_IDS and defaults to 4326,6343.

The frontend imports client HTTP types through the @pump-party/client-api TypeScript alias, backed by ../shared/src/generated/client-api.d.ts. If you change the OpenAPI spec, regenerate those types from the repo root:

pnpm run openapi:generate

Before review or CI, validate the spec and verify the generated file is current:

pnpm run openapi:verify

The docs dev/build commands generate the static API reference automatically. To refresh it manually:

pnpm run openapi:docs

Auth Flow

The local frontend follows the User/Auth module contract:

Step	Frontend route	Backend route
Issue SIWE challenge	POST /api/auth/siwe/challenge	POST /api/v1/auth/siwe/challenge
Verify signature	POST /api/auth/siwe/verify	POST /api/v1/auth/siwe/verify
Refresh session	POST /api/auth/session/refresh	POST /api/v1/auth/session/refresh
Logout	DELETE /api/auth/session	DELETE /api/v1/auth/session
Product API proxy	/api/backend/*	/api/v1/*

The frontend stores backend-issued access and refresh tokens in HttpOnly cookies. Product API calls proxy to the backend with Authorization: Bearer <accessToken>. If the access token is missing or expired and the refresh cookie is still valid, the proxy rotates the refresh token and retries the product API call once.

Optional Workers

Run each process in its own terminal:

cd backend
npm run ingest:local

cd backend
npm run workers:all

ingest:local starts capped local market ingestion. workers:all starts prop decisions, mark-to-market, backtests, audition evaluation, and Arena Entry sync. Run ingestion separately because it is not included in workers:all.

VitePress Docs

npm install
npm run docs:dev

Open http://127.0.0.1:5174.

Build and preview the docs:

npm run docs:build
npm run docs:preview

Verification

Frontend checks:

cd frontend
pnpm exec tsc --noEmit
pnpm run lint
pnpm run build

Backend checks:

cd backend
npm run typecheck
npm test

Smoke checks:

curl -I http://localhost:3000
curl -H "Authorization: Bearer $PUMP_PARTY_ACCESS_TOKEN" http://127.0.0.1:8787/api/v1/assets

Set PUMP_PARTY_ACCESS_TOKEN to the accessToken returned by backend SIWE verification.

Common Issues

Symptom	Check
Frontend cannot load clones/assets	Backend API is not running, PUMP_PARTY_BACKEND_API_URL is wrong, or the Pump Party access token is missing/expired.
Authenticated backend curl returns 401	Refresh the Pump Party session with POST /api/v1/auth/session/refresh or run the SIWE login flow again.
Generated client API types are stale	Run pnpm run openapi:generate from the repo root, then pnpm run openapi:verify.
Next.js warns about multiple lockfiles	Expected while the repo has root and frontend lockfiles.