{"id":49546444,"url":"https://github.com/BlockRunAI/franklin","last_synced_at":"2026-05-19T09:01:00.915Z","repository":{"id":346264640,"uuid":"1188475888","full_name":"BlockRunAI/Franklin","owner":"BlockRunAI","description":"The AI agent with a wallet — spends USDC autonomously to get real work done. Apache-2.0, TypeScript.","archived":false,"fork":false,"pushed_at":"2026-05-11T19:01:39.000Z","size":14203,"stargazers_count":618,"open_issues_count":0,"forks_count":42,"subscribers_count":19,"default_branch":"main","last_synced_at":"2026-05-11T19:05:11.160Z","etag":null,"topics":["ai-agent","ai-marketing","ai-trading","autonomous-agent","autonomous-economic-agent","blockrun","crypto-native","franklin","llm-agent","micropayments","multi-model","pay-per-action","runcode","typescript","usdc","wallet","wallet-native","x402"],"latest_commit_sha":null,"homepage":"https://franklin.run","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BlockRunAI.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-22T05:57:55.000Z","updated_at":"2026-05-11T19:01:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"ab9b926d-8183-4aca-8073-638d7c14eff4","html_url":"https://github.com/BlockRunAI/Franklin","commit_stats":null,"previous_names":["blockrunai/brcc","blockrunai/franklin"],"tags_count":96,"template":false,"template_full_name":null,"purl":"pkg:github/BlockRunAI/Franklin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlockRunAI%2FFranklin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlockRunAI%2FFranklin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlockRunAI%2FFranklin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlockRunAI%2FFranklin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BlockRunAI","download_url":"https://codeload.github.com/BlockRunAI/Franklin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlockRunAI%2FFranklin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33209392,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-19T07:54:09.561Z","status":"ssl_error","status_checked_at":"2026-05-19T07:54:08.508Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ai-marketing","ai-trading","autonomous-agent","autonomous-economic-agent","blockrun","crypto-native","franklin","llm-agent","micropayments","multi-model","pay-per-action","runcode","typescript","usdc","wallet","wallet-native","x402"],"created_at":"2026-05-02T20:00:18.031Z","updated_at":"2026-05-19T09:01:00.894Z","avatar_url":"https://github.com/BlockRunAI.png","language":"TypeScript","funding_links":[],"categories":["Web4 The Money Loop 🔄"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cbr\u003e\n\n\u003cimg src=\"assets/terminal-banner.png\" alt=\"Franklin Agent terminal\" width=\"680\"\u003e\n\n\u003cbr\u003e\u003cbr\u003e\n\n\u003ch1\u003eFranklin Agent\u003c/h1\u003e\n\u003ch3\u003eThe AI agent with a wallet.\u003c/h3\u003e\n\n\u003cp\u003e\n  Other agents write code. Franklin Agent writes code \u003cem\u003eand spends money\u003c/em\u003e to get things done.\u003cbr\u003e\n  One wallet. Every model. Every paid API. Pay only for outcomes — not subscriptions.\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://npmjs.com/package/@blockrun/franklin\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@blockrun/franklin.svg?style=flat-square\u0026color=FFD700\u0026label=npm\" alt=\"npm\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://npmjs.com/package/@blockrun/franklin\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/@blockrun/franklin.svg?style=flat-square\u0026color=10B981\u0026label=downloads\" alt=\"downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/BlockRunAI/Franklin/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/BlockRunAI/Franklin?style=flat-square\u0026color=FFD700\u0026label=stars\" alt=\"stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache_2.0-blue?style=flat-square\" alt=\"license\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.typescriptlang.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square\u0026logo=typescript\u0026logoColor=white\" alt=\"TypeScript\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Node-%E2%89%A520-339933?style=flat-square\u0026logo=node.js\u0026logoColor=white\" alt=\"Node\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://x402.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/x402-native-10B981?style=flat-square\" alt=\"x402\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://t.me/blockrunAI\"\u003e\u003cimg src=\"https://img.shields.io/badge/chat-telegram-26A5E4?style=flat-square\u0026logo=telegram\u0026logoColor=white\" alt=\"telegram\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick\u0026nbsp;start\u003c/a\u003e ·\n  \u003ca href=\"#yopo\"\u003eYOPO\u003c/a\u003e ·\n  \u003ca href=\"#a-new-category\"\u003eCategory\u003c/a\u003e ·\n  \u003ca href=\"#what-franklin-can-execute\"\u003eWhat\u0026nbsp;it\u0026nbsp;does\u003c/a\u003e ·\n  \u003ca href=\"#smart-router\"\u003eSmart\u0026nbsp;Router\u003c/a\u003e ·\n  \u003ca href=\"#the-comparison\"\u003eComparison\u003c/a\u003e ·\n  \u003ca href=\"#how-it-works\"\u003eArchitecture\u003c/a\u003e ·\n  \u003ca href=\"#community\"\u003eCommunity\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n---\n\n## The pitch in one paragraph\n\nMost coding agents write code. Franklin Agent writes code **and spends money to get the job done**. It holds a USDC wallet, picks the best model per task from 55+ providers, purchases trading data, generates images, pays for web search — all autonomously. 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](https://x402.org) micropayment protocol and settles against your own wallet. No subscriptions. No API keys. No account. The wallet is the identity.\n\nBuilt by the [BlockRun](https://blockrun.ai) team. Apache-2.0. TypeScript. Ships as one npm package.\n\n\u003e **YOPO — You Only Pay Outcome**\n\u003e\n\u003e Not a subscription (pay for access). Not a generic pay-per-call (pay for trying).\n\u003e You pay only for the work Franklin Agent delivers. Provider cost + 5%, settled per action\n\u003e in USDC. No monthly fees. No rate limits. No overdraft.\n\n---\n\n## Quick start\n\n```bash\n# 1. Install\nnpm install -g @blockrun/franklin\n\n# 2. Run (free — uses NVIDIA Nemotron \u0026 Qwen3 Coder out of the box)\nfranklin\n\n# 3. (optional) Fund a wallet to unlock Sonnet, Opus, GPT, Gemini, Grok, + paid APIs\nfranklin setup base        # or: franklin setup solana\nfranklin balance           # show address + USDC balance\n```\n\nThat'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.\n\n### Prefer a GUI? Try Franklin for VS Code\n\n[![Franklin for VS Code — Beta is here](assets/franklin-vscode-banner.png)](https://marketplace.visualstudio.com/items?itemName=blockrun.franklin-vscode)\n\nThe same agent ships as a [VS Code extension](https://marketplace.visualstudio.com/items?itemName=blockrun.franklin-vscode) — chat panel, model picker, wallet balance, image / video generation, inline diff cards — all driven by the wallet you already funded for the CLI.\n\n```\nVS Code → Extensions  (Cmd+Shift+X / Ctrl+Shift+X)\n        → search \"Franklin\" → Install\n        → click the Franklin icon in the Activity Bar\n```\n\nFree 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.\n\n---\n\n## YOPO\n\n**You Only Pay Outcome.** This is Franklin Agent's pricing model, and it is the opposite of almost every other AI product you use.\n\n|                         | You pay for...                               | Result                               |\n| ----------------------- | -------------------------------------------- | ------------------------------------ |\n| AI subscription       | Access. Paid whether you use it or not. | $20–200/month, rate-limited.         |\n| Pay-per-call (OpenAI API, etc.) | Every attempt — even failed ones.    | Hidden cost from retries, dead ends. |\n| **Franklin Agent (YOPO)**     | **The outcome.** Each signed micropayment.  | **Provider cost + 5%. No more.**     |\n\nThree consequences fall out of this:\n\n1. **No subscriptions.** Use Franklin for $0.50 one week and $50 the next — you pay for compute actually consumed, nothing more.\n2. **No rate limits.** Subscriptions throttle you when you need AI most. YOPO has no artificial caps — if you have USDC, you have access.\n3. **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.\n\nConcretely — $1 in USDC gets you roughly:\n- ~400K GPT-4o input tokens\n- ~7M DeepSeek tokens\n- ~13M Gemini Flash tokens\n- ~20 DALL-E 3 images\n- ~40 Exa neural web searches\n- Unlimited agent-tested NVIDIA free tier (Qwen3 Coder + Llama 4 Maverick, no wallet needed)\n\n---\n\n## A new category\n\n\u003e **Economic Agent**\n\u003e\n\u003e Software that can hold a wallet, price its own actions, spend toward an outcome, and stop at a hard budget cap.\n\nMost AI products fit into one of three buckets: they answer questions, write code, or automate a fixed workflow. None of them can spend money.\n\nFranklin 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).\n\nThat is why Franklin is an economic agent, not just a task agent.\n\n---\n\n## What Franklin can execute\n\nFranklin 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.\n\n### 📈 Trading signals\n\n```text\n\u003e what's BTC looking like today?\n\n  ✓ TradingSignal  BTC\n\n  ## BTC Signal Report\n\n  Price: $71,056 USD (+2.3% 24h)\n  Market Cap: $1.42T\n  24h Volume: $29.6B\n\n  ### Technical Indicators (30d)\n  - RSI(14): 53.2 — neutral\n  - MACD: 339.21 / Signal: 280.45 — bullish crossover\n  - Bollinger: within band (upper $73,773 / lower $64,545)\n  - Volatility: 35.3% annualized — medium\n\n\u003e if I enter at 65000 with $1000, where should my stop be?\n\n  Based on ATR(14) and support at $63,500:\n  Entry: $65,000 · Stop: $63,200 (−2.8%) · Risk: $27.69\n  Risk/reward to $70K target: 1:2.8 ✓\n```\n\nLive data from CoinGecko. RSI, MACD, Bollinger, and volatility computed locally. No API key needed.\n\n### 🎨 Image generation\n\n```text\n\u003e generate a logo for my AI startup — minimalist, dark background\n\n  ✓ ImageGen  \"minimalist AI startup logo, dark background...\"\n  Saved: generated-logo-1713052800.png (1024x1024)\n```\n\nGenerates images via DALL-E / GPT Image directly from the CLI. Paid from your wallet — no OpenAI API key needed.\n\n### 📱 Remote control via Telegram\n\nRun `franklin telegram` on an always-on machine (set `TELEGRAM_BOT_TOKEN` + `TELEGRAM_OWNER_ID`) and drive Franklin from your phone. Owner-locked, session-resumable across restarts, slash commands (`/new`, `/balance`, `/status`). Trading, content, dev work — all reachable from a Telegram chat.\n\n### 🔎 Research, code, anything with a budget\n\n```text\n\u003e compare the top 5 AI agent pricing models, summarize the patterns, and save a note for me\n\n  ✓ WebSearch  ai agent pricing models\n  ✓ WebFetch   5 articles\n  ✓ Write      notes/agent-pricing.md\n\n  Summary:\n  - Most agents hide pricing behind monthly seats\n  - Usage-based products win with power users and teams\n  - Wallet-based billing is still basically empty whitespace\n```\n\n```text\n\u003e refactor src/auth.ts to use the new jwt helper, then run the tests\n\n  ✓ Read   src/auth.ts                    $0.002\n  ✓ Read   src/lib/jwt.ts                 $0.001\n  ✓ Edit   src/auth.ts (-24 +31 lines)    $0.008\n  ✓ Bash   npm test                       $0.000\n    › 142 passing · 0 failing · 2.4s\n\n  Done in 18s · $0.011\n```\n\nCode is still first-class. It is just **one workload**, not the category.\n\nEvery tool call is itemized. Every token is priced. When the wallet hits zero, Franklin stops. No overdraft, no surprise bill, no rate-limit wall at 3 a.m. — this is YOPO in practice.\n\n---\n\n## Smart Router\n\n**55+ models. One decision. Zero guesswork.**\n\nYou don't pick models. Franklin picks for you.\n\nThe Smart Router classifies every request — coding, trading, reasoning, research — and selects the model with the best quality-to-cost ratio. Trained on **2M+ real requests** from the BlockRun gateway, continuously updated.\n\n```text\n\u003e refactor this auth module to use JWT\n\n  CODING kimi-k2.5  ·  12.4K in / 2.1K out  ·  $0.0023  saved 84%\n\n\u003e what's the BTC outlook for the week?\n\n  TRADING grok-4-1-fast-reasoning  ·  8.2K in / 1.8K out  ·  $0.0008  saved 95%\n\n\u003e prove that this algorithm is O(n log n)\n\n  REASONING claude-sonnet-4.6  ·  15.1K in / 3.4K out  ·  $0.0312\n```\n\nEvery response shows which model was chosen, why, and how much you saved vs. always using the most expensive option.\n\n**Four profiles:**\n\n| Profile | Strategy | Use case |\n|---------|----------|----------|\n| `auto` | Best quality-to-cost ratio | Default — smart spend |\n| `eco` | Cheapest model with decent quality | Budget-conscious |\n| `premium` | Highest quality regardless of cost | Mission-critical |\n| `free` | Free NVIDIA models only | Zero wallet balance |\n\n**Per-session breakdown** — run `/cost` to see exactly where your USDC went:\n\n```text\nSession Cost: $0.0847 (23 requests)\n  gemini-2.5-flash       $0.0012   14 req   CODING\n  kimi-k2.5              $0.0423    6 req   CODING\n  claude-sonnet-4.6      $0.0412    3 req   REASONING\n```\n\nThe router also learns from **your** usage. If you keep retrying a model for coding tasks, Franklin adapts and picks a better one next time. Your router gets smarter the more you use it.\n\n---\n\n## Why Franklin\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"33%\" valign=\"top\"\u003e\n\n### 💳 \u0026nbsp;AI is utility, not SaaS\n\nYou don't subscribe to electricity, you pay for what you use. Franklin brings the same model to AI. YOPO settlement means Franklin never bills you for access, only for outcomes. No monthly fees, no rate limits, no overdraft.\n\n\u003c/td\u003e\n\u003ctd width=\"33%\" valign=\"top\"\u003e\n\n### 🧠 \u0026nbsp;Multi-model is the future\n\nNo single model is best at everything. Sonnet writes better code, Gemini handles longer context, DeepSeek costs 20x less for simple tasks. The Smart Router routes every request to the optimal model in \u003c1ms — up to 89% savings vs. always using Opus.\n\n\u003c/td\u003e\n\u003ctd width=\"33%\" valign=\"top\"\u003e\n\n### 🔐 \u0026nbsp;Wallet is identity\n\nNo email. No phone. No KYC. Your Base or Solana address is your account — portable, permissionless, global. API keys require US banking and account approval. A wallet requires only USDC.\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## The comparison\n\n|                                        | Coding agents    | Editor IDEs      | Chatbots         | **Franklin**                    |\n| -------------------------------------- | ---------------- | ---------------- | ---------------- | ------------------------------- |\n| Writes code                            | ✅               | ✅               | ⚠️                | ✅                              |\n| **Spends money for you**               | ❌               | ❌               | ❌               | ✅ **USDC wallet, x402**        |\n| **Buys data + APIs + images + search** | ❌               | ❌               | ❌               | ✅ **55+ APIs, one wallet**     |\n| Picks best model per task              | ❌ single-vendor | ❌ plan-tied    | ❌               | ✅ **Smart Router, 55+ models** |\n| Pricing model                          | Subscription     | Subscription     | Subscription     | **YOPO** — per outcome, USDC    |\n| Monthly fee                            | $20–$200         | $20–$40          | $20+             | **$0**                          |\n| Rate-limited                           | Yes              | Yes              | Yes              | No — limited only by wallet     |\n| Works when provider goes down          | ❌               | ❌               | ❌               | ✅ **routes to another**        |\n| Identity                               | Vendor account   | Vendor account   | Account / email  | ✅ **wallet, no signup**        |\n| Start free, no KYC                     | ❌               | ❌               | ❌               | ✅                              |\n| Source                                 | Closed           | Closed           | Closed           | **Apache 2.0, local-first**     |\n\n**Franklin is the economic agent category in one sentence:** software with a wallet that can spend toward a result.\n\n---\n\n## Features\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n**💼 Wallet-native economic execution**\nFranklin can decide what is worth paying for, route the call, sign the micropayment, and keep going until the goal is done or the budget is exhausted.\n\n**📈 Trading signals**\nAsk \"what's BTC looking like?\" — Franklin fetches live price data, computes RSI/MACD/Bollinger/volatility, and synthesizes a signal.\n\n**🎨 AI image generation**\nAsk \"generate a logo\" — Franklin calls DALL-E / GPT Image, saves the result locally, paid from your wallet.\n\n**🧠 55+ models via one wallet**\nAnthropic, OpenAI, Google, xAI, DeepSeek, GLM, Kimi, Minimax, NVIDIA free tier. One wallet, one interface, automatic fallback.\n\n**💳 x402 micropayments (YOPO)**\nHTTP 402 native. Every paid action is a signed USDC micropayment via EIP-712 — non-custodial, your keys never leave your machine. YOPO: you pay only for outcomes.\n\n**🧠 Learned model router**\nTrained on 2M+ real requests. Classifies your task and picks the best model from 55+ LLMs. Four profiles (auto/eco/premium/free). Adapts to your usage over time.\n\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n**🛠 16 built-in tools**\nRead, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task, ImageGen, VideoGen, MemoryRecall, AskUser, SubAgent, TradingSignal, TradingMarket, TradingPortfolio, TradingOpenPosition, TradingClosePosition, TradingHistory.\n\n**💾 Persistent sessions**\nEvery turn is streamed to disk with metadata. Resume any session by ID. Survives crashes, reboots, and compaction.\n\n**🔍 Full-text session search**\n`franklin search \"payment loop\"` from the CLI, or `/session-search \"payment loop\"` in chat.\n\n**📊 Cost insights**\n`franklin insights` shows spend breakdowns, trends, and projections. Never wonder where the USDC went.\n\n**⚡ Anthropic prompt caching**\nMulti-turn Sonnet/Opus sessions use ephemeral cache breakpoints to reduce input spend on long conversations.\n\n**🔌 Plugin SDK + MCP**\nCore is workflow-agnostic. Add new verticals without touching the loop. Discover external tools automatically through MCP.\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## Slash commands\n\n| Command                          | What it does                                         |\n| -------------------------------- | ---------------------------------------------------- |\n| `/model [name]`                  | Interactive model picker, or switch directly         |\n| `/plan` / `/execute`             | Read-only planning mode / execution mode             |\n| `/ultrathink \u003cq\u003e`                | Deep reasoning mode for hard problems                |\n| `/compact`                       | Structured context compression                       |\n| `/search \u003cq\u003e`                    | Search the codebase                                  |\n| `/session-search \u003cq\u003e`            | Search past sessions                                 |\n| `/history` / `/resume [id]`      | Inspect or restore conversation state                |\n| `/commit` / `/push` / `/pr`      | Git workflow helpers                                 |\n| `/review` / `/fix` / `/test`     | One-shot code review, bugfix, or test runs           |\n| `/cost` / `/wallet`              | Session cost, wallet address, and balance            |\n| `/insights [--days N]`           | Rich usage analytics                                 |\n| `/help`                          | Full command list                                    |\n\n---\n\n## How it works\n\n```text\n┌──────────────────────────────────────────────────────────────┐\n│  Franklin Runtime                                            │\n│  Intent → Smart Router → Tool Use → Spend Control → Result   │\n├──────────────────────────────────────────────────────────────┤\n│  Learned Router                                              │\n│  2M+ requests · 55+ models · category detection · Elo scores │\n├──────────────────────────────────────────────────────────────┤\n│  Agent Loop                                                  │\n│  16 tools · Sessions · Compaction · Pricing · Plugin SDK     │\n├──────────────────────────────────────────────────────────────┤\n│  BlockRun Gateway                                            │\n│  55+ LLMs · CoinGecko · Search · Image APIs · paid services  │\n├──────────────────────────────────────────────────────────────┤\n│  x402 Micropayment Protocol                                  │\n│  HTTP 402 · USDC on Base \u0026 Solana · signed payment payloads  │\n└──────────────────────────────────────────────────────────────┘\n                            │\n                            ▼\n                     ┌─────────────┐\n                     │ Your wallet │\n                     │  (you own)  │\n                     └─────────────┘\n```\n\nThe loop is simple:\n1. You state an outcome.\n2. Franklin chooses what to read, call, and pay for.\n3. The payment settles against your wallet.\n4. Franklin reports the result and the spend.\n\nThat economic loop is the product.\n\n---\n\n## Project layout\n\n```text\nsrc/\n├── index.ts           CLI entry (franklin)\n├── banner.ts          Ben Franklin portrait + FRANKLIN gradient text\n├── agent/             Agent loop, LLM client, compaction, commands\n├── tools/             20+ built-in tools (Read/Write/Edit/Bash/Glob/Grep/\n│                      WebFetch/WebSearch/Task/ImageGen/VideoGen/\n│                      MemoryRecall/AskUser/SubAgent/Trading*/Content*)\n├── trading/           Market data (CoinGecko) + technical indicators\n├── content/           Content library with budget-bound media generation\n├── brain/             Cross-session entity knowledge graph\n├── channel/           Non-CLI ingress drivers (Telegram today)\n├── events/            Internal event bus\n├── plugin-sdk/        Public plugin contract (Workflow/Plugin/Channel)\n├── plugins/           Plugin registry + runner (plugin-agnostic)\n├── session/           Persistent sessions + search + channel tags\n├── stats/             Usage tracking + insights engine\n├── ui/                Ink-based terminal UI\n├── proxy/             Payment proxy for external tools\n├── router/            Learned model router (55+ models, Elo scoring)\n├── wallet/            Wallet management (Base + Solana)\n├── mcp/               MCP server auto-discovery\n└── commands/          CLI subcommands\n```\n\n---\n\n## Free tier, for real\n\nStart with **zero dollars**. Franklin defaults to free NVIDIA models that need no wallet funding.\n\n```bash\nfranklin --model free\n```\n\nWhen you fund the wallet, Franklin gets more purchasing power: Sonnet, Opus, GPT, Gemini, Grok, and paid tools like Exa, DALL-E, and CoinGecko Pro.\n\n---\n\n## Remote control via Telegram\n\nDrive Franklin from anywhere with a bot token:\n\n```bash\nexport TELEGRAM_BOT_TOKEN=\u003cfrom @BotFather\u003e\nexport TELEGRAM_OWNER_ID=\u003cyour numeric Telegram user id\u003e\nfranklin telegram                # start the bot (owner-locked)\n```\n\nSession state resumes across process restarts (tagged by owner id).\nSlash commands `/new`, `/balance`, `/status`, `/help` handled locally\nby the bot layer; everything else forwards to the agent. Progressive\nstreaming flushes partial answers at paragraph boundaries so long\nreplies don't wait for turn-end.\n\nSame wallet. Same tools. From your phone.\n\n---\n\n## Documentation\n\n- [Plugin SDK guide](docs/plugin-sdk.md) — build your own workflow vertical\n- [Changelog](CHANGELOG.md) — every release explained\n- [Roadmap](docs/ROADMAP.md) — what's coming next\n- [Proxy mode](docs/) — use Franklin as a payment proxy for Anthropic-compatible CLI agents\n\n---\n\n## Community\n\n- [Telegram](https://t.me/blockrunAI) — realtime help, bug reports, feature requests\n- [@BlockRunAI](https://x.com/BlockRunAI) — release notes, demos\n- [Issues](https://github.com/BlockRunAI/Franklin/issues) — bugs and feature requests\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/BlockRunAI/Franklin.git\ncd franklin\nnpm install\nnpm run build\nnpm test              # deterministic local tests — no API calls\nnpm run test:e2e      # live e2e tests — free smoke works unfunded; paid tools need network + funded wallet\nnpm run test:free-models # live matrix across current free NVIDIA models\nnode dist/index.js --help\n```\n\nFor the recommended live validation order and failure triage, see [docs/live-e2e-checklist.md](docs/live-e2e-checklist.md).\n\n**Contributing:** open an issue first to discuss meaningful changes. PRs welcome on bugs, docs, new models in pricing, and new tools.\n\n---\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE).\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**The AI agent with a wallet.**\u003cbr\u003e\n\u003csub\u003eYOPO — You Only Pay Outcome. Your wallet. Your budget. Your results.\u003c/sub\u003e\n\n\u003cbr\u003e\n\n\u003csub\u003eFrom the team at \u003ca href=\"https://blockrun.ai\"\u003eBlockRun\u003c/a\u003e.\u003c/sub\u003e\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBlockRunAI%2Ffranklin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBlockRunAI%2Ffranklin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBlockRunAI%2Ffranklin/lists"}