# RGO Trading API — Python client, CLI & MCP server

A Python toolkit for the **RGO Client API** and **Dealer API** (a trading
order/position system). It ships three layers so you can use it however you
like:

| Layer | Entry point | Use it for |
|-------|-------------|------------|
| **Library** | `rgo_api/` | Import in your own Python code |
| **CLI** | `cli.py` | Explicit commands (`python cli.py positions`) |
| **MCP server** | `mcp_server.py` | **Ask an AI assistant in plain English** (Claude CLI, etc.) |

> ⚠️ **This places REAL trades.** Order placement/update/deletion is gated
> behind a config flag (`RGO_ALLOW_TRADING`) and is **off by default**. Reads
> are always safe. See [Safety](#safety).

---

## Features

- **Dealer reads**: executed deals, pending orders, all positions.
- **Order writes** on both the Client and Dealer APIs: place, update, delete
  (opt-in).
- **Realtime deals** via WebSocket (`DealerApi.ws_stream`).
- **Natural-language access** through the Model Context Protocol (MCP): ask
  *"show my open positions"* and let your AI client call the right tool.
- Typed, validated requests (Pydantic v2), a single shared HTTP layer, and a
  test suite that mocks all network calls (no real trades in CI).

See [`docs/API.md`](docs/API.md) for the full endpoint reference and
[`docs/MCP.md`](docs/MCP.md) for AI-assistant setup.

---

## Requirements

- Python 3.10+
- An RGO account with API access (credentials + your broker's endpoints)

## Install

```bash
git clone https://github.com/bhdhiman/rgo-trading-api.git
cd rgo-trading-api

python -m venv .venv
# Windows:
.venv\Scripts\python -m pip install -r requirements.txt
# macOS/Linux:
# .venv/bin/python -m pip install -r requirements.txt
```

## Configure

```bash
cp .env.example .env      # then edit .env with your real values
```

`.env` is gitignored — your credentials never get committed.

| Variable | Meaning |
|----------|---------|
| `RGO_LICENSE_ID` | Your license id |
| `RGO_DEALER_USERNAME` / `RGO_DEALER_PASSWORD` | Dealer login (for the read JWT) |
| `RGO_API_USERNAME` / `RGO_API_PASSWORD` | Header credentials for order writes |
| `RGO_CLIENT_BASE` | Client API base URL, e.g. `https://api.YOUR_DOMAIN:6017/clientapi` |
| `RGO_DEALER_BASE_READ` | Dealer **read** base URL (e.g. port 9016) |
| `RGO_DEALER_BASE_WRITE` | Dealer **write** base URL (may use a different port, e.g. 6016) |
| `RGO_WS_URL` | Realtime WebSocket URL |
| `RGO_ALLOW_TRADING` | `false` by default — set `true` to enable REAL orders |

---

## Usage — CLI

```bash
# Reads (safe)
python cli.py positions
python cli.py deals
python cli.py orders

# Writes (need RGO_ALLOW_TRADING=true AND --yes)
python cli.py place --api dealer --user <ACCOUNT> --type BuyLimit \
    --side BID --price 1 --volume 1 --current 94000 --symbol GOLDOCT --yes
python cli.py delete --api dealer --position <POSITION_ID> --yes
```

## Usage — library

```python
from rgo_api import DealerApi, load_settings

with DealerApi(load_settings()) as api:
    positions = api.get_positions()
    deals = api.get_deals()
    pending = api.get_pending_orders()
```

## Usage — AI assistant (MCP)

Register the server with your MCP-capable client (e.g. the Claude CLI), then
ask in plain English:

- *"show my open positions"*
- *"list today's deals"*
- *"what orders are pending?"*

Full setup (registration + generic MCP client) is in [`docs/MCP.md`](docs/MCP.md).

---

## Safety

This software can place real financial orders. Guardrails:

- **Credentials live only in `.env`** (gitignored). Nothing is hardcoded.
- **Trading is opt-in.** Place/update/delete refuse to run unless
  `RGO_ALLOW_TRADING=true`; the CLI additionally requires `--yes`.
- **Inputs are validated** (side, order type, positive price/volume) before any
  request is sent.

You are responsible for any orders you place. No warranty — see
[`LICENSE`](LICENSE).

---

## Tests

```bash
python -m pytest --cov=rgo_api
```

All HTTP is mocked with `respx`; tests never contact a live server or place
trades.

## Project structure

```
rgo_api/        # client library
  config.py     # settings from .env
  models.py     # request models + response-envelope parsing
  _http.py      # shared httpx transport
  dealer_api.py # dealer reads + writes + websocket
  client_api.py # client order writes
cli.py          # Typer command-line interface
mcp_server.py   # FastMCP server (AI-assistant tools)
docs/           # API + MCP documentation
tests/          # pytest suite (network mocked)
```

## License

[MIT](LICENSE)