๐บ๏ธ Site Map & API Reference
Every page, endpoint, and external tool that makes up Bella Ciao. Share the Tier 0 section with Coinmania as the preview catalog.
๐ Dashboard pages
๐ EDU / Coinmania surfaces
๐ Public APIs
๐ B2B Tier 0 APIs (Coinmania preview)
๐ก๏ธ Admin APIs
๐ Observability (Grafana + Prometheus)
๐ ๏ธ Planned (Tier 1+)
๐ Dashboard Pages
Browser-facing pages served at the dashboard domain.
| Method | Path | Access | Purpose |
|---|---|---|---|
| PAGE | / / /dashboard | public | Main dashboard โ live signals, portfolio, แแแแแแกแ, crew status. |
| PAGE | /charts | public | TradingView widget + Bella Ciao's signal overlay + agent consensus strip. |
| PAGE | /analytics | public | Trade analytics โ win rate, profit factor, equity curve, per-trade log. |
| PAGE | /decisions | public | El Profesor-แแก แแแแแฌแงแแแขแแแแแแแแก แแฃแ แแแแ โ cycle history + reasoning. |
| PAGE | /backtest | public | Historical backtest runner (Q4 honest execution model). |
| PAGE | /sitemap | public | This page. Catalog of everything. |
| PAGE | /brain | admin | The Brain โ agents' internal telemetry terminal. |
| PAGE | /admin | admin | Admin panel โ trading mode, symbols, Rio config, agent prefs. |
| PAGE | /b2b | admin | B2B execution desk (Coinmania hedge orders overview). |
| PAGE | /login | public | Login form (admin credentials). |
๐ Coinmania / EDU Surfaces
Customer-facing educational + market-intelligence pages (Bella Edu). All public.
| Method | Path | Access | Purpose |
|---|---|---|---|
| PAGE | /controlV3b | public | SCADA Hub ยท Pro Data โ 6 agent cards + El Profesor verdict (LIVE). The flagship EDU view. |
| PAGE | /controlV3b/agent?id=โฆ | public | Per-agent detail โ portrait, live "today's read", 4-card lessons + 3-question quiz. |
| PAGE | /lessons | public | ๐ Lessons Library โ the full trading curriculum (all agents) in one browsable, filterable page. |
| PAGE | /control | public | Market Control ยท SCADA โ expert room + 9-step El Profesor guided tour. |
| PAGE | /controlV3 ยท /controlV3a ยท /controlV3a-globe | public | controlV3 variants โ Cafรฉ/HQ ยท SCADA Hub ยท SCADA Hub + realistic Three.js Earth. |
| PAGE | /controlv2 ยท /controlv2-agents | public | controlV2 โ 3D/voice "market map" (Three.js + ElevenLabs) + 7-agent viewer. (+ slice0/2/3 build milestones.) |
| PAGE | /market ยท /market-control ยท /market-flow | public | Coinmania Market Lens โ landing ยท command ยท flow. |
| PAGE | /edu-preview | public | Bella Edu โ product mockup (character moods + glossary + daily lesson). |
| PAGE | /analysis | public | Narrative analysis โ El Profesor + crew bilingual walkthrough. |
๐ Public APIs
Unauthenticated JSON endpoints powering the dashboard + available for anyone.
| Method | Path | Description |
|---|---|---|
| GET | /api/analytics | Aggregated trade performance (win rate, profit factor, equity curve). |
| GET | /api/reports/weekly?window_days=N&format=json|text | Q3 weekly performance report. JSON แแ plain-text. `window_days` โ [1, 90]. |
| GET | /api/agent-scorecards | O5 per-agent accuracy + expectancy (แชแแชแฎแแแ Redis-แแแ). |
| GET | /metrics | Prometheus text-exposition (api-side counters). Used by Grafana scrape. |
| WS | /ws | Real-time push: agent updates, decisions, trade events. Auth via cookie/header/query token. |
| GET | /api/v1/signals | ADR-004 S1.5: list all cached per-symbol signals (10 pairs, 16-min TTL). |
| GET | /api/v1/signals/{symbol} | ADR-004 S1.5: single symbol's SymbolSignal โ 404 on cache miss. |
๐ B2B Tier 0 APIs Tier 0
Public preview endpoints for Coinmania โ no auth required. Share this section directly with Coinmania's technical team.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/b2b/tier | Current tier level + capabilities. Coinmania's dashboard uses this. |
| GET | /api/v1/b2b/tier0/status | Live bot snapshot โ current signal, agent analyses, portfolio. |
| GET | /api/v1/b2b/tier0/weekly-report?days=N | Q3 weekly report scoped for Tier 0. Capped at 30 days in Tier 0, 90 in Tier 1+. |
| GET | /api/v1/b2b/readiness?days=N | Tier 1 โ Tier 2 promotion gate evaluator (Sharpe, MaxDD, trades โฅ 100). |
Tier 0-แจแ Coinmania แฎแแแแแก: read-only dashboard + แแก 4 endpoint-แ.
แ แแก แแ แฎแแแแแก: programmatic signal API (Tier 1+),
per-agent scorecards (NDA-แแแ), internal operational counters.
๐ก๏ธ Admin APIs admin only
Require admin JWT (`Cookie: bellaciao_token=...`). Router-level gated.
| Method | Path | Description |
|---|---|---|
| POST | /api/auth/login | Admin login โ returns JWT as HttpOnly SameSite=Strict cookie. |
| POST | /api/auth/logout | Clear admin cookie. |
| GET | /api/admin/system | System config snapshot (version, mode, symbols, cycle interval). |
| POST | /api/admin/trading-mode | Toggle paper / testnet / live mode. |
| POST | /api/admin/rio/config | Update Rio config (SL/TP floors, trailing, max positions, circuit breaker). |
| POST | /api/admin/symbols | Change traded pairs. Applies on next cycle. |
| POST | /api/admin/agents/{name}/prefs | Toggle is_active, swap model, adjust temperature for an agent. |
| POST | /api/admin/b2b/disable | ๐จ Engage B2B kill-switch (ADR-003 Tier 2 revocation). |
| POST | /api/admin/b2b/enable | Release kill-switch (re-enable live hedge execution). |
| GET | /api/admin/b2b/kill-switch-status | Query current kill-switch state. |
๐ Observability external tools
Prometheus + Grafana stack (Q2). Not on the primary dashboard domain โ direct host:port access, nginx allow-list required in prod.
| Tool | URL | Purpose |
|---|---|---|
| EXT | http://HOST:3001 |
Grafana โ Bella Ciao operational dashboard. Login: admin / see GRAFANA_ADMIN_PASSWORD in server .env.Password retrieve (server shell): grep GRAFANA_ADMIN_PASSWORD /home/ubuntu/bellaciao/.env
|
| EXT | http://HOST:9090 |
Prometheus UI โ metric explorer + alert state. No auth (internal access via nginx allow-list). Useful: /targets (scrape health), /alerts (rule state).
|
| EXT | http://HOST:9101/metrics | Trader metrics (cycle, agents, trades, PnL). Prometheus scrape target. |
| EXT | /metrics | API metrics (HTTP requests, WS clients). Prometheus scrape target. |
Security: in production nginx only allows the scrape IP for ports 9090, 9101.
The Grafana admin password was generated per-install via
openssl rand
and is NOT committed to git.
๐ ๏ธ Planned โ Tier 1+ Programmatic API not yet available
Unlocked when Coinmania promotes to Tier 1 (post-NDA, post-Phase O). Listed here so Coinmania's team can plan their integration.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/b2b/signal/{symbol} | แแแแแแแแ แ Profesor-แแก แแแแแฌแงแแแขแแแแแ + confidence แแแแแ แแขแฃแแ แฌแงแแแแแกแแแแก. |
| GET | /api/v1/b2b/consensus | แงแแแแแ แแแแแขแแก แแฎแแแ แแแแแแแ (แชแแชแฎแแ แแ แแจแ, 15-แฌแฃแแแแแ cadence). |
| WS | /api/v1/b2b/stream | Real-time push โ แแฎแแแ แแแแแฌแงแแแขแแแแแแก แแแ แขแงแแ แแแแแแแแแ แ แแแแ แช แแ Profesor แแแแแแ แแแก. |
| POST | /api/v1/b2b/hedge-order | Legacy ADR-003 hedge intent endpoint (kept for backward compat). Tier 1: logged only, Tier 2: real execution. |
| POST | /api/v1/b2b/hedge-order-v2 | ADR-004 Week 4: smart hedge routing with 7-agent AI decision engine. Returns ExecutionPlan + outcome (MARKET / LIMIT / STOP_LIMIT / TRAILING_STOP) based on per-symbol cached signal. Rate limit: 60+/min. p95 decision latency < 10ms. |
| GET | /api/v1/b2b/hedge-performance?days=N | ADR-004 Week 4: N-day diff report โ Bella's simulated / realized edge vs naive MARKET baseline. Shared with Coinmania for Tier 2 promotion readiness evidence. |
แแแแแกแแแแก แแแแขแแแ (ADR-003):
Tier 0 โ Tier 1 = NDA + Phase O complete โ
.
Tier 1 โ Tier 2 = 90 แแฆแ paper mode + Sharpe โฅ 1.0 + MaxDD โค 15%
+ โฅ 100 trades + 30-day 100% uptime + legal agreement signed.
๐ Documentation
| แฅแแ แแฃแแ โ แแแแ แแขแแ แ | docs/ka/TRADER_GUIDE.md |
| แฅแแ แแฃแแ โ Bella Ciao แแแแแฏแแแแขแ | docs/ka/MANAGEMENT_BRIEF.md |
| แฅแแ แแฃแแ โ Coinmania | docs/ka/COINMANIA_BRIEF.md |
| ADR-003 (phased rollout) | docs/decisions/ADR-003-โฆ |
| Observability runbook | docs/runbooks/observability.md |
| Session log (แแกแขแแ แแ) | docs/SESSION_LOG.md |
๐ต Bella Ciao โ "Every heist needs a perfect plan." โ El Profesor