F FORGE
FORGE AGENT

Start

FORGE — AI Agent Launchpad MVP Build Pack

Version: 0.1 MVP build specification Target deployment: single fresh DigitalOcean Ubuntu server, GitHub monorepo, PM2-managed services Primary launch rail: PONS on Robinhood Chain Later adapters: Pump.fun (Solana), flap.sh (BSC)

This pack is intended to be handed directly to Cursor/Grok/a development team. It contains the product specification, UX reference brief, system architecture, smart-contract design, indexing plan, AI-agent harness, database schema, API/WebSocket contracts, PM2/Nginx production setup, deployment runbook, security checklist and test/acceptance criteria.

MVP in one sentence

A creator chooses an agent template, configures an isolated Grok-powered agent, launches a token through PONS with the creator-fee recipient routed to an agent-specific FORGE fee vault, and gets a live token/agent page with on-chain trading data, real-time WebSocket updates and a safe chat interface.

Critical integration note

PONS v2 should be treated as an external protocol dependency, not copied or reimplemented. FORGE indexes PONS factory/curve events directly and calls the factory/router from user wallets or CLI. At integration time, re-read live PONS deployment addresses/configuration from official docs and validate canLaunch(address) before exposing launch actions.

Current docs reviewed for this pack (2026-10-08):

  • https://docs.ponsfamily.com/v2
  • https://docs.x.ai/developers/rest-api-reference/inference
  • https://docs.x.ai/developers/grok-4-7

Package map

  • Product — complete product requirements and UX
  • Architecture — service topology and data flows
  • PONS — launch, fee routing and indexer details
  • Runtime — Grok wrapper, isolation, tools and safety harness
  • Identity generation — Generate-with-Grok full identity + type-matched profile image
  • Fee keeper — fee-vault claim keeper (1% tip, gas+profit gate)
  • Market data — Mobula Enterprise TradingView charts + swap buy/sell routing
  • Smart contracts — contract requirements and threat model
  • contracts/AgentFeeVault.sol — MVP fee-split vault reference implementation
  • contracts/AgentFeeVaultFactory.sol — deterministic agent vault factory + predictVault ECA
  • contracts/ForgeLaunchRouter.sol — atomic vault create + PONS launch (one user tx)
  • API — REST and WebSocket contracts
  • Database — PostgreSQL schema
  • Deployment — clean Ubuntu/DigitalOcean setup and full production runbook
  • ops/ecosystem.config.cjs — PM2 service layout
  • ops/nginx-forge.conf — Nginx reverse proxy example
  • ops/logrotate-forge — log rotation
  • ops/healthcheck.sh — process/API health checker
  • CLI — agent + operator CLI (simulate, launch-token, identity, import)
  • DOCS_SITE.md — in-app /docs IA from this markdown tree
  • agents/ — agent playbooks (launch, identity, safety)
  • Security — security controls and launch gates
  • Test plan — tests and release acceptance checklist
  • ENV.example — environment variable inventory
  • CURSOR_BUILD_PROMPT.md — implementation prompt for Cursor/Grok
  • UI_REFERENCES/ — screenshots supplied with the brief

Repo root (ship day one): AGENTS.md, .cursor/skills/forge-launch-token/, .cursor/skills/forge-build-mvp/

text
forge/
  AGENTS.md
  .cursor/skills/
    forge-launch-token/  # SKILL.md — agent can launch a token
    forge-build-mvp/
  apps/
    web/                 # Next.js UI (+ /docs from markdown)
    api/                 # Fastify REST API
    ws/                  # WebSocket gateway
    indexer/             # PONS event indexer / chain state
    worker/              # fee claim jobs, agent jobs, maintenance
  packages/
    db/                  # Drizzle schema + migrations
    chain/               # viem clients, ABIs, PONS adapter
    agents/              # templates + Grok wrapper + tool registry
    contracts/           # Solidity + deployment scripts
    shared/              # zod schemas/types/constants
    ui/                  # shared components
  launch/
    forge.json
    agents/              # per-agent launch configs
  scripts/
    launch-token.ts
    launch-forge.ts
    identity-generate.ts
    import-token.ts
    backfill-indexer.ts
    smoke-test.ts
  ops/
  docs/
    agents/

Non-negotiables

  1. The browser never receives xAI API keys, server signer keys, DB passwords or admin secrets.
  2. AI agents do not receive direct access to FORGE infrastructure credentials, arbitrary shell/network access, database credentials, or platform wallets.
  3. PONS state is derived from chain events/read calls; local DB is a query/cache layer, not the source of truth.
  4. Fee routing must be transparent. Default: 15% of gross to platform, then 1% of the beneficiary pool to the claim caller (tip never from platform), rest to beneficiary. Keeper only auto-claims when the tip covers gas + profit.
  5. Complex agent actions are executed by the agent's separately configured wallet/action contract. The FORGE platform does not silently trade or custody on behalf of the agent.
  6. The UI must recover cleanly from RPC/WebSocket disconnects and indexer restarts without duplicate state.
  7. Everything needed to restart after a server reboot must be managed through PM2 + startup persistence; Nginx and DB/Redis are system services.
  8. Full docs + Cursor launch skill ship from day one; an agent must be able to simulate and launch a token via forge-launch-token without reverse-engineering the repo.