StellarMind

Multi-agent AI marketplace on Stellar Testnet with x402-protected premium endpoints, budget guardrails, and on-chain payment verification.

Why This Repo Exists

StellarMind demonstrates a production-style pattern for agent commerce:

• agents can call each other through paid APIs
• payment is enforced by protocol (x402), not trust alone
• spending is controlled with explicit budget policies
• every paid step can be verified on-chain

Core Capabilities

• Orchestrator that decomposes tasks and routes work to specialized agents
• Premium agent endpoints protected by @x402/express
• Automatic payment handling via @x402/fetch and Stellar settlement
• Real-time event stream (SSE) in the web dashboard
• Demo automation pipeline for recording and narrated video export

Architecture (High-Level)

Client Task + Budget
        |
        v
Orchestrator (plan, select agents, enforce spend limits)
        |
        v
/api/premium/* endpoints (x402-protected)
        |
        v
402 challenge -> signed payment -> facilitator verification
        |
        v
Agent execution + streamed updates + tx proof links

For a deeper, standalone walkthrough — components plus the request, payment, and orchestration flows — see docs/architecture.md.

Quick Start

1) Clone and install

git clone https://github.com/Flamki/stellarmind.git
cd stellarmind
nvm install
nvm use
npm install

The project pins its contributor runtime in .nvmrc (20.19.0) so local development matches the Node version expected by the Stellar SDK, lint tooling, and CI.

Windows alternatives:

# nvm-windows
nvm install 20.19.0
nvm use 20.19.0

# Volta
volta install node@20.19.0

2) Configure environment

cp .env.example .env

Windows PowerShell:

Copy-Item .env.example .env

Then either:

• run npm run setup to generate testnet wallets automatically, or
• manually fill wallet fields in .env

Security note:

• npm run setup masks wallet secrets in terminal output by default.
• Use node src/setup-wallets.js --show-secrets only when you explicitly need full secret printing.

Add your Anthropic key:

| `ANTHROPIC_API_KEY` | `sk-ant-...` | Anthropic API key for Claude agents |
| `ADMIN_TOKEN` | (optional) | Token required for runtime config changes (e.g. `POST /api/config/apikey`) |
| `SERVER_STELLAR_ADDRESS` | `G...` | Public Key of the server wallet (receives payments) |

Optional for deployments:

# Defaults to http://localhost:3001 in local dev
INTERNAL_BASE_URL=http://server:3001

Structured logging mode:

LOG_FORMAT=json

Run history persistence (for orchestration/payment audit):

RUN_HISTORY_STORAGE=file
RUN_HISTORY_FILE=./data/run-history.json
RUN_HISTORY_MAX_RUNS=200

The run-history file uses schema versioning for safe migrations:

• Current format includes a version field (version 1)
• Legacy unversioned files are automatically migrated to version 1 on startup
• Missing files are treated as a first startup: a fresh empty store is created, nothing to preserve
• Malformed JSON or an invalid/incompatible schema value is preserved with a .corrupted.{timestamp} suffix before a fresh store is started, so the original is always available for manual repair
• Future (newer-than-supported) schema versions fail startup with a clear error without touching the file
• Permission and I/O errors reading the file (e.g. EACCES) fail startup with an actionable error and leave the file untouched — these are distinct from a missing file and are never treated as corruption

3) Prepare USDC trustlines

npm run setup:usdc

4) Start the app

npm run dev

Open http://localhost:3001.

[!NOTE] Mobile UI Limitations: The dashboard is currently optimized for desktop viewports. Mobile responsiveness improvements are planned (see #34), but elements like the sidebar navigation are currently hidden on screens narrower than 768px. For the best experience, we recommend using a desktop browser with a viewport width of 1024px or wider during development and testing.

Because INTERNAL_BASE_URL defaults to http://localhost:$PORT, local demo setup stays one-command simple: npm run dev.

API Quick Reference (curl)

With the dev server running (npm run dev), copy-paste these local-first examples:

System status:

curl -s http://localhost:3001/api/status

Agent registry:

curl -s http://localhost:3001/api/agents

Orchestrate a task:

curl -s -X POST http://localhost:3001/api/orchestrate \
  -H "Content-Type: application/json" \
  -d '{"task":"Summarize why x402 on Stellar matters in one concise paragraph.","budget":0.15}'

Live agent calls require a configured ANTHROPIC_API_KEY and funded testnet wallets.

Wallet balances:

curl -s http://localhost:3001/api/wallet/balances

Inspect orchestration admission queue:

curl -s http://localhost:3001/api/orchestrate/queue

Cancel an orchestration run:

curl -s -X POST http://localhost:3001/api/orchestrate/<runId>/cancel \
  -H "Content-Type: application/json" \
  -d '{"reason":"User requested cancellation"}'

For full request/response examples of every endpoint — including premium (x402-protected) endpoints, agent registry, wallet transactions, run history, event stream, and the orchestrator — see docs/API_EXAMPLES.md.

Deployment Notes

The orchestrator uses INTERNAL_BASE_URL for its paid internal calls to /api/premium/*.

• Local development: leave INTERNAL_BASE_URL unset and run npm run dev
• Single container / Docker Compose: set INTERNAL_BASE_URL=http://<service-name>:3001
• Remote or reverse-proxied deployment: set INTERNAL_BASE_URL to the server origin the orchestrator can actually reach, for example https://stellarmind.example.com

Examples:

# Local
PORT=3001

# Docker Compose
PORT=3001
INTERNAL_BASE_URL=http://stellarmind:3001

# Remote deployment behind HTTPS
PORT=3001
INTERNAL_BASE_URL=https://stellarmind.example.com

Orchestration Admission Queue & Concurrency Limits

Every accepted orchestration request can perform planning, provider LLM calls, and Stellar x402 payment settlements. Because individual runs can be slow or encounter network delays, request-rate limits alone do not bound active concurrency. StellarMind includes a configurable, single-process admission queue to bound active execution and memory pressure:

• Bounded Active Execution: Active orchestrations cannot exceed ORCHESTRATION_MAX_CONCURRENT (default: 2).
• Bounded Waiting Queue: Pending requests cannot exceed ORCHESTRATION_QUEUE_CAPACITY (default: 10). Excess requests are rejected immediately with HTTP 503 Service Unavailable and code QUEUE_CAPACITY_EXCEEDED.
• Queue Wait Deadlines: Requests waiting in queue longer than ORCHESTRATION_QUEUE_TIMEOUT_MS (default: 30000ms) are aborted with HTTP 503 Service Unavailable and code QUEUE_TIMEOUT.
• Overload Retry Guidance: Overload responses include a standard Retry-After header (in seconds) and response body containing current queue state to guide client backoff.
• Cancellation & Failure Guarantees: Client disconnects or explicit cancellation via POST /api/orchestrate/:id/cancel immediately dequeue pending items or abort active work, releasing slots exactly once.
• Single-Process Scope: This admission queue operates in-memory for this server process. It bounds execution and memory on the local node without requiring or promising multi-replica distributed coordination.

Configuration variables in .env:

Variable	Default	Description
ORCHESTRATION_MAX_CONCURRENT	2	Maximum concurrent active orchestration runs
ORCHESTRATION_QUEUE_CAPACITY	10	Maximum pending runs allowed in the admission queue
ORCHESTRATION_QUEUE_TIMEOUT_MS	30000	Maximum milliseconds a request can wait before timing out

Operational Health Checks

StellarMind exposes lightweight endpoints for deployment tooling and load balancer probes:

• GET /healthz
  • returns 200 and status: ok when the process is alive
  • no external dependency checks are performed
• GET /readyz
  • returns 200 when the configured critical components are ready
  • returns 503 when required configuration is missing

Example /readyz response:

{
  "status": "ready",
  "ready": true,
  "timestamp": "2026-05-28T12:00:00.000Z",
  "components": {
    "app": { "ready": true, "description": "Core HTTP server initialized" },
    "anthropic": {
      "configured": true,
      "ready": true,
      "description": "Anthropic API key is configured for Claude-powered agents"
    },
    "x402": { "enabled": true, "ready": true, "description": "x402 payment wallet is configured" }
  }
}

Request Correlation and Logs

• Every API request is assigned a correlation ID (x-correlation-id).
• Incoming x-correlation-id / x-request-id headers are reused when provided.
• Response always includes x-correlation-id.
• Structured logs default to JSON (LOG_FORMAT=json) and include correlation data for request lifecycle, orchestrator flow, and payment events.

Audit Run History

StellarMind persists orchestration and payment audit history.

• GET /api/runs?limit=20
  • returns recent runs across restarts when RUN_HISTORY_STORAGE=file
  • includes task, budget/spend summary, status, and tx proof linkage (txHash, explorerUrl)

Storage modes:

• RUN_HISTORY_STORAGE=file (default): durable JSON file
• RUN_HISTORY_STORAGE=memory: in-memory only (cleared on restart)

Available Commands

Command	Purpose
npm run dev	Start local server
npm run demo	Run end-to-end demo flow
npm run preflight	Validate readiness (x402, wallets, model, payment path)
npm run setup	Generate/fund Stellar testnet wallets
npm run setup:usdc	Add USDC trustlines for settlement
npm run lint	Run ESLint against the repository
npm run lint:fix	Fix ESLint issues automatically
npm run format	Format source and docs with Prettier
npm run record:video	Capture website-only demo video
npm run voiceover	Generate narration track
npm run record:narrated	Full narrated demo render pipeline

Demo Acceptance Checklist

• npm run preflight reaches ready state
• main run shows live orchestration events
• at least one transaction hash resolves in Stellar Expert
• low-budget run demonstrates step skipping
• final narrated video is exported and reviewed

Security and Publishing Hygiene

Before pushing to GitHub:

1. Do not commit .env or wallet secrets.
2. Rotate any key that was ever exposed in terminal logs or screenshots.
3. Keep only .env.example in version control.
4. Review staged files with git status and git diff --staged.
5. Verify no private keys are present in docs, recordings, or commits.

This repo includes:

• strict secret-ignore defaults in .gitignore
• a GitHub Actions secret scan workflow (.github/workflows/secret-scan.yml)
• a dedicated security policy (SECURITY.md)

Project Structure

src/
  agents/
    orchestrator.js
    registry.js
    services.js
  stellar/
    wallet.js
  config.js
  server.js
  demo.js
  demo-preflight.js
  setup-wallets.js
  setup-usdc.js
  record-demo-video.js
  generate-demo-voiceover.js
  render-narrated-demo.js
public/
  index.html                    # Semantic HTML shell
  assets/
    css/
      variables.css            # Design tokens & reset
      sidebar.css              # Navigation UI
      layout.css               # Page structure & responsive
      components.css           # Reusable UI elements
      pages.css                # Page-specific styles
    js/
      navigation.js            # Page routing
      budget.js                # Budget slider
      agents.js                # Agent registry
      wallet.js                # Wallet data
      sse.js                   # Real-time events
      rendering.js             # Result display
      orchestration.js         # Task execution
      pages.js                 # Page loading
      init.js                  # App startup

Frontend Architecture

The UI has been refactored from a monolithic 1,300-line HTML file into a modular structure:

• HTML: Semantic markup only (~150 lines)
• CSS: 5 organized modules (~1,060 lines) organized by concern
• JavaScript: 9 focused modules (~810 lines) organized by feature

See FRONTEND_STRUCTURE.md for detailed documentation on:

• CSS organization and design tokens
• JavaScript module dependencies
• API integration points
• Responsive design approach
• Testing and maintenance guidelines

Contributing

Read CONTRIBUTING.md before opening a PR.

License

MIT. See LICENSE.

🚀 Enhanced by Bounty Hunter

Quick Start

git clone https://github.com/Flamki/stellarmind.git
cd stellarmind
# Follow instructions above

CI Status

Automated testing and linting configured via GitHub Actions. pr-test