AelixAELIX/ DOCS
← SiteGitHub
19, Going Public

Backend API

Run the Aelix public backend and call its REST API, auth, the Rule-Keeper, Portfolio X-Ray, the 24/7 desk, and alerts.

The public backend lives in `backend/` and is a zero-dependency Node service, it runs with plain node, no npm install. In its default mock mode it serves a demo account, so the whole API works with no credentials (great for local dev, CI, and the frontend).

Run it

bash
cd backend
cp .env.example .env        # optional in dev, ephemeral secrets auto-generate
npm start                   # → http://localhost:8787  (broker=mock)
npm test                    # deterministic Rule-Keeper + crypto tests

Auth flow

Sign up or log in to get a JWT, then send it as Authorization: Bearer <token> on every authenticated call.

bash
BASE=http://localhost:8787

# sign up → { token, user }
curl -s $BASE/v1/auth/signup -H 'content-type: application/json' \
  -d '{"email":"you@example.com","password":"supersecret"}'

# then use the token
TOKEN=... ; AUTH="authorization: Bearer $TOKEN"

Endpoints

MethodPathAuthPurpose
GET/health–Liveness.
GET/v1/meta–Broker mode, feature flags, default caps.
POST/v1/auth/signup–Create account → { token, user }.
POST/v1/auth/login–→ { token, user }.
GET/v1/me✓Current user.
PUT/v1/me/settings✓autoScan, scanIntervalSec.
POST/v1/broker/connect✓Store the user's Robinhood OAuth token (encrypted).
GET/v1/broker/status✓Connection + account snapshot.
DELETE/v1/broker✓Disconnect (delete token).
GET / PUT/v1/rules✓Read / update the user's risk caps.
POST/v1/rulekeeper/check✓Check a trade vs the rules → verdict.
GET/v1/desk✓Latest persisted desk snapshot.
POST/v1/desk/run✓Run a fresh read-only desk pass now.
GET/v1/xray✓Fresh portfolio x-ray.
GET/v1/alerts✓Recent alerts.
POST/v1/alerts/read✓Mark alerts read.

Add ?explain=1 to /v1/rulekeeper/check and /v1/xray to get a plain-language coach note (only when ANTHROPIC_API_KEY is configured).

The Rule-Keeper

The core endpoint. You send a trade the user wants to make; it returns a verdict against the user's own caps with explicit, checkable math, APPROVE, APPROVE-WITH-CHANGES (with a compliant suggestedQty), or VETO.

bash
curl -s $BASE/v1/rulekeeper/check -H "$AUTH" -H 'content-type: application/json' \
  -d '{"trade":{"symbol":"AAPL","side":"buy","qty":40,"price":208,"stop":195}}'
response
{
  "trade": { "symbol": "AAPL", "side": "buy", "qty": 40, "price": 208, "stop": 195 },
  "verdict": {
    "decision": "VETO",
    "reasons": [
      "Post-trade AAPL weight vs concentration cap (25%).",
      "Cash after buy is below your 10% buffer.",
      "No compliant size available, your concentration cap leaves no room to add AAPL."
    ],
    "checks": [ { "name": "per-trade cap", "ok": false, "detail": "..." } ],
    "suggestedQty": 0,
    "sizing": { "qty": 0, "maxNotional": 0, "boundBy": "concentration cap" }
  },
  "explanation": null
}

The default caps

New users start with the same conservative defaults as the desk's `strategies/`. Each user owns and edits their own via PUT /v1/rules.

json
{
  "perTradePct": 15,
  "maxConcentrationPct": 25,
  "maxOpenPositions": 6,
  "maxDailyOrders": 4,
  "stopLossPct": 8,
  "dailyLossHaltPct": 5,
  "cashBufferPct": 10,
  "noAveragingIntoLosers": true
}

Portfolio X-Ray

GET /v1/xray returns objective analytics on what the user already owns, concentration, sector exposure, cash %, a 0–100 discipline healthScore, and flags tied to the user's own caps (concentration breach, stop-breach, earnings-soon, underwater, cash-buffer). No recommendations.

The full endpoint list, deploy steps, and production checklist live in backend/README.md. Architecture + the legal gates are in Public Architecture.

Zero-dep NodeJWT authmock + mcp brokercurl-ableDocker-ready
Edit this page on GitHub ↗