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:

⚠️ 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.

Related MCP server: alpaca-mcp-server

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.

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