# FinanceManager CryptoTrader approval bridge

Use this reference when building or extending a local finance/trading dashboard that sits above an already-working trading bot/executor.

## Pattern

- Keep the specialist trader/executor as the only execution boundary.
- Dashboard reads runtime state read-only: process status, signal journals, paper positions, scorecards, daily reports.
- Model a separate trading portfolio for derivatives/margin venues such as `Hyperliquid`; do not mix it with spot crypto wallets or long-term holdings.
- Synthesize dashboard `TradeIntent` rows from the trader's existing order-intent/signal concepts when no explicit intent queue exists yet.
- Dashboard decisions (`approve`, `reject`, `paper_only`) are approval/audit records only — never direct exchange orders, signing, risk config edits, or execution toggles.
- The trader must later read approvals and re-check all gates itself before any possible execution.

## Backend shape

Recommended endpoints:

```text
GET  /api/crypto-trader/status
GET  /api/crypto-trader/signals
GET  /api/crypto-trader/scorecard
GET  /api/crypto-trader/hyperliquid-portfolio
GET  /api/crypto-trader/trade-intents
POST /api/crypto-trader/trade-approvals
GET  /api/crypto-trader/snapshot
```

Recommended data objects:

```text
CryptoTraderStatus
HyperliquidPortfolioSnapshot
CryptoTraderSignal
TradeIntent
TradeApprovalRequest
TradeApprovalResponse
CryptoTraderSnapshot
```

Approval response should always carry `execution_allowed = false` until a separate executor-side gate promotes it.

## Runtime-source handling

- Read JSON/JSONL defensively; ignore malformed rows.
- Tail journals rather than ingesting entire runtime histories.
- Use stable intent IDs derived from timestamp + strategy + coin + decision/setup fields.
- Store approval audit logs under the dashboard's runtime directory, not in Git and not in the trader source tree unless explicitly designing a shared runtime protocol.
- Do not print secrets or raw account/order credentials.

## Frontend UX

- Label the page as read-only / approval-audit center, not an order terminal.
- Show prominent safety boundary copy: dashboard approval does not execute.
- Show portfolio KPIs, positions, processes, scorecards, Buy/Hold/Sell signal cards, and Trade Approval Queue.
- Buttons may exist for `Approve`, `Paper only`, `Reject`, but they should call audit endpoints only.
- After a decision, refresh the snapshot so `approval_status` updates.

## Verification checklist

- Unit-test snapshot construction from synthetic runtime files.
- Unit-test approval audit write and status remapping.
- Assert API routes are registered.
- Run backend lint + targeted tests + frontend type/build/tests.
- Smoke-test API with `GET /snapshot`, `GET /trade-intents`, and `POST /trade-approvals` with `confirm=false` first.
- Browser-smoke the dashboard page and check the JS console.
- Commit/push only after local and remote SHAs match.