If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/NoFxAiOS/nofx shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2w ago
• 11 active contributors
• Distributed ownership (top contributor 35% of recent commits)
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live NoFxAiOS/nofx repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/NoFxAiOS/nofx.

What it runs against: a local clone of NoFxAiOS/nofx — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in NoFxAiOS/nofx | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch dev exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 41 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of NoFxAiOS/nofx. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/NoFxAiOS/nofx.git
#   cd nofx
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of NoFxAiOS/nofx and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "NoFxAiOS/nofx(\\.git)?\\b" \\
  && ok "origin remote is NoFxAiOS/nofx" \\
  || miss "origin remote is not NoFxAiOS/nofx (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify dev >/dev/null 2>&1 \\
  && ok "default branch dev exists" \\
  || miss "default branch dev no longer exists"

# 4. Critical files exist
test -f "agent/agent.go" \\
  && ok "agent/agent.go" \\
  || miss "missing critical file: agent/agent.go"
test -f "agent/skill_registry.go" \\
  && ok "agent/skill_registry.go" \\
  || miss "missing critical file: agent/skill_registry.go"
test -f "api/agent_routes.go" \\
  && ok "api/agent_routes.go" \\
  || miss "missing critical file: api/agent_routes.go"
test -f "agent/skill_dag_runtime.go" \\
  && ok "agent/skill_dag_runtime.go" \\
  || miss "missing critical file: agent/skill_dag_runtime.go"
test -f "agent/memory.go" \\
  && ok "agent/memory.go" \\
  || miss "missing critical file: agent/memory.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 41 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~11d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/NoFxAiOS/nofx"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

NOFX is an open-source autonomous AI trading assistant built in Go (backend) and TypeScript/React (frontend) that removes manual model configuration and API key management by letting an AI agent independently perceive markets, select models, fetch data, and execute trades. It integrates x402 USDC micropayments so users fund a wallet instead of managing API keys across services. Go backend monorepo with agent orchestration in agent/ (brain.go, execution_state.go, history.go), TypeScript/React frontend under web/ (inferred from typical Node projects). Docker-first deployment (Dockerfile.railway, docker-compose checks in CI). Configuration via .env.example; encryption concerns documented separately (ENCRYPTION_README.md).

Crypto traders and developers who want hands-off AI-driven trading without juggling API keys, model selection, or data source integration. Also appeals to teams building on-chain payment infrastructure or experimenting with autonomous agents in financial markets.

Actively developed with multi-language README support (Chinese, Japanese, Korean, Russian, Ukrainian, Vietnamese) and established CI/CD pipelines (docker-build, pr-checks, coverage tracking). The project has published releases and a CODE_OF_CONDUCT, suggesting community maturity, but the recent focus on docs translation and PR template organization suggests it's still refining its developer experience rather than stabilizing a v1.0.

Trades real money via USDC wallets, making bugs high-impact; the monorepo spans 2.5MB of Go + 1.4MB of TypeScript with integration across multiple external services (x402, Claw402 AI Gateway), increasing surface area for failures. AGPL-3.0 licensing may restrict commercial use. The agent logic in agent/ (brain.go, execution_state.go) lacks visible test coverage in file list, and reliance on external AI gateway (Claw402) creates vendor lock-in risk.

Heavy investment in internationalization (6 language READMEs), GitHub Actions CI expansion (new pr-checks-comment.yml, pr-docker-compose-healthcheck.yml workflows), and PR template standardization (separate templates for backend/frontend/docs/general). The project is scaling developer onboarding and deployment reliability.

curl -fsSL https://raw.githubusercontent.com/NoFxAiOS/nofx/main/install.sh | bash
# Then open http://127.0.0.1:3000

Or clone and use Makefile (visible in top-level): git clone https://github.com/NoFxAiOS/nofx && cd nofx && make

Daily commands:

make  # See Makefile for dev targets
# Frontend:
cd web && npm install && npm start  # Typical React dev server on port 3000
# Backend:
go run ./agent  # Agent entry point

Dependencies: Go 1.21+, Node/npm for React 18+, Docker for containerized deployment.

• agent/agent.go — Core agent orchestration engine—entry point for all skill execution, memory management, and trading workflow coordination.
• agent/skill_registry.go — Central registry and factory for all trading skills (strategy, exchange, model management)—essential for understanding how capabilities are registered and dispatched.
• api/agent_routes.go — HTTP route definitions for agent control and configuration—how external clients interact with the trading AI system.
• agent/skill_dag_runtime.go — Executes skill DAGs (directed acyclic graphs) for complex multi-step trading workflows—handles dependency resolution and parallel execution.
• agent/memory.go — Persistent memory and state management for agent continuity—stores conversation history, trade outcomes, and learned preferences.
• agent/brain.go — LLM-driven decision-making and reasoning layer—bridges natural language understanding to skill execution and strategy selection.
• agent/skill_catalog.go — Metadata and capability descriptions for all available skills—used for LLM grounding and skill discovery.

Add a New Trading Skill

1. Define skill metadata in a new JSON file in agent/skills/ directory (e.g., agent/skills/my_skill_management.json) following the pattern of existing skill definitions. (agent/skills/strategy_management.json)
2. Create handler function in agent/skill_execution_handlers.go or agent/skill_management_handlers.go that implements the skill's logic. (agent/skill_execution_handlers.go)
3. Register skill in agent/skill_registry.go by adding it to the RegisterSkill() or similar initialization function. (agent/skill_registry.go)
4. Add routing rule in agent/skill_dispatcher.go to map user intents to your new skill. (agent/skill_dispatcher.go)
5. Test end-to-end by invoking via agent/brain.go's LLM routing or direct API call through api/agent_routes.go. (api/agent_routes.go)

Add a New REST API Endpoint

1. Create a new handler function in the appropriate file (e.g., api/handler_trader.go, api/handler_exchange.go, or create api/handler_new_feature.go). (api/handler_trader.go)
2. Register the route in api/agent_routes.go using standard Go HTTP routing patterns. (api/agent_routes.go)
3. Define request/response structures inline or in api/errors.go if adding new error types. (api/errors.go)
4. Call appropriate agent methods (e.g., from agent/agent.go) or skill dispatcher to execute business logic. (agent/agent.go)
5. Return JSON response using standard error handling from api/errors.go. (api/errors.go)

Extend Agent Memory or State Persistence

1. Add new fields to the memory struct in agent/memory.go for new state to persist. (agent/memory.go)
2. If state is user-configurable, add corresponding fields to agent/preferences.go. (agent/preferences.go)
3. Implement load/save methods in agent/memory.go to serialize/deserialize from persistent backend. (agent/memory.go)
4. Call memory update methods from relevant skill handlers in agent/skill_execution_handlers.go after state changes. (agent/skill_execution_handlers.go)

Add Multi-Step Workflow (Skill DAG)

1. Define workflow structure with skill dependencies in agent/skill_dag.go. (agent/skill_dag.go)
2. Implement workflow execution logic in agent/skill_dag_runtime.go, leveraging DAG topology for parallel execution. (agent/skill_dag_runtime.go)
3. Register workflow as a composite skill in agent/skill_registry.go. (agent/skill_registry.go)
4. Expose workflow trigger via agent/brain.go reasoning or direct API call in api/agent_routes.go. (api/agent_routes.go)

• Go — High-performance concurrent execution for multi-skill workflows, efficient memory usage for long-running agent, and easy deployment with single binary.
• LLM (Brain Module) — Natural language understanding of trading intent, dynamic skill selection without hard-coded rules, and adaptive strategy reasoning based on market context.
• Skill DAG Execution — Enables complex multi-step trading workflows with dependency resolution, parallelization of independent steps, and clear execution semantics.
• USDC Payment Model — On-chain microtransactions for per-API-call costs rather than subscription; aligns incentives with actual usage; enables pay-per-use without traditional API key management.
• Persistent Memory & History — Agent learns from past trades, avoids repeated mistakes, maintains user preferences across sessions, and provides audit trail for trading decisions.

• LLM-driven skill routing vs. hard-coded rules

  • Why: Provides flexibility and adaptability to novel trading scenarios without code changes.
  • Consequence: Increased latency for skill selection (LLM inference), potential for misclassification under adversarial input, and dependency on external LLM provider reliability.

• DAG-based workflow execution vs. linear sequential

  • Why: Parallelizes independent operations, reduces total execution time, and enables complex trading strategies.
  • Consequence: More complex error handling and state management; debugging multi-branch workflows is harder; requires careful cycle detection.

• undefined

  • Why: undefined
  • Consequence: undefined

USDC wallet requirement: .env.example likely requires valid USDC wallet address and private key for any real trading; test mode may need separate config. x402 gateway dependency: Claw402 AI Gateway is external; if it's down or rate-limits, the agent can't function. AGPL-3.0 licensing: Commercial deployments must open-source their modifications. Agent autonomy: The brain.go agent makes trading decisions without human approval—test in dry-run mode first. Docker Compose health checks: pr-docker-compose-healthcheck.yml implies multi-service setup; missing service startup order could cause silent failures.

• x402 USDC Micropayments — NOFX's core differentiator: replacing API keys with on-chain USDC payments; understanding the x402 standard is essential to modify payment flows or add new AI gateways
• Autonomous Agent Pattern (Agent Loop) — The brain.go perceive-decide-act loop runs without human intervention; understanding state machines and event-driven architecture is critical for modifying agent behavior
• State Machine (Execution State) — Trade execution transitions through states (pending → open → closed); execution_state.go manages this; essential for preventing race conditions and order corruption
• Model Selection / Routing — The agent must choose which AI model (via Claw402 gateway) to use per market; understanding cost-benefit tradeoffs and model capabilities is key to improving trading accuracy
• AGPL-3.0 Copyleft Licensing — Commercial modifications must be open-sourced; understanding license obligations is critical before deploying a modified version in production
• Docker Multi-Stage Builds & Health Checks — The repo uses Docker heavily (Dockerfile.railway, docker-compose health checks in CI); understanding container orchestration and startup dependencies prevents deployment failures
• GitHub Actions CI/CD Pipelines — 6 workflow files manage coverage, Docker builds, and PR checks; understanding how to extend CI/CD is essential for adding new deployment targets or validation steps

• yearn/yearn-security — Similar focus on wallet security and USDC integration in DeFi; shares encryption and private key management patterns
• getampt/ampt — Autonomous agent orchestration in trading; comparable decision-making architecture for market data selection
• peppersec/peppersec-contracts — USDC payment and micropayment infrastructure; complements x402 integration for on-chain settlement
• spiceai/spice — Alternative AI trading framework; direct competitor with different monetization (API keys vs. x402 USDC)
• x402-protocol/x402 — Core dependency; the USDC micropayment standard NOFX uses instead of traditional API keys

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for agent/skill_dispatcher.go and agent/skill_execution_handlers.go

The agent package contains critical trading logic for skill dispatching and execution handling, but only 3 test files exist (memory_test.go, preferences_test.go, onboard_test.go). The skill_dispatcher.go and skill_execution_handlers.go files lack corresponding _test.go files despite handling core workflow orchestration. This is high-risk code that needs test coverage to prevent trading failures.

• [ ] Create agent/skill_dispatcher_test.go with tests for skill routing, dependency resolution, and error handling
• [ ] Create agent/skill_execution_handlers_test.go with tests for execution state transitions and handler invocation
• [ ] Add integration tests for skill DAG runtime execution (agent/skill_dag_runtime_test.go exists but may need expansion)
• [ ] Ensure coverage aligns with .github/workflows/pr-go-test-coverage.yml requirements

Add GitHub Actions workflow for Python dependency scanning and security audits

The repo has Python dependencies (requests>=2.31.0) used in .github/workflows/scripts/ for PR commenting and coverage calculation, but no dedicated security/dependency scanning workflow exists (unlike the comprehensive Go/Docker workflows). With USDC payment handling and AI trading logic, supply chain security is critical.

• [ ] Create .github/workflows/python-security-audit.yml to run bandit and safety checks on .github/workflows/scripts/
• [ ] Add dependency pinning and lock file (requirements.lock) alongside requirements.txt
• [ ] Reference .github/workflows/pr-go-test-coverage.yml structure for consistency with existing CI patterns
• [ ] Integrate with existing labeler.yml to auto-tag security issues

Create ARCHITECTURE.md documenting agent skill DAG system and LLM routing logic

The agent package has sophisticated components (skill_dag.go, llm_skill_router.go, planner_runtime.go, skill_catalog.go) that form the core trading decision engine, but no architectural documentation exists beyond README.md. New contributors struggle to understand the execution flow, skill registration, and routing decisions. CONTRIBUTING.md exists but needs architectural context.

• [ ] Create ARCHITECTURE.md with diagrams of skill DAG execution flow (reference agent/skill_dag_runtime.go logic)
• [ ] Document LLM skill routing strategy from agent/llm_skill_router.go with examples
• [ ] Explain memory/history management (agent/memory.go, agent/history.go) and state transitions (agent/execution_state.go)
• [ ] Add section on extending with custom skills and registering with agent/skill_catalog.go
• [ ] Link from main README.md and CONTRIBUTING.md for discoverability

• Add unit tests to agent/execution_state.go for trade state transitions; currently only backend_logs_test.go and config_tools_test.go exist, leaving core state logic untested.
• Document the AI model selection algorithm in agent/brain.go with code comments and add an ADR (Architecture Decision Record) in a new docs/adr/ folder explaining why Claw402 was chosen over alternatives.
• Implement missing i18n strings in agent/i18n.go for error messages in the agent (e.g., 'insufficient balance', 'market closed'); currently only 6 language READMEs exist but agent error messages may not be localized.

• Critical · Incomplete Encryption Key Configuration in .env.example — .env.example. The DATA_ENCRYPTION_KEY in .env.example is truncated and incomplete. The comment indicates it should be a Base64-encoded 32-byte key, but the actual key value is missing. This suggests incomplete security documentation and potential misconfigurations in production deployments. Fix: Complete the .env.example file with proper documentation showing a full example of the DATA_ENCRYPTION_KEY format. Ensure deployment guides emphasize the critical importance of generating strong, unique encryption keys for production.
• Critical · Exposed pprof Profiling Endpoint — docker-compose.yml (ports section). The docker-compose.yml file exposes port 6060 for pprof profiling (Go's built-in profiler). This endpoint provides detailed runtime information about the application including memory allocations, goroutines, and execution profiles. In production, this can leak sensitive information about the application's internal structure and be used for reconnaissance. Fix: Remove the pprof port exposure in production configurations. If profiling is needed, use network policies to restrict access to authorized networks only. Consider using separate docker-compose files for development and production environments.
• High · Missing Security Headers Configuration — Frontend service configuration / Backend API handlers. No visible security header configuration (e.g., Content-Security-Policy, X-Frame-Options, X-Content-Type-Options) in the provided frontend or backend configuration snippets. Given this is a trading application handling real funds, missing security headers could expose users to XSS, clickjacking, and other web-based attacks. Fix: Implement comprehensive security headers in the API responses and frontend server configuration. Include: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Strict-Transport-Security, and X-XSS-Protection headers.
• High · Plaintext .env File Mounted in Docker — docker-compose.yml (volumes section). The docker-compose.yml mounts the .env file directly as a volume into the container. While .env files should contain secrets, this approach means secrets are readable from the container filesystem and potentially visible in container inspection commands. Fix: Use Docker secrets or environment variable injection instead of mounting .env files. For production, use dedicated secret management solutions (Vault, AWS Secrets Manager, etc.). Never commit .env files to version control.
• High · No HTTPS/TLS Configuration in Docker Compose — docker-compose.yml (ports and services configuration). The docker-compose.yml shows no TLS/HTTPS configuration for the frontend or backend services. For a trading application handling real funds and API credentials, traffic must be encrypted. This configuration appears suitable only for development. Fix: Implement TLS/HTTPS in production. Use reverse proxy (nginx/caddy) with proper SSL certificates. Enforce HTTPS redirect. Ensure all inter-service communication is encrypted.
• High · Incomplete Security Policy Documentation — SECURITY.md. The SECURITY.md file is truncated and doesn't include complete vulnerability reporting procedures, response timelines, or contact information for security researchers. The section '## 🔒 Reporting a Vuln' appears incomplete. Fix: Complete the security policy with: vulnerability reporting procedures, contact information (security@domain.com), expected response timelines, security issue disclosure policy, and bug bounty program details if applicable.
• Medium · Loose Dependency Version Pinning in GitHub Actions — .github/workflows/scripts/requirements.txt. The requirements.txt file specifies 'requests>=2.31.0' without upper bound pinning. While this ensures compatibility, it could introduce breaking changes or security issues from future major versions without explicit testing. Fix: Pin dependencies to specific versions or use lower bound with reasonable upper bound (e.g., 'requests>=2.31.0,<3.0'). Use tools like dependabot for automated security updates and vulnerability scanning.
• Medium · Database Security Not Explicitly Documented — docker-compose.yml (data volume), agent/ directory. The codebase uses SQLite (mentioned in SECURITY.md), but no information about database file permissions, encryption at rest, or backup security is visible. SQLite databases in /app/data could be accessible to any process with filesystem access. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.