@blockrun/franklin-trading

Franklin Trading

The AI trading agent with a wallet.

Researches, debates, backtests, paper-trades and live-trades autonomously. Every decision is a multi-persona debate. Every fill has an on-chain x402 USDC receipt. Fund the wallet. Set a budget. Walk away — and come back to a book.

Franklin Trading is a fork of Franklin — the general-purpose Autonomous Economic Agent — specialized as a wallet-native trading agent. It inherits Franklin's economic substrate (x402 micropayments, USDC settlement, learned-weight model router across 55+ models, removable-by-design harness components) and adds a multi-role persona debate, a unified Backtest → Paper → Live strategy lifecycle, multi-venue on-chain execution, and four moat layers nobody else ships.

Why Franklin Trading

The open-source trading-agent landscape splits into halves nobody has joined:

Project	Strength	What it can't do
TradingAgents (78.8k★)	Multi-role agent debate, academic rigor	No live execution; 0% prompt-cache hit rate (#750); ticker hallucination (#814)
AI-Trader (18.5k★)	Federated agents, Polymarket live data, copy-trading	Stale price data (#188); position-averaging bug (#186); no published backtests (#207)
Vibe-Trading (8.4k★)	LLM-driven research, persistent memory, Alpha Zoo (452 factors), Shadow Account	Zero exchange connectors (#100)
Hummingbot (18.6k★, $34B+ volume)	50+ CEX/DEX connectors, V2 framework, institutional-grade risk controls	No LLM brain; no narrative awareness

Franklin Trading is the synthesis: Vibe-Trading-style natural-language research and persistent memory, TradingAgents-style hierarchical persona debate, Hummingbot-style multi-venue execution rigor — wrapped in Franklin's wallet-native economic substrate and four new moat layers (regime detection, prompt-cache optimization, slippage realism, hallucination guards).

The four moats nobody else ships

Each is a removable harness component per ADR 0003: toggle off with an env flag when the model catches up.

Layer	What it does	Env opt-out
Regime detector	Lightweight HMM on rolling vol + correlation; tags every decision; swaps Trader persona prompt between trend / chop / risk-off	FRANKLIN_NO_REGIME=1
Prompt-cache optimizer	Separates static persona prompts from volatile context; targets ≥40% cache hit rate from turn 2	FRANKLIN_NO_PROMPTCACHE=1
Slippage model	Per-venue impact (linear+sqrt) calibrated from observed fills; applied consistently in backtest, paper, live	FRANKLIN_NO_SLIPPAGE=1
Fact-checker	Deterministic ticker → entity resolver via on-chain registries + CoinGecko; blocks TOTDY-style hallucinations	FRANKLIN_NO_FACTCHECK=1

Quick start

npm install -g @blockrun/franklin-trading

# Create a USDC wallet on Base (or solana)
franklin-trading setup base

# Fund it with $20+ USDC — print address with:
franklin-trading balance

# Start with a budget — Franklin Trading stops when the wallet runs dry
franklin-trading --max-spend 5

# M1 strategy-runner work is in progress; today, use the agent's paper
# trading tools from an interactive session.
franklin-trading

A 60-second tour

# Research mode — natural language, multi-persona debate
> "Is the BTC perp funding rate on Hyperliquid right now wide enough
   to support a 1% NAV basis trade against spot on Jupiter?"

  [fundamentals-analyst]  thesis + citations
  [sentiment-analyst]     X chatter score, drivers
  [technical-analyst]     funding curve, term structure
  [bull-researcher]       carry thesis, target P&L
  [bear-researcher]       margin call risk, slippage risk
  [trader]                action: arb-long-spot-short-perp, size 0.2
  [risk-officer]          ✓ approved (within $400 position cap)
  [compliance-officer]    ✓ approved (audit_id: a1b2c3d4)

  → Estimated round-trip cost: $0.07 (LLM) + $0.83 (gas/fees)
  → Confirm? [y/N]

Every persona output, every model call, every gas fee, every fill is written to ~/.blockrun/sessions/<uuid>.jsonl. Resume any session, search across all of them, audit every trade.

Planned Strategy DSL (M1)

The author-facing strategy helper is available for early artifacts, while the franklin-trading run <strategy> command and unified backtest/paper/live runtime are still M1 roadmap work.

// src/strategies/btc-funding-basis.strategy.ts
import { defineStrategy } from '@blockrun/franklin-trading/strategy';

export default defineStrategy({
  name: 'btc-funding-basis',
  universe: ['BTC-PERP@hyperliquid', 'BTC@jupiter'],
  signal: async (ctx) => {
    const fr = await ctx.market.fundingRate('BTC-PERP@hyperliquid');
    return fr > 0.0001
      ? { action: 'arb-long-spot-short-perp', size: 0.2 }
      : null;
  },
  risk: { maxNotionalUsd: 1000, maxDrawdownPct: 5, killSwitch: true },
  schedule: { every: '1m' },
});

Once the M1 runner lands, one artifact will run three modes:

franklin-trading run btc-funding-basis --mode backtest --from 2024-01-01
franklin-trading run btc-funding-basis --mode paper      # live data, simulated fills
franklin-trading run btc-funding-basis --mode live       # real on-chain orders

Architecture

                Franklin Trading CLI / TUI / Telegram
                              │
                      Agent loop (inherited from brcc)
              plan · execute · compact · evaluate · verify · polish
                       (each removable via FRANKLIN_NO_*)
                              │
            ┌─────────────┬───┴──────┬──────────────┐
       Smart Router    Brain +     Session +    NEW: Trading
       (learned,     Learnings +   Cost +       Harness Layers
        55 models)   Shadow Acct   JSONL        (4 moats)
                              │
   Role personas (NEW): Analyst → Bull / Bear → Trader → Risk → Compliance
                              │
   Strategy surface (M1): defineStrategy now; unified runner roadmap
                              │
   Execution: Hyperliquid · Jupiter · 0x · Polymarket · Binance (read-only)
                              │
   Economic substrate (inherited): USDC wallet on Base + Solana, x402 micropayments

See PHILOSOPHY.md for the design principles, docs/CONVICTIONS.md for the 12 design stances formed from analyzing 60+ open issues across the four reference projects, and docs/adr/ for individual architecture decisions.

Base MCP — onchain actions

Franklin connects to the official Base MCP server (https://mcp.base.org) for onchain Base actions — balances, transactions, swaps, and x402 payments — authorized via your Base Account (OAuth, per-write approval). One command:

franklin mcp add base      # browser login, then `franklin start` — tools as mcp__base__*

The HTTP+OAuth transport is generic: franklin mcp add <name> --url <url> connects any hosted MCP server that supports Dynamic Client Registration + PKCE. See docs/base-mcp.md.

Roadmap

Status	Milestone
✅	M0 — Fork from brcc, prune non-trading verticals, rebrand
🚧	M1 — Strategy DSL + walk-forward backtest engine
🚧	M2 — Role personas (Analyst, Bull, Bear, Trader, Risk, Compliance) wired via Task dispatch
🚧	M3 — Four moats (regime.ts, prompt-cache.ts, slippage.ts, fact-check.ts)
🚧	M4 — Connectors (read): Hyperliquid, Jupiter, 0x, Polymarket, Binance
🚧	M5 — Connectors (write) + 24h-clean paper trade
🚧	M6 — Alpha Zoo (40 factors v1) + Shadow Account (broker CSV import)
🚧	M7 — Polish, docs, demo GIF, benchmark page, v1.0.0 launch

Out of scope (deliberate cuts)

• Equities (IB / Alpaca / retail brokers) — v2; crypto-first proves the loop
• Options Greeks / vol-surface fitting — v2
• Hosted SaaS — never; Franklin Trading's whole point is non-custodial
• Token model / liquidity-mining rewards — v2 at earliest; institutional approach in v1
• LangGraph or any other agent-graph runtime — we use Franklin's Task tool dispatch
• Web dashboard — v2; CLI + TUI + Telegram is sufficient for v1
• Full-orderbook market-making — Hummingbot already excels here; we differentiate on LLM-driven research + execution

Contributing

See CONTRIBUTING.md. The brcc rule applies: every fix needs a receipt (session id, log line, gateway response) showing the bug actually happened. We don't accept "looks broken" fixes.

License

Apache-2.0 — see LICENSE. Inherits the upstream Franklin license. Strategy contributions in strategies/community/ follow the same license unless explicitly marked otherwise.

Acknowledgements

Franklin Trading stands on the shoulders of these open-source projects:

• Franklin (brcc) — wallet, x402, router, harness, plugin SDK
• TradingAgents — multi-role debate architecture
• AI-Trader — federated-agent + Polymarket integration ideas
• Vibe-Trading — Alpha Zoo, persistent research memory, Shadow Account
• Hummingbot — Executor/Controller framework, multi-venue connector abstraction, governance model

If we did our job right, this is the agent each of them wanted to be.