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.

---

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 for the full endpoint reference and docs/MCP.md for AI-assistant setup.

---

Requirements

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

Install

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

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

# 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

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.

---

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.

---

Tests

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