sac-capital 0.1.1

AI trading research agent — paper trading on your Claude subscription, with verifiable on-chain decision commitments (Mantle)

SAC Capital

AI trading decisions are exported as deterministic bytes32 commitments and anchored on Mantle — anyone can verify agent behavior and outcomes.

Track: AI Alpha & Data · Turing Test Hackathon 2026

Demo	sapa-fund.vercel.app
Contract	0x1d1fFbC1b5F5E0471f8e8E28eAf007dd24EB4887
Deploy tx	0x46bbaa...

Install the CLI

uv tool install sac-capital   # or: pip install sac-capital
sac setup                     # step-by-step wizard — connect LLM, broker, alerts
sac doctor                    # verify config
sac run                       # equities pipeline (paper trading)

Runs on your Claude subscription via the claude CLI (no API key required) — Anthropic/OpenAI API keys and Codex optional. Every wizard step is skippable; config lives in ~/.sac-capital/. Full guide: INSTALL.md.

Command	Does
sac setup	interactive setup wizard (subscription-first, paper-only)
sac run	full equities screen → analyst → risk kernel → paper orders
sac research	supplier-lag research runner (--static-only etc.)
sac doctor	preflight checks; --llm adds a live LLM probe
sac verify	export deterministic decision commitment hashes

---

How It Works

US Equity Event Screen
  → Haiku pre-filter
  → Sonnet bull thesis
  → Sonnet challenger
  → Auditor
  → Risk Kernel (fractional Kelly, 2% per-trade cap, 35% sector cap)
  → Alpaca paper order + local ledger entry
  → Deterministic canonical JSON exporter
  → AgentDecisionRegistry on Mantle (bytes32 SHA-256 commitment)
  → Frontend verification panel

Mantle is the immutable benchmark layer. The agent hashes each decision payload with canonical JSON → SHA-256 → bytes32, records it on-chain, and can later anchor outcome hashes against the same decision ID. The frontend recomputes the hash client-side so reviewers can confirm the on-chain record matches the AI output.

Safety boundary: paper-only. On-chain records are verifiability anchors — not custody, brokerage, or live-trading instructions.

The equities research side now also includes a paper-only supplier-lag research runner:

uv run runner-research --static-only
uv run runner-research --strategy-backtest --static-only

runner-research saves the top research candidates to data/research_candidates.json and appends historical strategy backtests to data/strategy_backtests.jsonl when trades exist.

---

Reproduce Locally

Dependencies

uv sync

Tests

./.venv/bin/python -m pytest

Export decision commitments

./.venv/bin/python scripts/export_mantle_commitments.py \
  --ledger data/ledger.db \
  --out data/mantle_commitments.jsonl

Dry-run Mantle submission

./.venv/bin/python scripts/submit_mantle_decisions.py \
  --commitments data/mantle_commitments.jsonl \
  --contract 0x1d1fFbC1b5F5E0471f8e8E28eAf007dd24EB4887 \
  --agent-id mantle-verifiable-ai-agent \
  --limit 1

Deploy contract (Foundry required, funded Mantle wallet)

export MANTLE_RPC_URL=https://rpc.mantle.xyz
export MANTLE_PRIVATE_KEY=0x...

forge test
forge script contracts/script/DeployAgentDecisionRegistry.s.sol \
  --rpc-url "$MANTLE_RPC_URL" \
  --broadcast

Frontend

cd frontend
npm install
npm run dev

---

Repository Layout

cli/              `sac` CLI — banner, setup wizard, workdir, dispatcher
core/             Config, ledgers, alerts, LLM adapters (incl. claude_cli subscription provider)
equities/
  analysis/       Equity analyst, typed LLM schemas, budget controls
  data/           Prices, fundamentals, calendar, filings, news, macro, VIX
  eval/           Research artifact replay and report
  execution/      Alpaca paper execution and reconciliation
  killgate/       Forward-paper tracker and promotion gates
  research/       Artifact store and offline research modules
  risk/           Sizing, exits, risk kernel
  screen/         Event, quality, inflection, thematic, relative-strength, politician
contracts/        AgentDecisionRegistry.sol (Mantle)
scripts/          Commitment exporter, Mantle submission, nightly maintenance
runner_research.py Paper-only supplier-lag research runner
frontend/         React/Vite verification dashboard
tests/            790-test regression suite
docs/             Operator runbooks
deploy/           macOS launchd plists

---

Equities Pipeline

runner_equities.py runs the full loop:

1. Mark open positions and check exits
2. Classify macro regime
3. Check thesis health on open swing positions
4. Check thematic concentration
5. Run event screen (earnings + recent 8-K catalysts)
6. Add relative-strength, trend, base, breakout-volume evidence
7. Run quality and inflection screens
8. Apply VIX entry gate
9. Run LLM pre-filter → analyst → challenger → auditor
10. Validate with Pydantic; reject malformed outputs
11. Write research artifacts for all analysed candidates
12. Pass through risk kernel
13. Submit Alpaca paper orders or internal paper fills

Optional — Politician disclosure screen (off by default). When POLITICIAN_SIGNAL_ENABLED=true, a stage after relative-strength pulls recent US congressional STOCK Act buy disclosures (public House + Senate filings), scores them deterministically (recency, cluster, repeat-buyer, size), and feeds scored candidates into the same analyst funnel. Public-disclosure lag research only — not insider data, not copy-trading. Source feed URL is config-injected so the canonical House Clerk / Senate eFD sources can be swapped in without code changes.

---

Key Configuration

EXECUTION_PROVIDER=internal_paper   # never alpaca_live
LIVE_TRADING_ENABLED=false
EQUITY_RISK_PCT=0.005
EQUITY_MAX_POSITIONS=12
EQUITY_MAX_SECTOR_PCT=0.35
EQUITY_DAILY_LOSS_LIMIT_PCT=0.05

# Alpaca paper
ALPACA_PAPER=true
ALPACA_BASE_URL=https://paper-api.alpaca.markets
ALPACA_API_KEY_ID=...
ALPACA_SECRET_KEY=...

# Telegram
TELEGRAM_BOT_TOKEN=...
TELEGRAM_CHAT_ID=...
TELEGRAM_ALERT_MODE=critical   # critical | verbose

# LLM
ANTHROPIC_FAST_MODEL=claude-haiku-4-5-20251001
ANTHROPIC_STRONG_MODEL=claude-sonnet-4-6

# Politician disclosure screen (off by default)
POLITICIAN_SIGNAL_ENABLED=false
# Feed URLs default to public House/Senate stock-watcher mirrors; override to
# point at canonical sources. POLITICIAN_HOUSE_URL / POLITICIAN_SENATE_URL

---

Team

Name	Role
Nikolas Sapalidis	Lead Developer — architecture, Mantle integration, AI pipeline, frontend, investment strategy
Konstantopoulos Ilias	Safety features & stock research
George Apostolakis	Investment strategy & Mantle network funding

nikolas.helpmarq.com