Python Trading Toolkit

Turn a positions CSV across US, HK and A-share tickers into currency-correct P&L, and get your agent to compute risk and signals in code instead of guessing.

The Problem

Ask an agent to "check my portfolio" and it often quotes a price from memory, mixes up 0700.HK and hk00700, or adds Hong Kong dollars and yuan to US dollars as if they were the same currency. The result looks tidy and is wrong: a Tencent position bought in HKD can show up as the largest holding in the book simply because nobody converted it. Sharpe ratios and RSI readings arrive with no formula and no data behind them, so you cannot check them.

What You Get

• An offline P&L script. scripts/portfolio-analyzer.py reads ticker,shares,cost_basis,current_price and prints total cost, value and P&L, then per-ticker P&L, P&L %, portfolio weight and share of total P&L, sorted by contribution, plus top position, best and worst performer. It needs only pandas and no network.
• Currency safety built in. The script infers HKD from .HK and CNY from .SS/.SZ (or reads a currency column), converts with the rates you pass via --fx, and refuses to add mixed currencies without them; you get per-currency subtotals instead.
• Risk metric recipes. Tested Python for total and annualized return, volatility, Sharpe, Sortino and max drawdown from a daily return series, plus alpha, beta, tracking error and information ratio against a benchmark you choose.
• Technical indicator recipes. SMA 20/50, EMA, RSI 14, MACD and signal line, Bollinger Bands and a volume Z-score, with a signal detector for golden/death crosses, RSI extremes, MACD crosses, band breaks and volume spikes.
• Market data, options and screens. yfinance price history for all three markets, a raw Sina quote helper, a nearest-expiry put/call ratio with volume-over-2x-open-interest flags, a P/E, volume and market-cap screen, and gap alerts.
• A multi-market reference with Yahoo and Sina ticker formats, trading hours, settlement cycles and lot sizes.

Why This Beats Prompting It Yourself

Without instructions, an agent tends to answer market questions from memory and to sum positions without checking currency. This skill tells it to normalize tickers first, settle FX before any combined total, run code for every number, and report the data date, currency and rates used. The P&L script enforces the currency rule mechanically, so the mistake cannot slip through on a busy day. The recipes fix the formula once (252-day annualization, inner-joined dates, explicit risk-free rate), so two runs on the same data agree. The session below is verbatim output of the bundled script run on its demo file, with the FX rates taken from the request.

Example Session

You: Analyze the demo positions CSV in USD (HKD 0.128, CNY 0.138). Where did my P&L come from?

Agent: PORTFOLIO (USD; FX CNY 0.138, HKD 0.128) Cost 67,744.00 | Value 92,817.50 | P&L +25,073.50 (+37.01%)

Ticker Ccy P&L USD P&L% Weight Share NVDA USD +12,750 +94.4% 28.3% 51% TSM USD +4,500 +45.0% 15.6% 18% MSFT USD +4,012 +26.8% 20.5% 16% AAPL USD +2,550 +17.0% 18.9% 10% 0700.HK HKD +768 +8.6% 10.5% 3% GOOGL USD +700 +25.0% 3.8% 3% 600519.SS CNY -207 -8.3% 2.5% -1%

Top position: NVDA (28.3%) Best: NVDA (+94.44%) | Worst: 600519.SS (-8.33%)

Use Cases

• You keep holdings in a spreadsheet across US, HK and A-share accounts and want one P&L in your home currency.
• You want to know which positions actually drove this year's gain before you trim or rebalance.
• You need Sharpe, Sortino and max drawdown for a portfolio from price history, with the formula visible.
• You scan a watchlist each morning for golden crosses, RSI extremes and volume spikes.
• You want a quick put/call ratio and unusual-volume check on a US ticker before placing an options trade.

Known Limitations

The bundled script is offline cost-basis P&L only; it uses the prices and FX rates you give it and shows price P&L, not currency P&L. Risk metrics, indicators, options and screens are recipes the agent runs with network access through yfinance, which can be delayed or rate-limited. It does not compute Greeks, VaR or backtests.

Upgrade to Pro

Python Trading Toolkit Pro adds the decision layer on top of this analysis. It includes portfolio optimization (max Sharpe, min variance, risk parity, Black-Litterman), a walk-forward backtest engine with out-of-sample checks, a risk monitor with VaR, CVaR and correlation, Kelly and fixed-fractional position sizing, and MT5 and Binance broker connectors. https://www.agensi.io/skills/python-trading-toolkit-pro