Franklin

<div align="center"> <br> <img src="assets/terminal-banner.png" alt="Franklin Agent terminal" width="680">

<br><br>

<h1>Franklin Agent</h1> <h3>The AI agent with a wallet.</h3> <p> Other agents just talk. Franklin Agent holds your USDC <em>and puts it to work</em> —<br> trading, research, and autonomous tasks with real budgets, real guardrails, real outcomes.<br> One wallet. Every model. Every paid API. Pay only for outcomes — not subscriptions. </p> <p> <a href="https://npmjs.com/package/@blockrun/franklin"><img src="https://img.shields.io/npm/v/@blockrun/franklin.svg?style=flat-square&color=FFD700&label=npm" alt="npm"></a> <a href="https://npmjs.com/package/@blockrun/franklin"><img src="https://img.shields.io/npm/dm/@blockrun/franklin.svg?style=flat-square&color=10B981&label=downloads" alt="downloads"></a> <a href="https://github.com/BlockRunAI/Franklin/stargazers"><img src="https://img.shields.io/github/stars/BlockRunAI/Franklin?style=flat-square&color=FFD700&label=stars" alt="stars"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-blue?style=flat-square" alt="license"></a> <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript"></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node-%E2%89%A520-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node"></a> <a href="https://x402.org"><img src="https://img.shields.io/badge/x402-native-10B981?style=flat-square" alt="x402"></a> <a href="https://t.me/blockrunAI"><img src="https://img.shields.io/badge/chat-telegram-26A5E4?style=flat-square&logo=telegram&logoColor=white" alt="telegram"></a> </p> <p> <a href="#quick-start">Quick&nbsp;start</a> · <a href="#yopo">YOPO</a> · <a href="#a-new-category">Category</a> · <a href="#what-franklin-can-execute">What&nbsp;it&nbsp;does</a> · <a href="#smart-router">Smart&nbsp;Router</a> · <a href="#the-comparison">Comparison</a> · <a href="#how-it-works">Architecture</a> · <a href="#community">Community</a> </p> </div>

---

The pitch in one paragraph

Franklin Agent is an autonomous economic agent — an AI that holds a USDC wallet and spends it to get real work done, with trading as its flagship arena. It buys live market data, proposes trade plans you approve before a cent moves, pursues long-running goals across sessions, keeps a wallet-bound trading journal, and picks the best model per task from 55+ providers. You state an outcome and set a budget. Franklin Agent decides what to call, what to pay for, and when to stop. Every paid action routes through the x402 micropayment protocol and settles against your own wallet. No subscriptions. No API keys. No account. The wallet is the identity.

Built by the BlockRun team. Apache-2.0. TypeScript. Ships as one npm package.

YOPO — You Only Pay Outcome

Not a subscription (pay for access). Not a generic pay-per-call (pay for trying). You pay only for the work Franklin Agent delivers. Provider cost + 5%, settled per action in USDC. No monthly fees. No rate limits. No overdraft.

---

Quick start

Requires Node.js 20.19+ (Node 22 LTS recommended). Check with node -v. Older Node crashes at startup with ERR_REQUIRE_ESM.

# 1. Install
npm install -g @blockrun/franklin

# 2. Run (free — uses NVIDIA Nemotron & Qwen3 Coder out of the box)
franklin

# 3. (optional) Fund a wallet to unlock Sonnet, Opus, GPT, Gemini, Grok, + paid APIs
franklin setup base        # or: franklin setup solana
franklin balance           # show address + USDC balance

That's it. Zero signup, zero credit card, zero phone verification. Send $5 of USDC to the wallet and you've unlocked every frontier model and every paid tool in the BlockRun gateway.

No global install? Just run it directly — no permissions, no -g:

npx @blockrun/franklin

Install troubleshooting

| Symptom | Cause | Fix | | ------- | ----- | --- | | npm error EACCES … mkdir '/usr/local/lib/node_modules' | Your global npm folder is owned by root (common when Node was installed from the macOS .pkg). | Don't use sudo. Either run npx @blockrun/franklin (no global install needed), or switch to a user-owned Node via a version manager — see below. | | Error [ERR_REQUIRE_ESM] … rpc-websockets … require() of ES Module … uuid | Node is older than 20.19. Franklin's Solana deps need the require(esm) support added in Node 20.19.0. | Upgrade to Node 20.19+ or 22 LTS (see below). This is the #1 cause of a crash on first run. | | npm warn EBADENGINE … required: { node: '>=20.x' } | Node is older than 20.19. | Upgrade to Node 20.19+ or 22 LTS. The warning alone is harmless, but on old Node the run will also crash — upgrade. |

