# 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