Metadata-Version: 2.4
Name: alphameta
Version: 2.9.1
Summary: IBKR trading + SEC research API gateway
Home-page: https://github.com/intelliscale/alphameta
Author: GAO KE
Author-email: gaoke@intelliscale.com
License: Apache-2.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.7
Requires-Dist: httpx>=0.28.1
Requires-Dist: loguru>=0.7.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: orjson>=3.6.7
Requires-Dist: pandas>=2.0.3
Requires-Dist: python-dateutil>=2.9.0
Requires-Dist: fastapi>=0.128.7
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: uvicorn>=0.40.0
Requires-Dist: ib_async>=2.0.1
Requires-Dist: prompt_toolkit>=3.0.29
Requires-Dist: questionary>=2.0.1
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: aiohttp>=3.7.4
Requires-Dist: websockets>=16.0
Requires-Dist: arrow>=1.1.0
Requires-Dist: cachetools>=6.2.0
Requires-Dist: pandas-market-calendars>=4.1.4
Requires-Dist: pytz>=2020.1
Requires-Dist: whenever>=0.6.9
Requires-Dist: beautifulsoup4>=4.11.1
Requires-Dist: jinja2>3.1.0
Requires-Dist: lark>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: diskcache>=5.6.3
Requires-Dist: ulid-py>=1.1.0
Requires-Dist: prettyprinter>=0.18.0
Requires-Dist: setproctitle>=1.2.2
Requires-Dist: edgartools>=5.30.2
Requires-Dist: yfinance>=1.2.0
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# AlphaMeta

[![PyPI - Version](https://img.shields.io/pypi/v/alphameta?color=orange)](https://pypi.org/project/alphameta/)
[![Python Version](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue)]()
[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue)]()
[![Downloads](https://static.pepy.tech/badge/alphameta)](https://pepy.tech/project/alphameta)
[![WeChat](https://img.shields.io/badge/WeChat-Group-C5EAB4?style=flat&logo=wechat&logoColor=white)](https://github.com/intelliscale/.github)

AlphaMeta is an algorithmic trading platform that unifies five surfaces in a single process:

- **REST API gateway** — 80+ commands for market data, SEC EDGAR fundamentals, options analytics, trading, portfolio, automation, and watchlists, served over HTTP by a FastAPI gateway and callable via `curl` or any HTTP client.
- **Real-time streaming** — a WebSocket endpoint (`/ws/stream`) broadcasting live ticks, quotes, and 1m–1h bars at tick rate, plus custom formula streams.
- **Backtesting engine** — Rust-based strategy backtests with QuantStats/Plotly reports, available via the `alphameta backtest` CLI, REST API, Jupyter magics, and the web UI.
- **Live strategy hosting** — hot-reloadable strategy files managed over REST, running against live market data.
- **Embedded MCP server** — an MCP tool layer (`/mcp`) exposing the full command surface to AI agents: market data, fundamentals, portfolio, and live trading. Trading is opt-in and gated behind a three-step confirm-token flow with risk limits and audit logging.
- **AI agent harness** — a built-in chat server that runs agents locally and plugs into any LLM, orchestrating MCP tools end-to-end from natural language.

Broker backends: **IBKR** (stocks, options, futures, crypto) and **QMT** (China A-shares). Also includes SEC EDGAR research commands — filing listing, 13F investors, insider trades, XBRL financial statements and segment data.

## Quick start

```bash
uv tool install alphameta    # or: pip install alphameta
```

Get a **free API key** at [alphameta.app](https://alphameta.app), then create `~/.alphameta/.env`:

```ini
# API Key (Required) — get one free at https://alphameta.app
ALPHAMETA_API_KEY=am-xxx

# IBKR Account ID (Required for trading)
ALPHAMETA_IBKR_ACCOUNT_ID=U1234567

# IBKR Gateway connection
ALPHAMETA_IBKR_HOST=127.0.0.1
ALPHAMETA_IBKR_PORT=4001
ALPHAMETA_IBKR_CLIENT_ID=0

# Timezone (default: US/Eastern)
# ALPHAMETA_TIMEZONE=Asia/Shanghai
```

Start the server (choose a broker backend: `ibkr` or `qmt`):

```bash
alphameta --broker ibkr
```

Open the web UI in your browser (server must be running first):

```bash
alphameta web
```

The API serves at `http://127.0.0.1:18080` by default:

```bash
# Live quotes
curl -X POST "http://127.0.0.1:18080/api/v1/execute" \
  -H "Content-Type: application/json" \
  -d '{"cmd": "quote AAPL"}'

# SEC research (no IBKR needed)
curl -X POST "http://127.0.0.1:18080/api/v1/execute" \
  -H "Content-Type: application/json" \
  -d '{"cmd": "filings AAPL 10-K"}'
```

## Real-time streaming

Connect to the WebSocket endpoint for push-based market data instead of polling:

```
ws://127.0.0.1:18080/ws/stream
```

The streamer broadcasts live ticks and quotes (throttled to tick rate), real-time bars (1m / 5m / 15m / 30m / 1h), and evaluated formula streams, with heartbeat and connection-state events.

## Backtesting & strategies

Run backtests from the CLI with QuantStats or Plotly reports:

```bash
alphameta backtest --strategy my_strategy.py --symbol SPY --report quantstats --benchmark SPY
```

The same engine is available over REST (`/api/v1/backtest`, `/history`, `/{id}/report`), in Jupyter via `alphameta.research` (`get_pricing` / `run_backtest`) and IPython magics, and in the web UI backtest workbench with equity charts and run history.

Live strategies are hot-reloadable Python files in `~/.alphameta/strategies`, managed over REST (`/api/v1/strategies` — list / start / stop / reload / logs).

## MCP server (AI agents)

An embedded MCP server (streamable HTTP) is mounted at `/mcp` and enabled by default. It exposes the full command surface — quote, kline, chain, positions, balance, orders, gex/dex, maxpain, calendar, news, SEC filings, and more — to any MCP-compatible agent.

Trading tools are available but opt-in (`ALPHAMETA_MCP_TRADING_ENABLED=true`, default off); when enabled, every trade goes through a three-step confirm-token flow: `trade_preview` → `trade_confirm` → `trade_transmit`, with risk limits, symbol blacklists, and an audit log.

The built-in chat server doubles as a local agent harness: it can plug into any LLM provider and orchestrates these MCP tools end-to-end from natural language.

## AI Agent Skills

[alphameta-skills](https://github.com/intelliscale/alphameta-skills) provides agent skills for AI coding assistants (Claude Code, Codex, Cursor, etc.) — use AlphaMeta in natural language for market data, trading, portfolio analysis, and more.

```bash
npx skills add intelliscale/alphameta-skills -g
```

## Features

### Commands by category
| Category | Commands |
|----------|----------|
| Market | `quote`, `add`, `remove` (`rm`), `kline`, `depth`, `chain`, `range`, `info`, `align`, `prequalify`, `oadd` |
| Fundamentals | `financial-report`, `financial-statement`, `financial` (`fin`, `yf`), `sec`, `filings`, `investors`, `insider-trades`, `calc-index`, `consensus`, `earnings`, `fundamental` (`fund`), `news`, `operating`, `calendar` |
| Technicals | `dex`, `gex`, `dge`, `maxpain`, `capital-flow`, `straddle`, `advice`, `reporter` |
| Trading | `buy`, `cancel`, `modify`, `evict`, `fast`, `scale` |
| Portfolio | `positions` (`ls`), `balance`, `orders`, `executions`, `report`, `cash` |
| Automation | `ifthen`, `iflist`, `ifrm`, `ifclear`, `ifgroup`, `auto`, `sched-add`, `sched-list`, `sched-cancel`, `tasklist`, `taskcancel` |
| Watchlist | `qadd`, `qremove`, `qlist`, `qsave`, `qrestore`, `qdelete`, `qclean`, `qsnapshot`, `qloadsnapshot`, `alert` |
| Utilities | `math`, `say`, `expand`, `simulate`, `paper`, `daydumper`, `details`, `alias`, `clear`, `meta`, `qualify`, `reconnect`, `set` |

## Prerequisites

1. **Broker backend** — pick one with `--broker`:
   - `ibkr` — Interactive Brokers (requires IB Gateway or TWS, see below)
   - `qmt` — QMT for China A-shares

2. **Interactive Brokers Account** (for `ibkr`): You need an active IB account

3. **IB Gateway or TWS** (for `ibkr`): Download and install either:
   - [IB Gateway (Stable)](https://www.interactivebrokers.com/en/trading/ibgateway-stable.php) — Recommended for API-only use
   - [IB Gateway (Latest)](https://www.interactivebrokers.com/en/trading/ibgateway-latest.php) — Latest features
   - [Trader Workstation (TWS)](https://www.interactivebrokers.com/en/trading/tws.php) — Full trading platform

4. **API Configuration** (for `ibkr`):
   - Enable API access in TWS/Gateway: `Configure → API → Settings` and check "Enable ActiveX and Socket Clients"
   - Set appropriate port (default: 7497 for TWS, 4001 for Gateway)
   - Add `127.0.0.1` to trusted IPs if connecting locally

## Examples

**Bulk symbol expansion:**
```bash
# Add/remove multiple option strikes at once
curl -X POST "http://127.0.0.1:18080/api/v1/execute" \
  -H "Content-Type: application/json" \
  -d '{"cmd": "add SPY240412{P,C}005{1,2,3}0000"}'

# Remove by row id
curl -X POST "http://127.0.0.1:18080/api/v1/execute" \
  -H "Content-Type: application/json" \
  -d '{"cmd": "remove :{31..37}"}'
```

**Multi-symbol orders:**
```bash
# Buy ~$15k of each symbol
curl -X POST "http://127.0.0.1:18080/api/v1/execute" \
  -H "Content-Type: application/json" \
  -d '{"cmd": "expand buy {META,MSFT,NVDA,AMD,AAPL} $15_000 MID"}'
```

**Flexible order pricing:**
```bash
# By quantity or dollar amount, with bracket orders
curl -X POST "http://127.0.0.1:18080/api/v1/execute" \
  -H "Content-Type: application/json" \
  -d '{"cmd": "buy AAPL 100 AF @ 233.33 ± 10"}'
```

**Conditional triggers:**
```bash
# Execute command when price condition is met
curl -X POST "http://127.0.0.1:18080/api/v1/execute" \
  -H "Content-Type: application/json" \
  -d '{"cmd": "if AAPL last > 300: buy AAPL 100 AF"}'
```

**Backtest a strategy:**
```bash
# QuantStats report against a benchmark
alphameta backtest --strategy my_strategy.py --symbol SPY --report quantstats --benchmark SPY
```

**Account calculator:**
```bash
# Calculate shares buyable on margin, combine with growth projections
curl -X POST "http://127.0.0.1:18080/api/v1/execute" \
  -H "Content-Type: application/json" \
  -d '{"cmd": "(/ :BP3 AAPL)"}'
```

## License

© 2026 Intelliscale Technologies, Inc.
