[REST API SERVER]

OpenCatz AI ships with a native, zero-dependency REST API server (src/api/server.ts) listening on port 3000 by default (configurable via API_PORT in .env). It includes full CORS headers (Access-Control-Allow-Origin: *) and optional API Key security via OPENCATZ_API_KEY.

Authentication & Headers

If OPENCATZ_API_KEY is set in your .env, pass the authentication token in either of the following headers:

# Option A: Custom Header
X-OpenCatz-Api-Key: your_secret_key_here

# Option B: Standard Authorization Bearer
Authorization: Bearer your_secret_key_here

API Endpoints Specification

Method	Endpoint	Description
`GET`	`/api/status (or /health)`	Full system status, execution mode (DRY_RUN vs LIVE), active sub-agents, market regime, kill-switch status, and connected API keys.
`GET`	`/api/calls`	Historical signal calls evaluated by Swarm Consensus across all specialist sub-agents. Supports `?domain=alpha-robinhood&limit=50` filters.
`GET`	`/api/positions`	Active token holdings, LP positions, and NFT positions with real-time PnL and TP/SL milestone tracking.
`GET`	`/api/executions`	Trade journal ledger entries, win-rate metrics, total realized PnL, and transaction execution stats.
`GET`	`/api/alerts`	Active custom price alerts and notification triggers configured by users.
`POST`	`/api/agents/toggle`	Dynamically activate or pause a specific specialist sub-agent domain. Body: `{"domain": "alpha-robinhood", "active": true}`.
`POST`	`/api/command`	Execute ToolRegistry actions directly from web UI inputs. Body: `{"command": "pause_sub_agent", "args": {"agentId": "nft"}}`.

Example Status Response

{
  "success": true,
  "status": "HEALTHY",
  "executionMode": "DRY_RUN",
  "primaryVenue": "Uniswap V3 • Robinhood Chain L2 (#4663)",
  "activeDomains": ["meme-robinhood", "lp-robinhood", "nft", "alpha-robinhood", "whale-eth"],
  "marketRegime": { "regime": "TRENDING_BULLISH", "volatility": "NORMAL" },
  "connectedApiKeys": {
    "opensea": true,
    "xApiV2": true,
    "llm": true,
    "gmgn": true
  },
  "timestamp": "2026-08-18T20:20:00.000Z"
}