# FinanceManager approval bridge for CryptoTrader

Use when connecting a trading bot such as Crypto_Agent/Hyperliquid to the user's FinanceManager dashboard.

## Principle

The dashboard is a control, approval, audit, and visibility layer. It must not be the exchange executor.

A safe first increment is a **read-only bridge cockpit**: ingest runtime files/reports, expose only status/signals/scorecards/open positions, and prove all signal cards have `execution_allowed=false`. In the FinanceManager v1 implementation this used `/api/crypto-trader/status`, `/signals`, `/scorecard`, `/hyperliquid-portfolio`, and `/snapshot`, plus a Vue `/crypto/hyperliquid` page. This pattern is reusable: restart only the local Finance API/frontend if needed, never the trading bot, and verify with safe shape/count smokes plus browser console.

For the approval-reader increment, make the dashboard approval log self-describing: write `intent_id` plus `strategy_id`, `coin`, `portfolio_id`, `source_engine`, `side`, `signal`, and `intent_created_at`. The bot should first match by exact `intent_id`, then fall back to `strategy_id + coin`, and otherwise fail closed. A matched `approve` is still only `approved_pending_crypto_trader_gates`; it must not bypass reconcile, stop, kill-switch, loss-limit, credential, data-quality, mode, or risk gates. CLI/status smokes should report `mainnet_signed_action=false` and `execution_side_effects=false`.

Safe flow:

1. CryptoTrader creates a structured `TradeIntent` from its strategy/risk engine.
2. FinanceManager ingests it read-only or via a local bridge.
3. User sees signal, risk, stop, evidence, mode, and blockers.
4. User can approve/reject/paper-only in FinanceManager.
5. Approval is written as local audit state only.
6. CryptoTrader re-reads approval and re-runs all hard gates before any execution.
7. CryptoTrader, not the dashboard, performs exchange side effects if live mode is explicitly approved and gates are green.

## Required mode separation

Maintain distinct modes in every intent/card:

- `research`: informational signal only
- `paper`: simulated fill possible, no exchange order
- `approval`: awaiting human decision
- `live-blocked`: live path intentionally unavailable
- `live-preview-ready`: all preview gates green, still not live unless explicitly launched
- `live-active`: autonomous runtime already approved and supervised

## Hyperliquid portfolio boundary

Represent Hyperliquid as a separate trading portfolio/depot in FinanceManager:

- base currency USDC
- margin/leverage/open position fields
- realized/unrealized PnL and funding
- stop/reconcile/kill-switch state
- strategy/source for each position

Do not mix Hyperliquid derivatives exposure into ordinary spot-crypto wallet holdings.

## Approval queue fields

A `TradeIntent` should include:

- strategy id and source engine
- asset/coin, side, order type
- notional/size and risk percent
- entry thesis and blockers cleared
- stop loss / take profit / exit plan
- confidence and horizon
- data quality status
- expected move vs cost
- status and expiry

A `TradeApproval` should include:

- decision: approve/reject/paper-only
- approver and timestamp
- note
- immutable audit id/hash

## Pitfalls

- Do not add `[Buy now]` buttons that call exchange APIs from Vue/FastAPI.
- Do not treat dashboard approval as sufficient for execution; the bot must re-check reconcile, stops, loss limits, kill-switch, API health, credential consistency, and mode flags.
- Do not require manual approval for every future mini-trade if the user has explicitly chosen autonomous risk-bounded mode; instead build hard limits, watchdogs, and daily reporting.
- Do not present paper or research signals as live-ready evidence.