Jakeschincariol/trader-skill / trader-risk
trader-risk
VerifiedRisk Manager. Checks every proposed order against your limits before it can reach the broker and blocks anything over them: blocked tickers, max order size, minimum order, max position percent after the fill, the cash buffer, margin, short sales, options and crypto (off unless allowed), malformed orders, duplicates and a daily order limit. Prints PASS or BLOCK with the reason for each order and records the verdicts so trader-broker only shows an order that passed. Use when the user says "check my orders", "is this safe", "risk check", "does this break my rules", "can I place this", or before /trader-broker, always.
check.py
View on GitHub#!/usr/bin/env python3
"""Pre-trade risk check for trader-risk. Standard library only, no network.
Reads the proposed orders (trader/orders.json) and checks every one against
your rules (trader/config.json), your account (trader/portfolio.json) and
prices (trader/prices.json). Each order gets PASS or BLOCK with the reasons.
Orders are checked in file order as if each PASS had filled, so five buys
that are fine one by one but break the cash buffer together are caught.
python3 check.py # the trader/ files, writes trader/state/risk.json
python3 check.py --orders trader/orders.json --json
python3 check.py --no-write # check without recording the verdicts
What blocks an order:
format missing symbol or side, both or neither of qty / notional,
notional on anything but a market day order (Alpaca's rule),
a limit order without a limit price, unknown type
asset options (OCC symbols) unless "allow_options": true; crypto
and anything that is not a stock or ETF
blocked a ticker on your "blocked" list
size under min_order_usd, over max_order_usd
position the stock would be over max_position_pct of the account
cash the buy would dip into your cash buffer, or need margin
short selling more than you hold, unless "allow_short": true
duplicate the same symbol and side twice in this batch, or already
placed today (trader/state/broker.json)
daily limit more than max_orders_per_day orders placed today
Exit code 0 when every order passes, 1 when any order is blocked.
The verdicts go to trader/state/risk.json with a fingerprint of each order,
so trader-broker only shows an order as ready if THIS exact order passed today.
"""
import argparse
import datetime
import hashlib
import json
import os
import re
import sys
DEFAULTS = {
"budget": None, "cash_buffer_pct": 10, "max_position_pct": 25, "max_order_usd": 2000,
"min_order_usd": 5, "max_orders_per_day": 10, "paper": True, "blocked": [],
"allow_options": False, "allow_margin": False, "allow_short": False,
}
ALPACA_FIELDS = ("symbol", "side", "qty", "notional", "type", "time_in_force", "limit_price",
"stop_price", "trail_price", "trail_percent", "extended_hours", "client_order_id",
"order_class", "take_profit_limit_price", "stop_loss_stop_price",
"stop_loss_limit_price", "advanced_instructions")
TYPES = {"market", "limit", "stop", "stop_limit", "trailing_stop"}
TIFS = {"day", "gtc", "opg", "cls", "ioc", "fok"}
OCC = re.compile(r"^[A-Z]{1,6}\d{6}[CP]\d{8}$")
TICKER = re.compile(r"^[A-Z]{1,5}([.\-][A-Z]{1,2})?$")
CENT = 0.005
class RiskError(Exception):
pass
def read_json(path, what, required=True):
if not path or not os.path.exists(path):
if required:
raise RiskError("no %s at %s" % (what, path))
return None
try:
with open(path, encoding="utf-8") as fh:
return json.load(fh)
except json.JSONDecodeError as e:
raise RiskError("%s is not valid JSON: %s" % (path, e))
def fingerprint(order):
"""Same function in trader-broker/ticket.py: the exact order that was checked."""
core = {k: order[k] for k in ALPACA_FIELDS if k in order and order[k] is not None}
blob = json.dumps(core, sort_keys=True, separators=(",", ":"))
return hashlib.sha256(blob.encode("utf-8")).hexdigest()[:16]
def _f(x):
try:
return float(x)
except (TypeError, ValueError):
return None
def money(x):
return "$" + "{:,.2f}".format(float(x)).replace(".00", "")
def account(cfg, portfolio, prices):
"""Starting account: cash and position values. No portfolio = a fresh
account funded with the budget."""
warnings = []
if portfolio is None:
budget = _f(cfg.get("budget"))
if not budget:
raise RiskError("no trader/portfolio.json and no budget in the config: "
"nothing to check the orders against")
return {"cash": budget, "shares": {}, "values": {}}, warnings
cash = _f(portfolio.get("cash"))
if cash is None:
raise RiskError("portfolio.json needs a \"cash\" number")
shares, values = {}, {}
for p in portfolio.get("positions", []):
t = str(p.get("ticker") or p.get("symbol") or "").upper()
if not t:
continue
n = _f(p.get("shares", p.get("qty")))
if n is None:
n = sum(_f(l.get("shares")) or 0 for l in p.get("lots", []))
shares[t] = shares.get(t, 0) + n
if prices.get(t):
values[t] = shares[t] * prices[t]
else:
basis = sum(_f(l.get("cost")) or 0 for l in p.get("lots", []))
values[t] = basis
warnings.append("no price for %s: valued at its cost basis %s" % (t, money(basis)))
return {"cash": cash, "shares": shares, "values": values}, warnings
def placed_today(state, today):
"""Orders recorded as placed today by trader-broker."""
out = []
for rec in (state or {}).get("orders", []):
if rec.get("status") == "placed" and str(rec.get("date") or str(rec.get("at", ""))[:10]) == today:
out.append(rec)
return out
def check(orders, cfg, portfolio=None, prices=None, state=None, today=None):
"""Pure function. Returns {"results": [...], "pass": n, "block": n, "warnings": [...]}."""
c = dict(DEFAULTS)
c.update(cfg or {})
prices = {str(k).upper(): float(v) for k, v in (prices or {}).items() if _f(v)}
today = today or datetime.date.today().isoformat()
acct, top_warn = account(c, portfolio, prices)
blocked = {str(b).upper() for b in c.get("blocked") or []}
done_today = placed_today(state, today)
count_today = len(done_today)
placed_keys = {(str(r.get("symbol", "")).upper(), r.get("side")) for r in done_today}
seen = set()
results = []
if not c.get("paper", True):
top_warn.append("LIVE account (\"paper\": false): these orders use real money")
for i, o in enumerate(orders, 1):
reasons, warns = [], []
sym = str(o.get("symbol", "")).strip().upper()
side = str(o.get("side", "")).strip().lower()
typ = str(o.get("type", "market")).strip().lower()
tif = str(o.get("time_in_force", "day")).strip().lower()
qty, notional = o.get("qty"), o.get("notional")
value = None
# format
if not sym:
reasons.append("format: no symbol")
if side not in ("buy", "sell"):
reasons.append("format: side must be buy or sell, got %r" % o.get("side"))
if (qty is None) == (notional is None):
reasons.append("format: give exactly one of qty or notional")
for k in ("qty", "notional", "limit_price", "stop_price"):
if o.get(k) is not None:
v = _f(o.get(k))
if v is None or v <= 0:
reasons.append("format: %s must be a positive number, got %r" % (k, o.get(k)))
elif not isinstance(o.get(k), str):
warns.append("send %s as a string (\"%s\"), the way place_stock_order types it"
% (k, o.get(k)))
if typ not in TYPES:
reasons.append("format: unknown order type %r" % typ)
if tif not in TIFS:
reasons.append("format: unknown time_in_force %r" % tif)
if notional is not None and (typ != "market" or tif != "day"):
reasons.append("format: a notional (dollar) order must be a market order with time_in_force day")
if typ in ("limit", "stop_limit") and o.get("limit_price") is None:
reasons.append("format: a %s order needs a limit_price" % typ)
if typ in ("stop", "stop_limit") and o.get("stop_price") is None:
reasons.append("format: a %s order needs a stop_price" % typ)
if o.get("extended_hours") and not (typ == "limit" and tif == "day"):
reasons.append("format: extended hours needs a limit order with time_in_force day")
if o.get("order_class") or o.get("advanced_instructions"):
warns.append("advanced order (%s): check every leg before you say yes"
% (o.get("order_class") or "advanced_instructions"))
# asset
if sym and OCC.match(sym.replace(" ", "")):
if not c.get("allow_options"):
reasons.append("asset: %s is an option contract; options are off "
"(\"allow_options\": false)" % sym)
else:
warns.append("option order: options can lose 100%% of what you pay")
elif sym and ("/" in sym or not TICKER.match(sym)):
reasons.append("asset: %s does not look like a US stock or ETF ticker; "
"this pack trades stocks and ETFs only" % sym)
# blocked list
if sym in blocked:
reasons.append("blocked: %s is on your blocked list" % sym)
# dollar value of the order
ref = None
if typ in ("limit", "stop_limit"):
ref = _f(o.get("limit_price"))
elif typ == "stop":
ref = _f(o.get("stop_price"))
if ref is None:
ref = prices.get(sym)
if notional is not None and _f(notional):
value = _f(notional)
elif qty is not None and _f(qty):
if ref:
value = _f(qty) * ref
else:
reasons.append("price: no price for %s to size a %s-share order; add it to "
"trader/prices.json (trader-alerts: alerts.py quote %s --write)"
% (sym, qty, sym))
if value is not None:
if value < float(c.get("min_order_usd") or 0) - CENT:
reasons.append("size: %s is under your %s minimum order"
% (money(value), money(c["min_order_usd"])))
if c.get("max_order_usd") and value > float(c["max_order_usd"]) + CENT:
reasons.append("size: %s is over your %s max order"
% (money(value), money(c["max_order_usd"])))
# account effects, simulated in order
cash = acct["cash"]
held = acct["shares"].get(sym, 0.0)
held_value = acct["values"].get(sym, 0.0)
total = cash + sum(acct["values"].values())
buffer_usd = total * float(c.get("cash_buffer_pct") or 0) / 100.0
if value is not None and side == "buy":
after_cash = cash - value
if after_cash < -CENT and not c.get("allow_margin"):
reasons.append("cash: needs %s but only %s cash; that would be margin (borrowed money)"
% (money(value), money(cash)))
elif after_cash < buffer_usd - CENT:
reasons.append("cash: leaves %s cash, under your %s%% buffer of %s"
% (money(max(after_cash, 0)), _pct(c["cash_buffer_pct"]), money(buffer_usd)))
pos_after = held_value + value
limit = total * float(c.get("max_position_pct") or 100) / 100.0
if total > 0 and pos_after > limit + CENT:
reasons.append("position: %s would be %s, %.1f%% of the %s account, over your %s%% cap"
% (sym, money(pos_after), 100.0 * pos_after / total, money(total),
_pct(c["max_position_pct"])))
if side == "sell" and sym:
if qty is not None and _f(qty):
over = _f(qty) > held + 1e-9
elif value is not None:
over = value > held_value + CENT
else:
over = held <= 0
if over and not c.get("allow_short"):
reasons.append("short: selling more %s than you hold (%s shares); short selling is off"
% (sym, _num(held)))
# duplicates and the daily limit
key = (sym, side)
if key in seen:
reasons.append("duplicate: a second %s %s in this batch" % (side, sym))
if key in placed_keys:
reasons.append("duplicate: a %s %s was already placed today" % (side, sym))
passed_so_far = sum(1 for r in results if r["verdict"] == "PASS")
cap_n = int(c.get("max_orders_per_day") or 0)
if cap_n and count_today + passed_so_far >= cap_n:
reasons.append("daily limit: %d placed today plus %d passed earlier in this batch, "
"your limit is %d a day" % (count_today, passed_so_far, cap_n))
seen.add(key)
verdict = "BLOCK" if reasons else "PASS"
if verdict == "PASS" and value is not None:
if side == "buy":
acct["cash"] -= value
acct["values"][sym] = acct["values"].get(sym, 0.0) + value
if ref:
acct["shares"][sym] = held + value / ref
else:
acct["cash"] += value
acct["values"][sym] = max(acct["values"].get(sym, 0.0) - value, 0.0)
if qty is not None:
acct["shares"][sym] = held - _f(qty)
elif ref:
acct["shares"][sym] = held - value / ref
results.append({
"index": i, "symbol": sym, "side": side,
"amount": money(_f(notional) or 0) if notional is not None else ("%s shares" % qty),
"value_usd": round(value, 2) if value is not None else None,
"fingerprint": fingerprint(o), "verdict": verdict,
"reasons": reasons, "warnings": warns,
})
return {
"date": today,
"paper": bool(c.get("paper", True)),
"results": results,
"pass": sum(1 for r in results if r["verdict"] == "PASS"),
"block": sum(1 for r in results if r["verdict"] == "BLOCK"),
"warnings": top_warn,
"cash_after": round(acct["cash"], 2),
}
def _pct(x):
x = float(x)
return str(int(x)) if x == int(x) else ("%.2f" % x)
def _num(x):
x = float(x)
return str(int(x)) if x == int(x) else ("%.4f" % x).rstrip("0")
def report(res):
lines = []
for w in res["warnings"]:
lines.append("WARNING: " + w)
if res["warnings"]:
lines.append("")
for r in res["results"]:
lines.append("%-5s #%d %s %s %s" % (r["verdict"], r["index"], r["side"], r["symbol"], r["amount"]))
for x in r["reasons"]:
lines.append(" - " + x)
for x in r["warnings"]:
lines.append(" ~ " + x)
lines.append("")
lines.append("%d passed, %d blocked. Cash after the passed orders: %s (%s account)."
% (res["pass"], res["block"], money(res["cash_after"]), "paper" if res["paper"] else "LIVE"))
if res["block"]:
lines.append("Blocked orders do not go to the broker. Fix the order or your rules, then check again.")
else:
lines.append("Every order passed. trader-broker still asks you yes or no for each one.")
lines.append("Education and tooling, not financial advice.")
return "\n".join(lines)
def main(argv=None):
ap = argparse.ArgumentParser(description="Check proposed orders against your limits (trader-risk).")
ap.add_argument("--orders", default="trader/orders.json")
ap.add_argument("--config", default="trader/config.json")
ap.add_argument("--portfolio", default="trader/portfolio.json",
help="your account; if missing, a fresh account funded with the budget")
ap.add_argument("--prices", default="trader/prices.json")
ap.add_argument("--state", default="trader/state/broker.json", help="what trader-broker placed today")
ap.add_argument("--today", help="YYYY-MM-DD (default: today)")
ap.add_argument("--out", default="trader/state/risk.json", help="where the verdicts are recorded")
ap.add_argument("--no-write", action="store_true", help="do not record the verdicts")
ap.add_argument("--json", action="store_true")
a = ap.parse_args(argv)
try:
doc = read_json(a.orders, "orders file (run trader-budget or trader-rebalance first)")
orders = doc.get("orders", doc) if isinstance(doc, dict) else doc
if not isinstance(orders, list) or not orders:
raise RiskError("no orders in %s" % a.orders)
cfg = read_json(a.config, "config", required=False) or {}
portfolio = read_json(a.portfolio, "portfolio", required=False)
pdoc = read_json(a.prices, "prices", required=False) or {}
prices = pdoc.get("prices", pdoc) if isinstance(pdoc, dict) else {}
state = read_json(a.state, "broker state", required=False)
res = check(orders, cfg, portfolio, prices, state, a.today)
if pdoc.get("as_of"):
res["prices_as_of"] = pdoc["as_of"]
if not a.no_write:
d = os.path.dirname(a.out)
if d:
os.makedirs(d, exist_ok=True)
rec = dict(res)
rec["checked_at"] = datetime.datetime.now().replace(microsecond=0).isoformat()
rec["orders_file"] = a.orders
with open(a.out, "w", encoding="utf-8") as fh:
json.dump(rec, fh, indent=2)
fh.write("\n")
except RiskError as e:
print("check.py: %s" % e, file=sys.stderr)
return 1
print(json.dumps(res, indent=2) if a.json else report(res))
return 1 if res["block"] else 0
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |