# Guardian MCP

Guardian MCP is a policy-bounded AI trading gateway for Alpaca paper trading. AI agents can propose stock, ETF, and crypto trades, but deterministic rules decide whether the trade is blocked, approved for human review, or submitted to Alpaca paper trading.

## Why this exists

Most AI trading demos give the model too much authority. Guardian separates the workflow:

```text
AI proposes a TradeIntent
Guardian validates the intent
Policy engine approves or blocks
Alpaca paper trading receives only approved low-risk orders
Every decision becomes an audit receipt
```

## Current scope

- US equities and ETFs
- Crypto pairs on Alpaca, including `BTC/USD`, `ETH/USD`, and `SOL/USD`
- Paper trading only
- Mock Alpaca execution when API keys are missing
- Local JSON audit log for the first demo
- Official Alpaca Skills alignment for paper-only safety gates

## Getting started

```bash
npm install
npm run dev
```

Open `http://localhost:3000`.

To connect Alpaca paper trading, create `.env.local`:

```bash
ALPACA_API_KEY=your_key
ALPACA_SECRET_KEY=your_secret
ALPACA_PAPER_BASE_URL=https://paper-api.alpaca.markets
ALPACA_PAPER_TRADE=true
TELEGRAM_BOT_TOKEN=your_botfather_token
```

Alpaca's official skills also use `APCA_API_KEY_ID` and `APCA_API_SECRET_KEY`; Guardian supports those names too.

Do not paste API keys into chat or commit them. Guardian blocks live Alpaca configuration and only supports paper trading.

## Demo flow

1. Pick a mock AI trade proposal.
2. Run the guard.
3. See allowed trades submitted to mock or real Alpaca paper trading.
4. See blocked trades recorded with exact policy reasons.

## Telegram bot

Guardian can also run as a Telegram bot for the chat-first demo:

```bash
npm run telegram
```

Bot commands:

```text
/account
/portfolio
/policy
/preview buy SOL/USD 50
/confirm guardian-tg-...
```

The bot uses long polling, so it should run on your Google VM, not Vercel. It never submits silently: `/preview` creates the paper order preview and `/confirm` is required before Guardian can submit to Alpaca paper trading.

To run beside another process on the VM:

```bash
pm2 start npm --name guardian-telegram -- run telegram
pm2 save
```

## Policy defaults

- Paper-only mode
- Max trade notional: `$500`
- Human approval above: `$100`
- Max daily loss: `2%`
- Max position exposure: `15%`
- Max crypto trade notional: `$100`
- Max crypto portfolio exposure: `20%`
- Crypto cooldown: `15 minutes`

## Hackathon pitch

Guardian MCP lets AI trading agents operate through Alpaca without giving the model unchecked control over an account. The model can research and propose trades; Guardian enforces deterministic user policy before execution and records every decision in a replayable audit trail.

## Alpaca Skills

This repo is aligned with Alpaca's official agent skills. See `docs/alpaca-skills.md` for the paper-trading guardrails and the remaining Alpaca-specific work.

## MCP Server

Guardian includes its own MCP server:

```bash
npm run mcp
```

See `docs/mcp.md` for tool names and MCP client configuration.