# AGENTS.md

## Scope

`exec-mcp` is the execution layer for Trader27. It owns exchange access, account metadata, balances, fees, market metadata, order placement, order lookup, and cancel flows.

## How To Run

- Start the service with `./run.sh`
- Restart with `./restart.sh`
- Stop listeners with `./killserver.sh`
- Run tests with `./tests.sh`
- `GET /health` is the runtime health probe used by Docker

`run.sh` uses `uvicorn app:app` and will source `.venv/bin/activate` if present.

## Code Boundaries

- Keep secrets in `account_secrets`; never expose them through dashboard or MCP responses.
- Keep account metadata and order lifecycle logic in `repo.py`, `services_bitstamp.py`, and `services_orders.py`.
- Keep Bitstamp-specific client behavior in `bitstamp.py` and websocket handling in `bitstamp_private_ws.py`.
- Keep schema changes compatible with the non-destructive bootstrap in `storage.py`.

## Runtime Contracts

- `venue_account_ref` is the exchange-side account reference shown in the dashboard.
- `client_id` is optional on orders, stored locally, and used to filter open orders and recover tracked state.
- Bitstamp client instances are cached per account, and nonce generation must remain monotonic per credential scope.
- Background tasks refresh Bitstamp metadata and EUR/USD data, and the private websocket updates local order records.
- Public discovery tools should stay read-only; order placement and cancel paths are the execution surface.
- Reporting tools are snapshot-only: recent trades default to `filled`, support `cancelled` and `all`, and balance reporting reads stored `balance_snapshots`.

## Editing Rules

- Prefer small, targeted changes.
- Do not invent new architecture or strategy semantics.
- When changing runtime behavior, update the relevant tests and docs in the same patch.
- If a test or cleanup path depends on the local SQLite DB, use a temp DB in tests instead of mutating shared state.
- For Docker runs, keep `/app/data` mounted so the SQLite file survives restarts.

## Files To Read First

- `README.md`
- `PROJECT.md`
- `src/exec_mcp/server.py`
- `src/exec_mcp/services_orders.py`
- `src/exec_mcp/services_bitstamp.py`
- `src/exec_mcp/bitstamp.py`
- `src/exec_mcp/storage.py`