The clean, permanent fix for both is a user-owned Node so global installs never touch root-owned system folders:

# nvm (https://github.com/nvm-sh/nvm)
nvm install 22 && nvm use 22
npm install -g @blockrun/franklin

# or fnm (https://github.com/Schniz/fnm)
fnm install 22 && fnm use 22
npm install -g @blockrun/franklin

Prefer a GUI? Try Franklin for VS Code

The same agent ships as a VS Code extension — chat panel, model picker, wallet balance, image / video generation, inline diff cards — all driven by the wallet you already funded for the CLI.

VS Code → Extensions  (Cmd+Shift+X / Ctrl+Shift+X)
        → search "Franklin" → Install
        → click the Franklin icon in the Activity Bar

Free models work immediately. Paid models, image gen, and video gen activate the moment your wallet has USDC. The CLI and the extension share the same ~/.blockrun/ config and session history, so jumping between terminal and VS Code is seamless.

---

YOPO

You Only Pay Outcome. This is Franklin Agent's pricing model, and it is the opposite of almost every other AI product you use.

| | You pay for... | Result | | ----------------------- | -------------------------------------------- | ------------------------------------ | | AI subscription | Access. Paid whether you use it or not. | $20–200/month, rate-limited. | | Pay-per-call (OpenAI API, etc.) | Every attempt — even failed ones. | Hidden cost from retries, dead ends. | | Franklin Agent (YOPO) | The outcome. Each signed micropayment. | Provider cost + 5%. No more. |

Three consequences fall out of this:

1. No subscriptions. Use Franklin for $0.50 one week and $50 the next — you pay for compute actually consumed, nothing more.
2. No rate limits. Subscriptions throttle you when you need AI most. YOPO has no artificial caps — if you have USDC, you have access.
3. No overdraft. The wallet balance IS the hard limit. When it's empty, Franklin stops. No surprise bills, no 3 a.m. rate-limit walls.

Concretely — $1 in USDC gets you roughly:

• ~400K GPT-4o input tokens
• ~7M DeepSeek tokens
• ~13M Gemini Flash tokens
• ~20 DALL-E 3 images
• ~40 Exa neural web searches
• Unlimited agent-tested NVIDIA free tier (Qwen3 Coder + Llama 4 Maverick, no wallet needed)

---

A new category

Economic Agent

Software that can hold a wallet, price its own actions, spend toward an outcome, and stop at a hard budget cap.

Most AI products fit into one of three buckets: they answer questions, write code, or automate a fixed workflow. None of them can spend money.

Franklin can. It combines purchasing power (it pays for models, tools, and APIs), budget awareness (cost is part of the loop, not an afterthought), cross-vertical execution (code, trading, research, marketing, ops), and hard stopping conditions (wallet balance is a real constraint, not a suggestion).

That is why Franklin is an economic agent, not just a task agent.

---

What Franklin can execute

Franklin is chat-first. You do not wire a DAG, configure six API keys, or commit to one model vendor. You state an outcome. Franklin decides what to read, search, fetch, call, and pay for.

📈 Trading signals

> what's BTC looking like today?

  ✓ TradingSignal  BTC

  ## BTC Signal Report

  Price: $71,056 USD (+2.3% 24h)
  Market Cap: $1.42T
  24h Volume: $29.6B

  ### Technical Indicators (30d)
  - RSI(14): 53.2 — neutral
  - MACD: 339.21 / Signal: 280.45 — bullish crossover
  - Bollinger: within band (upper $73,773 / lower $64,545)
  - Volatility: 35.3% annualized — medium

> if I enter at 65000 with $1000, where should my stop be?

  Based on ATR(14) and support at $63,500:
  Entry: $65,000 · Stop: $63,200 (−2.8%) · Risk: $27.69
  Risk/reward to $70K target: 1:2.8 ✓

Live data from CoinGecko. RSI, MACD, Bollinger, and volatility computed locally. No API key needed.

🛡️ Trades only move on YOUR approval

Real-money trades (Jupiter, 0x, Polymarket) are hard-gated behind a trade plan: the agent proposes a structured plan — venue, asset, size, slippage, stop condition, rationale, total spend — and nothing executes until you approve it. Approved budgets draw down per trade and expire in 15 minutes. This holds in every permission mode, --trust included. Add your own guardrails as lifecycle hooks — daily spend caps, token blacklists, spend ledgers — that veto actions before money moves.

🎯 Autonomous goals with adversarial verification

> /goal research the top 3 x402-compatible data APIs and produce a comparison

Franklin plans the objective, works it across turns on its own, and — when it claims completion — a panel of **adversa