205 lines
6.6 KiB
Markdown
205 lines
6.6 KiB
Markdown
# SPEC-052 — Invest Trade Specs + Alice Monitor + Exit-to-Base (paper sandbox)
|
|
|
|
**SPEC-ID:** 052-MYVEXX
|
|
**Vincula:** 049, 050, 051
|
|
**Org Forgejo:** `myvexx` (≠ ligbox)
|
|
**Status:** ✅ Sandbox paper operacional (actualizado 2026-08-07)
|
|
**Para:** Roger
|
|
**Runtime:** CT124 (`invest.myvexx.com`) · Bridge `:3100` · OpenAlice `:47331`
|
|
|
|
---
|
|
|
|
## 1. Objectivo
|
|
|
|
Escolher índice/crypto → (opcional) Alice investiga → **spec no Invest** (alvo, alavancagem simulada, modo de saída) → motor monitoriza → ao atingir alvo **fecha e volta à conta base** (paper).
|
|
|
|
Fluxo:
|
|
|
|
```text
|
|
Activo → OpenAlice (investigar) → Spec no Invest/bridge
|
|
↓
|
|
tick_live (preço real Yahoo) ou simulate
|
|
↓
|
|
alvo +1,20%? → aviso | semi | auto_paper → conta base
|
|
```
|
|
|
|
---
|
|
|
|
## 2. O que foi realizado (changelog)
|
|
|
|
| Data | Entrega | Estado |
|
|
|------|---------|--------|
|
|
| 2026-08-05 | Motor sandbox no bridge (`sandbox.py`) | ✅ |
|
|
| 2026-08-05 | API criar/listar/tick/simulate/confirm_close | ✅ |
|
|
| 2026-08-05 | Testes dos 3 modos (aviso / semi / auto_paper) | ✅ |
|
|
| 2026-08-05 | **Opção 2:** `tick_live` + `markets/quote` (Yahoo) | ✅ |
|
|
| 2026-08-05 | UI Invest `/agents` (criar specs, OpenAlice link) | ✅ |
|
|
| 2026-08-05 | `GET /architecture` no bridge | ✅ |
|
|
| 2026-08-05 | Docs + Forgejo `myvexx/invest-myvexx` + vault | ✅ |
|
|
|
|
### Ficheiros principais (CT124)
|
|
|
|
| Path | Papel |
|
|
|------|--------|
|
|
| `/opt/invest/agents/bridge/main.py` | API bridge v0.2 |
|
|
| `/opt/invest/agents/bridge/sandbox.py` | Motor de specs / saída |
|
|
| `/opt/invest/agents/bridge/markets.py` | Quotes Yahoo (Index Hub mínimo) |
|
|
| `/opt/invest/invest.myvexx.com/frontend/src/pages/Agents.js` | UI `/agents` |
|
|
| `/opt/invest/agents/docs/ARCHITECTURE-INVEST-OPENALICE-OPTION2.md` | Diagrama arquitectura |
|
|
|
|
### URLs
|
|
|
|
| URL | Função |
|
|
|-----|--------|
|
|
| https://invest.myvexx.com/agents | UI specs paper |
|
|
| https://invest.myvexx.com/api/agents/health | Health bridge |
|
|
| https://invest.myvexx.com/api/agents/sandbox/specs | Specs API |
|
|
| https://invest.myvexx.com/api/agents/markets/quote?symbol=NVDA | Cotação real |
|
|
| https://openalice.myvexx.com/ | Investigação Alice |
|
|
| https://git.spec.ligbox.com.br/myvexx/invest-myvexx | Specs no Forgejo |
|
|
|
|
---
|
|
|
|
## 3. Contrato da Spec (Invest / bridge)
|
|
|
|
```json
|
|
{
|
|
"symbol": "NVDA",
|
|
"asset_class": "equity",
|
|
"entry_price": 100.0,
|
|
"target_pct": 1.20,
|
|
"leverage_sim": 1.0,
|
|
"exit_mode": "aviso|semi|auto_paper",
|
|
"stop_pct": null,
|
|
"note": "opcional"
|
|
}
|
|
```
|
|
|
|
- `target_pct` = **+1,20%** sobre `entry_price` (lucro percentual).
|
|
- `leverage_sim` = factor só para P&L **simulado**.
|
|
- `asset_class`: `equity` | `crypto` | `index` | `fx` (aliases: BTC→BTC-USD, SPX→^GSPC, IBOV→^BVSP…).
|
|
|
|
### Estados
|
|
|
|
| Status | Significado |
|
|
|--------|-------------|
|
|
| `watching` | A monitorizar |
|
|
| `alerted` | Alvo atingido (modo aviso) |
|
|
| `ready_to_close` | Alvo atingido (modo semi — falta confirm) |
|
|
| `closed_to_base` | Fechado / voltou à base |
|
|
| `aborted` | Stop hit |
|
|
|
|
---
|
|
|
|
## 4. Modos de saída
|
|
|
|
| Modo | Comportamento |
|
|
|------|----------------|
|
|
| **aviso** | Ao alvo → `alerted`; não fecha sozinho |
|
|
| **semi** | Ao alvo → `ready_to_close`; `POST .../confirm_close` |
|
|
| **auto_paper** | Ao alvo → `closed_to_base` automático |
|
|
|
|
Live broker: **proibido** (`ALLOW_LIVE_BROKER=0`).
|
|
|
|
---
|
|
|
|
## 5. Como funciona (passo a passo)
|
|
|
|
1. Login em `invest.myvexx.com` → menu **Agents / Specs**.
|
|
2. (Opcional) **Abrir OpenAlice** e investigar o activo.
|
|
3. **Cotação real → entrada** (Yahoo via bridge).
|
|
4. Definir alvo `%`, alavancagem sim, modo de saída → **Criar spec paper**.
|
|
5. **tick_live** = puxa preço real e aplica regras; **simulate** = sobe preço artificial até ao alvo.
|
|
6. Se `semi` → **confirm_close**. Se `auto_paper` → já fica `closed_to_base`.
|
|
|
|
### API (Traefik strip `/api/agents` → bridge `:3100`)
|
|
|
|
| Método | Path | Função |
|
|
|--------|------|--------|
|
|
| GET | `/health` | Saúde + contagem specs |
|
|
| GET | `/architecture` | Diagrama/fluxo opção 2 |
|
|
| GET | `/markets/quote?symbol=&asset_class=` | Preço real Yahoo |
|
|
| POST | `/sandbox/specs` | Criar spec |
|
|
| GET | `/sandbox/specs` | Listar |
|
|
| GET | `/sandbox/specs/{id}` | Detalhe |
|
|
| POST | `/sandbox/specs/{id}/tick` | Preço manual |
|
|
| POST | `/sandbox/specs/{id}/tick_live` | **Opção 2** — preço real |
|
|
| POST | `/sandbox/specs/{id}/simulate` | Path artificial até alvo |
|
|
| POST | `/sandbox/specs/{id}/confirm_close` | Semi: confirmar fecho |
|
|
|
|
### Teste rápido (CLI)
|
|
|
|
```bash
|
|
# cotação
|
|
curl -sk 'https://invest.myvexx.com/api/agents/markets/quote?symbol=NVDA'
|
|
|
|
# criar + tick real
|
|
curl -sk -X POST https://invest.myvexx.com/api/agents/sandbox/specs \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"symbol":"NVDA","entry_price":221.0,"target_pct":1.20,"exit_mode":"aviso"}'
|
|
|
|
curl -sk -X POST https://invest.myvexx.com/api/agents/sandbox/specs/<ID>/tick_live
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Arquitectura (opção 2)
|
|
|
|
```text
|
|
invest.myvexx.com/agents
|
|
│ /api/agents/*
|
|
▼
|
|
Bridge :3100 ── markets/quote (Yahoo)
|
|
│ sandbox motor (alvo / saída)
|
|
│ research TradingAgents (opcional)
|
|
▼
|
|
OpenAlice :47331 — investigação / workspace (paper)
|
|
```
|
|
|
|
Detalhe: `ARCHITECTURE-INVEST-OPENALICE-OPTION2.md`.
|
|
|
|
---
|
|
|
|
## 7. Constraints
|
|
|
|
1. Alvo % = trigger, não garantia de fill.
|
|
2. Alavancagem = simulada (não broker).
|
|
3. Auto só em paper; live = futuro + gate humano.
|
|
4. Spec no Invest/bridge = fonte da verdade.
|
|
5. Equity/crypto = mesmo contrato; adapters depois.
|
|
6. Polling / tick manual; websocket = depois.
|
|
|
|
---
|
|
|
|
## 8. Critério de done — sandbox (cumprido)
|
|
|
|
| # | Critério | Resultado |
|
|
|---|----------|-----------|
|
|
| 1 | Spec NVDA alvo 1,20% `auto_paper` | ✅ |
|
|
| 2 | `simulate` ≥ +1,20% | ✅ `closed_to_base` |
|
|
| 3 | Modos `aviso` e `semi` | ✅ |
|
|
| 4 | `tick_live` com preço Yahoo | ✅ |
|
|
| 5 | UI `/agents` | ✅ |
|
|
|
|
---
|
|
|
|
## 9. Pendente / próximo (fora do done 052)
|
|
|
|
| Item | Notas |
|
|
|------|--------|
|
|
| LLM key TradingAgents | Research real (`dry_run:false`) |
|
|
| OpenAlice Claude/Codex OAuth | Agents a falar no container |
|
|
| Monitor automático (cron/loop) | Hoje tick é manual na UI |
|
|
| Alice ler spec via bridge | Sync Invest → workspace Alice |
|
|
| Index Hub completo (051 Fase B) | Histórico OHLC, +providers, cache KPI |
|
|
| SSO cookie OpenAlice | Ainda token admin separado |
|
|
| Paper broker real (Alpaca paper) | Só se ligar UTA — nunca live |
|
|
| Live trading | **Fora de escopo** até SPEC explícita |
|
|
|
|
---
|
|
|
|
## 10. Fora de escopo permanente (até nova SPEC)
|
|
|
|
- Ordem live / UTA com fundos reais
|
|
- Unificar senha Invest = token OpenAlice
|
|
- Patch OpenAlice para password fraca
|