Franklin

The AI agent with a wallet.

While others chat, Franklin spends — turning your USDC into real work.

Franklin runs your money

Franklin is the first AI agent that can actually spend money to get work done. Not just write text about it.

$ franklin marketing campaign "Launch my AI coding app to indie hackers"
  Budget cap: $10

  ✓ $0.50  Research competitors via Exa
  ✓ $1.20  Write 5 blog post drafts (Claude Sonnet 4.6)
  ✓ $0.48  Generate 3 hero images (DALL-E 3)
  ✓ $3.50  Generate 15-second launch video (Runway)
  ✓ $0.80  Generate background music (Suno)
  ✓ $0.30  Find 20 relevant Reddit discussions
  ✓ $1.50  Draft Reddit comments (Claude Sonnet 4.6)
  ✓ $0.10  Post 3 casts to Farcaster

  Total spent: $8.58 · Time: 4m 32s
  Deliverables: 5 blog posts, 3 hero images, 1 launch video, 1 music
                track, 20 Reddit drafts, 3 Farcaster casts (live)

One wallet. Every model. Every paid API. No subscriptions. No accounts.

Two products, one Franklin

Both paid per action in USDC. Both backed by the same BlockRun gateway and x402 protocol.

Why Franklin is different

Franklin is the first AI agent in the "Autonomous Economic Agent" category — an agent that receives a goal, decides what to spend on, and executes autonomously within a hard budget cap enforced by the wallet.

Quick Start

# Install
npm install -g @blockrun/franklin

# Create a wallet (Base or Solana)
franklin setup base

# Fund wallet with USDC (any amount, $5 gets you started)
# Check address: franklin balance

# Run
franklin                           # Interactive agent — code, research, anything
franklin marketing run             # Marketing workflow
franklin trading signal "BTC"      # Trading workflow
franklin plugins                   # List installed plugins

Start free: use franklin with NVIDIA's free models (Nemotron, Qwen3 Coder) — zero wallet funding required to try it out.

How it works

┌─────────────────────────────────────────────────┐
│  Franklin Agent (you)                            │
│  Plugin SDK · CLI · Multi-model router           │
├─────────────────────────────────────────────────┤
│  BlockRun Gateway                                │
│  Aggregates 55+ LLMs + Exa + DALL-E + (soon)    │
│  Runway + Suno + CoinGecko + Dune + Apollo       │
├─────────────────────────────────────────────────┤
│  x402 + Wallet Infrastructure                    │
│  HTTP 402 micropayments · USDC on Base/Solana    │
└─────────────────────────────────────────────────┘

Every API call is paid atomically from your wallet via the x402 protocol. You fund once; Franklin spends per task. The wallet is your identity — no accounts, no API keys, no KYC.

Features

Core agent (55+ models)

• Multi-model routing — Claude Sonnet/Opus, GPT-5.4, Gemini 2.5 Pro, DeepSeek, Grok 4, Kimi, GLM-5.1, Llama, NVIDIA free tier
• Automatic fallback — if one model fails, Franklin tries the next
• Smart tiers — free / cheap / premium per task, user-configurable
• Prompt caching — 75% input token savings on Anthropic multi-turn (Hermes pattern)
• Structured context compression — Goal / Progress / Decisions / Files / Next Steps template
• Session search — franklin search "payment loop" — full-text across past sessions
• Rich insights — franklin insights — cost breakdown, daily activity sparklines, projections

Plugin SDK

Franklin is plugin-first. Core stays workflow-agnostic. Adding a new vertical requires zero core changes.

import type { Plugin, Workflow } from '@blockrun/franklin/plugin-sdk';

const myWorkflow: Workflow = {
  id: 'my-workflow',
  name: 'My Workflow',
  description: '...',
  steps: [
    { name: 'search', modelTier: 'none', execute: async (ctx) => ({ ... }) },
    { name: 'filter', modelTier: 'cheap', execute: async (ctx) => ({ ... }) },
    { name: 'draft',  modelTier: 'premium', execute: async (ctx) => ({ ... }) },
  ],
  // ...
};

Full plugin guide: docs/plugin-sdk.md

Built-in tools

Read · Write · Edit · Bash · Glob · Grep · WebFetch · WebSearch · Task · ImageGen · AskUser · SubAgent (delegated child agents with isolated toolsets)

MCP integration

Auto-discovers installed MCP servers including blockrun-mcp (market data, X data, prediction markets) and unbrowse (turn any website into an API). Add your own in ~/.blockrun/mcp.json.

Slash Commands

Migration from RunCode

Nothing breaks. If you were using RunCode, your runcode command continues to work as an alias for franklin for 60 days. Your config at ~/.blockrun/ is unchanged. Your wallet, sessions, and settings all migrate automatically.

The package name is now @blockrun/franklin. Update when convenient:

npm uninstall -g @blockrun/runcode
npm install -g @blockrun/franklin

Both commands (franklin and runcode) work for the next 60 days. After v3.1.0 ships, runcode will be removed.

Architecture

src/
├── agent/              # Core agent loop, multi-model LLM client, compaction
├── tools/              # 12 built-in tools
├── plugin-sdk/         # Public plugin contract (Workflow, Channel, Plugin)
├── plugins/            # Plugin registry + runner (plugin-agnostic)
├── plugins-bundled/    # Ships with Franklin — social, marketing (more coming)
├── session/            # Persistent sessions + FTS search
├── stats/              # Usage tracking + insights engine
├── ui/                 # Terminal UI (Ink-based)
├── proxy/              # Payment proxy for Claude Code compatibility
├── router/             # Smart model tier routing
├── wallet/             # Wallet management (Base + Solana)
└── commands/           # CLI subcommands

Development

git clone https://github.com/BlockRunAI/franklin.git
cd franklin
npm install
npm run build
npm test             # Deterministic local tests (no API calls)
npm run test:e2e     # Live end-to-end tests (hits real models)
node dist/index.js --help

Contributing

Contributions welcome. Open an issue first to discuss meaningful changes. For plugin ideas, see docs/plugin-sdk.md — the plugin system is how most new features should land.

Links

• Marketing: franklin.run
• Trading: franklin.bet
• Parent: BlockRun
• npm: @blockrun/franklin
• Telegram: t.me/blockrunAI
• x402 protocol: x402.org

License

Apache-2.0. See LICENSE.

Franklin runs your money.
_{Your wallet, your agent, your results.}