Jakeschincariol/trader-skill / trader-broker
trader-broker
VerifiedOrder Executor. Places APPROVED orders through your brokerage connector, one at a time, and never without your explicit yes. Shows each order as a plain ticket plus the exact JSON for Alpaca's place_stock_order, records your yes word for word, then Claude's own Allow once / Deny card asks again. Covers setting up Alpaca's official MCP server in Claude Desktop (paper trading by default, keys in env vars, never in chat), the Interactive Brokers connector (orders go to your IBKR account for your approval), and setting order tools to "Needs approval". Use when the user says "place the orders", "buy it", "execute", "send it to my broker", "connect Alpaca", "connect Interactive Brokers", "set up paper trading", or after /trader-risk passes.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.3 KB |
| claude_desktop_config.example.json | config | 378 B |
| ticket.py | script | 21.0 KB |
ticket.py
View on GitHub#!/usr/bin/env python3
"""Order tickets and the decision log for trader-broker. Standard library only.
This tool never talks to a broker and never places anything. It does three
things around the one moment that matters, your yes:
show renders each proposed order as a plain-English ticket plus the
exact JSON Claude will send to Alpaca's place_stock_order tool.
An order is READY only if trader-risk passed THIS exact order
today (matched by fingerprint) and nobody has decided on it yet.
approve records your explicit yes for ONE order, with your reply word for
word. It refuses "yes to all", "sure", "ok", a yes that names a
different stock or amount, and any order that is not READY.
decline records a no.
result records what happened after the Allow once / Deny card:
placed (with the broker's order id), denied, or failed.
fill adds a filled order to trader/portfolio.json as a tax lot.
log prints today's decisions.
python3 ticket.py show # every order, READY or not
python3 ticket.py show --index 1 --json # one ticket as JSON
python3 ticket.py approve --index 1 --reply "yes"
python3 ticket.py result --index 1 --status placed --broker-id 61e6...
python3 ticket.py fill --symbol AAPL --side buy --qty 3.6628 --price 341.27
python3 ticket.py log
Everything is written to trader/state/broker.json (append only).
"""
import argparse
import datetime
import hashlib
import json
import os
import re
import sys
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")
STRING_FIELDS = ("qty", "notional", "limit_price", "stop_price", "trail_price", "trail_percent",
"take_profit_limit_price", "stop_loss_stop_price", "stop_loss_limit_price")
TIF_WORDS = {"day": "good for today", "gtc": "good until canceled", "opg": "at the open",
"cls": "at the close", "ioc": "immediate or cancel", "fok": "fill or kill"}
YES_WORDS = ("yes", "y")
BATCH_WORDS = {"all", "every", "everything", "rest", "remaining", "them", "both", "batch", "each"}
DOUBT_WORDS = {"no", "not", "dont", "don't", "wait", "cancel", "stop", "but", "maybe", "later",
"hold", "unless", "if"}
class TicketError(Exception):
pass
# ---------------------------------------------------------------- files
def read_json(path, what, required=True):
if not path or not os.path.exists(path):
if required:
raise TicketError("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 TicketError("%s is not valid JSON: %s" % (path, e))
def write_json(path, data):
d = os.path.dirname(path)
if d:
os.makedirs(d, exist_ok=True)
tmp = path + ".tmp"
with open(tmp, "w", encoding="utf-8") as fh:
json.dump(data, fh, indent=2)
fh.write("\n")
os.replace(tmp, path)
def now_iso():
return datetime.datetime.now().replace(microsecond=0).isoformat()
def rec_day(rec):
"""The trading day a decision belongs to: its "date" (the --today it was made under), else the day of "at"."""
return str(rec.get("date") or str(rec.get("at", ""))[:10])
# ---------------------------------------------------------------- the order
def fingerprint(order):
"""Same function as trader-risk/check.py: identifies the exact order."""
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 _str_num(v):
if isinstance(v, bool):
return v
if isinstance(v, (int, float)):
f = float(v)
return str(int(f)) if f == int(f) else repr(f)
return str(v)
def tool_input(order):
"""The exact arguments for place_stock_order: Alpaca's parameter names,
numbers as strings (its signature types qty and notional as str)."""
out = {}
for k in ALPACA_FIELDS:
if k in order and order[k] is not None:
out[k] = _str_num(order[k]) if k in STRING_FIELDS else order[k]
return out
def _money(v):
f = float(v)
s = "{:,.2f}".format(f)
return "$" + (s[:-3] if s.endswith(".00") else s)
def plain(order):
"""BUY $1,250 of AAPL, market order, good for today"""
side = str(order.get("side", "")).upper()
sym = order.get("symbol", "?")
if order.get("notional") is not None:
what = "%s of %s" % (_money(order["notional"]), sym)
else:
q = _str_num(order.get("qty"))
what = "%s share%s of %s" % (q, "" if q == "1" else "s", sym)
typ = str(order.get("type", "market"))
if typ == "limit":
how = "limit order at %s" % _money(order.get("limit_price"))
elif typ == "stop":
how = "stop order at %s" % _money(order.get("stop_price"))
elif typ == "stop_limit":
how = "stop %s, limit %s" % (_money(order.get("stop_price")), _money(order.get("limit_price")))
else:
how = "%s order" % typ.replace("_", " ")
tif = TIF_WORDS.get(str(order.get("time_in_force", "day")), order.get("time_in_force"))
return "%s %s, %s, %s" % (side, what, how, tif)
def amount_numbers(order):
nums = []
for k in ("notional", "qty", "limit_price"):
if order.get(k) is not None:
try:
nums.append(float(order[k]))
except (TypeError, ValueError):
pass
return nums
def parse_yes(reply, order, batch_symbols=()):
"""Is this reply an explicit yes for THIS one order? Returns (ok, why)."""
raw = (reply or "").strip()
if not raw:
return False, "the reply is empty"
if "?" in raw:
return False, "the reply is a question, not a yes"
words = re.findall(r"[a-z']+", raw.lower())
if not words or words[0] not in YES_WORDS:
return False, "only a reply that starts with \"yes\" counts (not ok, sure, go, do it)"
if BATCH_WORDS & set(words):
return False, "a yes covers one order at a time, not a batch"
if DOUBT_WORDS & set(words[1:]):
return False, "the reply has a condition or a doubt in it; ask again"
sym = str(order.get("symbol", "")).upper()
tokens = set(re.findall(r"[A-Z][A-Z.\-]{0,6}", raw.upper()))
others = {s.upper() for s in batch_symbols} - {sym}
named = tokens & others
if named:
return False, "the reply names %s, but this order is for %s" % (", ".join(sorted(named)), sym)
nums = [float(n.replace(",", "")) for n in re.findall(r"\d[\d,]*(?:\.\d+)?", raw)]
if nums:
want = amount_numbers(order)
if not any(abs(n - w) < 0.005 for n in nums for w in want):
return False, "the reply says %s, but this order is %s" % (
", ".join(_str_num(n) for n in nums), plain(order))
return True, "explicit yes for %s" % plain(order)
# ---------------------------------------------------------------- state
def load_state(path):
return read_json(path, "broker state", required=False) or {"orders": []}
def latest(state, fp, today):
"""The latest decision recorded today for this fingerprint, or None."""
found = None
for rec in state.get("orders", []):
if rec.get("fingerprint") == fp and rec_day(rec) == today:
found = rec
return found
def risk_verdict(risk, fp, today):
if not risk:
return None, "trader-risk has not checked these orders (run check.py)"
if risk.get("date") != today:
return None, "the risk check is from %s, not today; run check.py again" % risk.get("date")
for r in risk.get("results", []):
if r.get("fingerprint") == fp:
return r, None
return None, "this exact order was not in the last risk check (it changed or is new); run check.py again"
def status_of(order, risk, state, today):
"""(ready, label, risk_result)"""
fp = fingerprint(order)
rv, why = risk_verdict(risk, fp, today)
if rv is None:
return False, "NOT READY: " + why, None
if rv.get("verdict") != "PASS":
return False, "BLOCKED by trader-risk: " + "; ".join(rv.get("reasons", [])), rv
rec = latest(state, fp, today)
if rec:
st = rec.get("status")
if st == "approved":
return False, "APPROVED by you at %s, waiting for the place_stock_order call" % rec.get("at"), rv
return False, "DONE: %s at %s" % (st, rec.get("at")), rv
return True, "READY: trader-risk PASS, waiting for your yes", rv
# ---------------------------------------------------------------- rendering
def render(order, idx, total, cfg, risk, state, today):
ready, label, rv = status_of(order, risk, state, today)
broker = str(cfg.get("broker", "alpaca")).lower()
paper = cfg.get("paper", True)
acct = "PAPER account" if paper else "LIVE ACCOUNT, REAL MONEY"
lines = ["ORDER %d of %d, %s, %s" % (idx, total, acct, "Interactive Brokers" if broker == "ibkr" else "Alpaca"),
" " + plain(order)]
if order.get("why"):
lines.append(" why: " + order["why"])
lines.append(" " + label)
for w in (rv or {}).get("warnings", []):
lines.append(" note: " + w)
if broker == "ibkr":
lines.append(" Claude drafts this with the Interactive Brokers connector. IBKR sends it to your")
lines.append(" IBKR account, and it only goes to the market after you approve it there.")
else:
lines.append(" Claude will call place_stock_order with exactly:")
for l in json.dumps(tool_input(order), indent=2).splitlines():
lines.append(" " + l)
if ready:
lines.append(" Reply \"yes\" to place this one order, or \"no\" to skip it.")
if broker != "ibkr":
lines.append(" Claude's own card then asks again: Allow once places it, Deny stops it.")
return "\n".join(lines), ready
def ticket_json(order, idx, cfg, risk, state, today):
ready, label, rv = status_of(order, risk, state, today)
return {"index": idx, "ready": ready, "status": label, "plain": plain(order),
"fingerprint": fingerprint(order), "paper": bool(cfg.get("paper", True)),
"broker": cfg.get("broker", "alpaca"), "tool": "place_stock_order",
"tool_input": tool_input(order), "why": order.get("why", "")}
# ---------------------------------------------------------------- fills -> lots
def apply_fill(portfolio_path, cfg, symbol, side, qty, price, date):
"""Record a filled order in trader/portfolio.json (a lot for a buy, FIFO for a sell)."""
pf = read_json(portfolio_path, "portfolio", required=False)
if pf is None:
budget = cfg.get("budget")
if not budget:
raise TicketError("no %s yet and no budget in the config to start it from" % portfolio_path)
pf = {"cash": float(budget), "positions": []}
symbol = symbol.upper()
qty, price = float(qty), float(price)
cost = round(qty * price, 2)
pos = None
for p in pf.setdefault("positions", []):
if str(p.get("ticker", "")).upper() == symbol:
pos = p
if side == "buy":
if pos is None:
pos = {"ticker": symbol, "shares": 0.0, "lots": []}
pf["positions"].append(pos)
lots = pos.setdefault("lots", [])
lots.append({"id": "%s-%d" % (symbol, len(lots) + 1), "date": date, "shares": qty, "cost": cost})
pos["shares"] = round(float(pos.get("shares", 0)) + qty, 6)
pf["cash"] = round(float(pf.get("cash", 0)) - cost, 2)
else:
if pos is None or float(pos.get("shares", 0)) + 1e-9 < qty:
raise TicketError("cannot record selling %s %s: the portfolio holds %s"
% (qty, symbol, pos.get("shares", 0) if pos else 0))
left = qty
for lot in sorted(pos.get("lots", []), key=lambda l: l.get("date", "")):
if left <= 1e-9:
break
take = min(left, float(lot["shares"]))
per = float(lot["cost"]) / float(lot["shares"]) if float(lot["shares"]) else 0
lot["cost"] = round(float(lot["cost"]) - per * take, 2)
lot["shares"] = round(float(lot["shares"]) - take, 6)
left -= take
pos["lots"] = [l for l in pos.get("lots", []) if float(l["shares"]) > 1e-9]
pos["shares"] = round(float(pos["shares"]) - qty, 6)
if pos["shares"] <= 1e-9:
pf["positions"].remove(pos)
pf["cash"] = round(float(pf.get("cash", 0)) + cost, 2)
write_json(portfolio_path, pf)
return pf
# ---------------------------------------------------------------- commands
def _load(a):
doc = read_json(a.orders, "orders file (run trader-budget, trader-rebalance or trader-tax first)")
orders = doc.get("orders", doc) if isinstance(doc, dict) else doc
if not isinstance(orders, list) or not orders:
raise TicketError("no orders in %s" % a.orders)
cfg = read_json(a.config, "config", required=False) or {}
risk = read_json(a.risk, "risk check", required=False)
state = load_state(a.state)
today = a.today or datetime.date.today().isoformat()
return orders, cfg, risk, state, today
def _pick(orders, index):
if index is None:
raise TicketError("say which order: --index N")
if not 1 <= index <= len(orders):
raise TicketError("there is no order %d (there are %d)" % (index, len(orders)))
return orders[index - 1]
def cmd_show(a):
orders, cfg, risk, state, today = _load(a)
picks = [(a.index, _pick(orders, a.index))] if a.index else list(enumerate(orders, 1))
if a.json:
out = [ticket_json(o, i, cfg, risk, state, today) for i, o in picks]
print(json.dumps(out[0] if a.index else out, indent=2))
return 0 if any(t["ready"] for t in out) else 1
blocks, any_ready = [], False
for i, o in picks:
text, ready = render(o, i, len(orders), cfg, risk, state, today)
blocks.append(text)
any_ready = any_ready or ready
print("\n\n".join(blocks))
print("\nOne order at a time: a yes covers one ticket, never the batch. Education and tooling, "
"not financial advice.")
return 0 if any_ready else 1
def cmd_approve(a):
orders, cfg, risk, state, today = _load(a)
order = _pick(orders, a.index)
ready, label, rv = status_of(order, risk, state, today)
if not ready:
raise TicketError("order %d is not ready: %s" % (a.index, label))
ok, why = parse_yes(a.reply, order, [o.get("symbol", "") for o in orders])
if not ok:
print("Not recorded: %s. Ask the user again with the ticket for order %d." % (why, a.index))
return 1
rec = {"at": now_iso(), "date": today, "index": a.index, "fingerprint": fingerprint(order),
"symbol": str(order.get("symbol", "")).upper(), "side": order.get("side"),
"plain": plain(order), "status": "approved", "reply": a.reply,
"paper": bool(cfg.get("paper", True)), "broker": cfg.get("broker", "alpaca")}
state.setdefault("orders", []).append(rec)
write_json(a.state, state)
print("Recorded your yes for order %d: %s." % (a.index, plain(order)))
if str(cfg.get("broker", "alpaca")).lower() == "ibkr":
print("Now draft it with the Interactive Brokers connector; approve it in your IBKR account.")
else:
print("Now call place_stock_order with exactly:")
print(json.dumps(tool_input(order), indent=2))
print("Claude's card shows Allow once / Deny. Then: ticket.py result --index %d --status "
"placed|denied|failed" % a.index)
return 0
def cmd_decline(a):
orders, cfg, risk, state, today = _load(a)
order = _pick(orders, a.index)
rec = {"at": now_iso(), "date": today, "index": a.index, "fingerprint": fingerprint(order),
"symbol": str(order.get("symbol", "")).upper(), "side": order.get("side"),
"plain": plain(order), "status": "declined", "reply": a.reply or "no"}
state.setdefault("orders", []).append(rec)
write_json(a.state, state)
print("Recorded: you said no to order %d (%s). Nothing was sent." % (a.index, plain(order)))
return 0
def cmd_result(a):
orders, cfg, risk, state, today = _load(a)
order = _pick(orders, a.index)
fp = fingerprint(order)
rec = latest(state, fp, today)
if not rec or rec.get("status") != "approved":
raise TicketError("order %d has no yes recorded today; a result can only follow an approval" % a.index)
new = {"at": now_iso(), "date": today, "index": a.index, "fingerprint": fp, "symbol": rec["symbol"],
"side": rec["side"], "plain": rec["plain"], "status": a.status}
if a.broker_id:
new["broker_order_id"] = a.broker_id
if a.note:
new["note"] = a.note
state["orders"].append(new)
write_json(a.state, state)
print("Recorded order %d as %s." % (a.index, a.status))
if a.status == "placed" and a.filled_qty and a.filled_price:
apply_fill(a.portfolio, cfg, rec["symbol"], rec["side"], a.filled_qty, a.filled_price, today)
print("Added the fill to %s." % a.portfolio)
elif a.status == "placed":
print("When it fills, record it for trader-tax: ticket.py fill --symbol %s --side %s --qty Q --price P"
% (rec["symbol"], rec["side"]))
return 0
def cmd_fill(a):
cfg = read_json(a.config, "config", required=False) or {}
date = a.date or datetime.date.today().isoformat()
pf = apply_fill(a.portfolio, cfg, a.symbol, a.side, a.qty, a.price, date)
print("Recorded %s %s %s at %s on %s. Cash now %s." % (a.side, a.qty, a.symbol.upper(),
_money(a.price), date, _money(pf["cash"])))
return 0
def cmd_log(a):
state = load_state(a.state)
today = a.today or datetime.date.today().isoformat()
rows = [r for r in state.get("orders", []) if a.all or rec_day(r) == today]
if not rows:
print("No decisions recorded%s." % ("" if a.all else " today"))
return 1
for r in rows:
extra = (" id " + r["broker_order_id"]) if r.get("broker_order_id") else ""
reply = (' reply "%s"' % r["reply"]) if r.get("reply") and r["status"] in ("approved", "declined") else ""
print("%s #%s %-9s %s%s%s" % (r.get("at"), r.get("index"), r.get("status"), r.get("plain"), reply, extra))
placed = sum(1 for r in rows if r.get("status") == "placed")
print("%d placed%s." % (placed, "" if a.all else " today"))
return 0
def main(argv=None):
ap = argparse.ArgumentParser(description="Order tickets and your yes (trader-broker). Never places orders.")
sub = ap.add_subparsers(dest="cmd")
def common(p):
p.add_argument("--orders", default="trader/orders.json")
p.add_argument("--config", default="trader/config.json")
p.add_argument("--risk", default="trader/state/risk.json")
p.add_argument("--state", default="trader/state/broker.json")
p.add_argument("--today", help="YYYY-MM-DD (default: today)")
p = sub.add_parser("show", help="render the tickets")
common(p)
p.add_argument("--index", type=int)
p.add_argument("--json", action="store_true")
p = sub.add_parser("approve", help="record the user's explicit yes for one order")
common(p)
p.add_argument("--index", type=int, required=True)
p.add_argument("--reply", required=True, help="the user's reply, word for word")
p = sub.add_parser("decline", help="record a no")
common(p)
p.add_argument("--index", type=int, required=True)
p.add_argument("--reply")
p = sub.add_parser("result", help="record what happened after the Allow once / Deny card")
common(p)
p.add_argument("--index", type=int, required=True)
p.add_argument("--status", required=True, choices=["placed", "denied", "failed"])
p.add_argument("--broker-id")
p.add_argument("--note")
p.add_argument("--filled-qty")
p.add_argument("--filled-price")
p.add_argument("--portfolio", default="trader/portfolio.json")
p = sub.add_parser("fill", help="add a filled order to trader/portfolio.json")
p.add_argument("--symbol", required=True)
p.add_argument("--side", required=True, choices=["buy", "sell"])
p.add_argument("--qty", required=True)
p.add_argument("--price", required=True)
p.add_argument("--date")
p.add_argument("--portfolio", default="trader/portfolio.json")
p.add_argument("--config", default="trader/config.json")
p = sub.add_parser("log", help="today's decisions")
p.add_argument("--state", default="trader/state/broker.json")
p.add_argument("--today")
p.add_argument("--all", action="store_true")
a = ap.parse_args(argv)
if not a.cmd:
ap.print_help()
return 1
try:
return {"show": cmd_show, "approve": cmd_approve, "decline": cmd_decline, "result": cmd_result,
"fill": cmd_fill, "log": cmd_log}[a.cmd](a)
except TicketError as e:
print("ticket.py: %s" % e, file=sys.stderr)
return 1
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |