docs: initial project documents (Libro Frattali + Pythagoras Trading Prediction summaries)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-26 23:31:41 +02:00
commit 49ee092c7f
3 changed files with 586 additions and 0 deletions
@@ -0,0 +1,294 @@
+# Cerbero MCP — API Reference (V2.0.0)
+
+Documento di riferimento completo per tutti gli endpoint HTTP e i tool MCP
+esposti dal container `cerbero-mcp`. Generato dall'analisi diretta dei
+router FastAPI in `src/cerbero_mcp/routers/`.
+
+---
+
+## 1. Autenticazione
+
+Tutte le chiamate ai namespace `/mcp-*` richiedono:
+
+| Header | Valore | Note |
+|---|---|---|
+| `Authorization` | `Bearer <TOKEN>` | `TESTNET_TOKEN` → upstream testnet · `MAINNET_TOKEN` → upstream live · token sconosciuto → `401` |
+| `X-Bot-Tag` | stringa ≤ 64 char | identifica il bot chiamante, loggato nell'audit · mancante → `400` |
+
+Gli endpoint pubblici (`/health`, `/apidocs`, `/openapi.json`) non
+richiedono auth. L'endpoint `/admin/audit` richiede bearer ma **non**
+richiede `X-Bot-Tag`.
+
+---
+
+## 2. Endpoint pubblici
+
+| Path | Metodo | Descrizione |
+|---|---|---|
+| `/health` | GET | Liveness — sempre `200` finché il processo è vivo |
+| `/health/ready` | GET | Readiness — itera i client registry, status `ready` / `degraded` / `not_ready`. Forza `503` se `READY_FAILS_ON_DEGRADED=true` |
+| `/apidocs` | GET | Swagger UI interattiva |
+| `/openapi.json` | GET | Schema OpenAPI 3.1 |
+
+---
+
+## 3. Endpoint admin
+
+| Path | Metodo | Descrizione |
+|---|---|---|
+| `/admin/audit` | GET | Query del JSONL `AUDIT_LOG_FILE`. Filtri: `from`, `to`, `actor`, `exchange`, `action`, `bot_tag`, `limit` (default 1000, max 10000) |
+| `/admin/ibkr/rotate-keys/confirm?env=` | POST | Swap atomico chiavi IBKR con auto-rollback su validazione fallita |
+
+---
+
+## 4. Namespace MCP — panoramica
+
+| Namespace | Tool | Tipo | Note |
+|---|---|---|---|
+| `/mcp-deribit/tools/*` | 33 | exchange (options-first) | DVOL, GEX, dealer gamma, spread payoff |
+| `/mcp-bybit/tools/*` | 30 | exchange (spot + perp + options) | basis, funding, batch orders |
+| `/mcp-hyperliquid/tools/*` | 16 | exchange (perp DEX) | L1 signing, leverage cap |
+| `/mcp-alpaca/tools/*` | 18 | exchange (US stocks + options) | clock/calendar, fractional |
+| `/mcp-ibkr/tools/*` | 24 | exchange (multi-asset broker) | OAuth 1.0a, streaming WS, bracket/OCO/OTO |
+| `/mcp-macro/tools/*` | 11 | data provider (read-only) | yields, FRED, COT |
+| `/mcp-sentiment/tools/*` | 9 | data provider (read-only) | news, social, funding cross-exchange |
+| `/mcp-cross/tools/*` | 1 | aggregator | storico consensus multi-exchange |
+
+**Totale**: ~142 tool MCP.
+
+---
+
+## 5. `/mcp-deribit/tools/*`
+
+### Info
+- `is_testnet` — flag ambiente corrente
+- `environment_info` — stringa diagnostica completa
+
+### Market data
+- `get_ticker`, `get_ticker_batch`
+- `get_instruments`
+- `get_orderbook`, `get_orderbook_imbalance`
+- `get_historical` (chiave `candles` uniforme)
+- `get_trade_history`
+
+### Account
+- `get_positions`
+- `get_account_summary`
+
+### Options analytics
+- `get_dvol`, `get_dvol_history`
+- `get_gex`, `get_dealer_gamma_profile`
+- `get_vanna_charm`
+- `get_oi_weighted_skew`, `get_smile_asymmetry`, `get_atm_vs_wings_vol`
+- `get_pc_ratio`, `get_skew_25d`, `get_term_structure`
+- `get_iv_rank`, `get_realized_vol`
+- `find_by_delta`, `calculate_spread_payoff`
+
+### Technicals
+- `get_technical_indicators`
+- `run_backtest`
+
+### Write (richiede leverage cap)
+- `place_order`, `place_combo_order`
+- `cancel_order`
+- `set_stop_loss`, `set_take_profit`
+- `close_position`
+
+---
+
+## 6. `/mcp-bybit/tools/*`
+
+### Info
+- `environment_info`
+
+### Market data
+- `get_ticker`, `get_ticker_batch`
+- `get_orderbook`, `get_orderbook_imbalance`
+- `get_historical`
+- `get_instruments`, `get_option_chain`
+- `get_trade_history`
+
+### Derivati
+- `get_funding_rate`, `get_funding_history`
+- `get_open_interest`
+- `get_basis_spot_perp`, `get_basis_term_structure`
+
+### Account
+- `get_positions`, `get_account_summary`, `get_open_orders`
+
+### Technicals
+- `get_indicators`
+
+### Write
+- `place_order`, `place_combo_order`
+- `amend_order`, `cancel_order`, `cancel_all_orders`
+- `set_stop_loss`, `set_take_profit`, `close_position`
+- `set_leverage`, `switch_position_mode`
+- `transfer_asset`
+
+---
+
+## 7. `/mcp-hyperliquid/tools/*`
+
+### Info
+- `environment_info`
+
+### Market data
+- `get_markets`, `get_ticker`, `get_orderbook`
+- `get_historical`, `get_trade_history`
+- `get_funding_rate`, `basis_spot_perp`
+
+### Account
+- `get_positions`, `get_account_summary`, `get_open_orders`
+
+### Technicals
+- `get_indicators`
+
+### Write (L1 signing + leverage cap)
+- `place_order`, `cancel_order`
+- `set_stop_loss`, `set_take_profit`
+- `close_position`
+
+---
+
+## 8. `/mcp-alpaca/tools/*`
+
+### Info / calendar
+- `environment_info`, `get_clock`, `get_calendar`
+
+### Market data
+- `get_assets`, `get_ticker`
+- `get_bars`, `get_snapshot`
+- `get_option_chain`
+
+### Account
+- `get_account`, `get_positions`, `get_activities`, `get_open_orders`
+
+### Write
+- `place_order`, `amend_order`
+- `cancel_order`, `cancel_all_orders`
+- `close_position`, `close_all_positions`
+
+> **Nota**: override URL applicato solo all'endpoint trading. Gli
+> endpoint dati (`data.alpaca.markets`) restano i default SDK.
+
+---
+
+## 9. `/mcp-ibkr/tools/*`
+
+Auth via OAuth 1.0a Self-Service con minting di session token
+unattended. Setup one-time per ambiente (paper + live) — vedi sezione
+"IBKR Setup" del README.
+
+### Info / clock
+- `environment_info`, `get_clock`
+
+### Account
+- `get_account`, `get_positions`
+- `get_open_orders`, `get_activities`
+
+### Market data
+- `get_ticker`, `get_bars`, `get_snapshot`
+- `get_option_chain`, `search_contracts`
+
+### Streaming (WebSocket singleton)
+- `get_tick`, `get_depth`
+- `subscribe_tick`, `unsubscribe`
+
+### Write
+- `place_order`, `amend_order`
+- `cancel_order`, `cancel_all_orders`
+- `close_position`, `close_all_positions`
+
+### Complex orders
+- `place_bracket_order` — entry + TP + SL atomico
+- `place_oco_order` — One-Cancels-Other (OCA group)
+- `place_oto_order` — One-Triggers-Other (parent → child)
+
+---
+
+## 10. `/mcp-macro/tools/*` (read-only)
+
+| Tool | Sorgente |
+|---|---|
+| `get_economic_indicators` | FRED + Yahoo |
+| `get_macro_calendar` | Finnhub + impact heuristic |
+| `get_market_overview` | mix Yahoo + Deribit DVOL |
+| `get_asset_price` | Yahoo Finance |
+| `get_treasury_yields` | US Treasury XML |
+| `get_equity_futures` | Yahoo |
+| `get_yield_curve_slope` | derivato da treasury yields |
+| `get_breakeven_inflation` | FRED (T10YIE / T5YIE) |
+| `get_cot_tff` | CFTC TFF report |
+| `get_cot_disaggregated` | CFTC disaggregated report |
+| `get_cot_extreme_positioning` | percentili COT (gate ±5%) |
+
+---
+
+## 11. `/mcp-sentiment/tools/*` (read-only)
+
+| Tool | Fonte |
+|---|---|
+| `get_crypto_news` | CryptoPanic + CoinDesk + CryptoCompare + Messari (deduped) |
+| `get_world_news` | aggregato generalista |
+| `get_social_sentiment` | LunarCrush + Fear&Greed Index |
+| `get_funding_rates` | per-asset multi-exchange |
+| `get_cross_exchange_funding` | snapshot multi-asset multi-venue |
+| `get_funding_arb_spread` | spread arbitraggio funding |
+| `get_oi_history` | open interest serie storica |
+| `get_liquidation_heatmap` | heatmap liquidazioni |
+| `get_cointegration_pairs` | screening coppie cointegrate |
+
+---
+
+## 12. `/mcp-cross/tools/*`
+
+### `get_historical`
+Aggregatore cross-exchange. Fan-out a tutti gli exchange che supportano
+`(symbol, asset_class)`, poi consensus per-bar:
+
+- `close` = mediana delle close
+- `open`/`high`/`low` = mediana corrispondente
+- `sources` = numero di exchange che hanno contribuito al bar
+- `div_pct = (max - min) / median` → quality gate per i bot
+
+**Crypto** (`asset_class: "crypto"`): BTC, ETH, SOL via Bybit +
+Hyperliquid + Deribit.
+**Stocks** (`asset_class: "stocks"`): AAPL, SPY, QQQ, TSLA, NVDA via
+Alpaca.
+
+In caso di fallimento parziale ritorna i bar disponibili più
+`failed_sources: [...]`. Se *tutti* gli upstream falliscono → `502
+Bad Gateway` retryable.
+
+---
+
+## 13. Observability
+
+### Request log (`mcp.request`)
+Una riga JSON per richiesta con: `request_id`, `method`, `path`,
+`status_code`, `duration_ms`, `actor`, `bot_tag`, `exchange`, `tool`,
+`client_ip`, `user_agent`.
+
+### Audit log (`mcp.audit`)
+Persistito su `AUDIT_LOG_FILE` (JSONL) per le operazioni write.
+Rotazione configurabile via `AUDIT_LOG_BACKUP_DAYS`.
+
+### Correlation
+Lo stesso `request_id` appare in `mcp.request`, `mcp.audit` e
+nell'envelope di errore restituito al client.
+
+---
+
+## 14. Esempio chiamata
+
+```bash
+curl -X POST http://localhost:9000/mcp-bybit/tools/get_ticker \
+  -H "Authorization: Bearer $MAINNET_TOKEN" \
+  -H "X-Bot-Tag: scanner-alpha-prod" \
+  -H "Content-Type: application/json" \
+  -d '{"symbol":"BTCUSDT","category":"linear"}'
+```
+
+Per lo schema completo dei body di richiesta e risposta:
+<http://localhost:9000/apidocs>.