# exec-mcp

Execution MCP for Trader27.

This service is the order-and-account layer of the stack. It owns exchange access, account metadata, balances, fee schedules, precision/step rules, and the actual order lifecycle.

## Role in the stack

- **Crypto MCP**: market data, indicators, technical context
- **News MCP**: sentiment, events, background context
- **Trader / Strategy client**: strategy logic, UI, internal loop, decision making
- **Exec MCP**: authenticated execution, account routing, order placement, query, cancel, metadata

## What this server should do

- List configured accounts, optionally filtered by exchange
- Expose account metadata, balances, commissions, and exchange-specific limits
- Expose read-only market/currency discovery helpers
- Keep the public MCP surface read-only for discovery, with execution tools for orders
- Use the dashboard for adding, updating, enabling, disabling, and deleting accounts
- Store credentials separately from account metadata
- Record balance snapshots over time internally
- Support multiple exchanges and subaccounts
- Keep credentials isolated from strategy and UI layers
- Provide a stable API for strategy engines and operator UIs

## Project goals

- FastMCP-based service
- Clear separation from strategy logic
- Safe credential handling
- Exchange-agnostic account abstraction
- Paper-trading friendly architecture
- Observability, auditability, and restart safety

## Current status

This folder is the starting scaffold. The architecture and intent are captured in `trader27.md` and will be expanded into:

- server contract
- account/exchange adapters
- execution state model
- logging and audit trail
- test harness / paper trading mode

## Dashboard shape

- `GET /` shows a minimal landing page with links
- `GET /dashboard` shows the HTML dashboard
- the dashboard creates, updates, and deletes accounts with forms
- the add-account section starts collapsed, since it is only used occasionally
- the visible account reference is the exchange-side identifier, for example the Bitstamp numeric user id
- the internal database primary key is separate and hidden from the web UI
- the `name` field is the arbitrary label you choose for that account

## Notes

This project is intended to stay lightweight at the FastMCP boundary and push exchange-specific details into adapter modules.

## Bitstamp reference docs

A local copy of the Bitstamp WebSocket API docs lives at `bitstamp_websocket_api.md` in the project root. Use that as the primary reference for live market data, private streams, and reconnect behavior.

The older REST reference file is still present too, but the websocket doc is the one to follow for the next integration step.

## Bitstamp metadata cache

The app now persists Bitstamp metadata tables and refreshes them on startup, then once a day in the background:
- `GET /api/v2/currencies/`
- `GET /api/v2/markets/`

These are stored in SQLite for reuse across restarts.

## Bitstamp websocket prices

`exec-mcp` no longer owns public live-price streaming. Price lookup is expected to come from `crypto` MCP's cached `get_price` path when needed.

`exec-mcp` keeps only the Bitstamp private websocket needed for order state updates.