Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Franklin Agent

Open-source AI agent with a wallet. <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models. Pay per use with BlockRun API account credit or USDC wallets via x402.
Open-source AI agent with a wallet. <!-- br:models.chatVisible -->90<!-- /br:models.chatVisible --> models. Pay per use with BlockRun API account credit or USDC wallets via x402.

## Commands

Expand Down
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Capability pillars:

Built on three layers:
1. **x402 micropayment protocol** — HTTP 402 native payments
2. **BlockRun Gateway** — aggregates <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> LLMs + paid APIs (Exa, DALL-E, future Runway/Suno/CoinGecko)
2. **BlockRun Gateway** — aggregates <!-- br:models.chatVisible -->90<!-- /br:models.chatVisible --> LLMs + paid APIs (Exa, DALL-E, future Runway/Suno/CoinGecko)
3. **Franklin Agent** — this repo, the reference client

## Commands
Expand Down
2 changes: 1 addition & 1 deletion CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ The first, unpaid HTTP request whose 402 response carries the payment terms; Fra
_Avoid_: Pre-flight, handshake.

**BlockRun Gateway**:
The single upstream service Franklin calls for both LLM completions and paid tools (Exa, ImageGen, VideoGen, MusicGen, market data); aggregates <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models and accepts x402.
The single upstream service Franklin calls for both LLM completions and paid tools (Exa, ImageGen, VideoGen, MusicGen, market data); aggregates <!-- br:models.chatVisible -->90<!-- /br:models.chatVisible --> models and accepts x402.
_Avoid_: API, provider, backend, BlockRun (without "Gateway") when referring to the service.

**Per-turn spend cap**:
Expand Down
16 changes: 8 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@

## 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 <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models. You state an outcome and set a budget. Franklin Agent decides what to call, what to pay for, and when to stop. No subscriptions, no seats, no rate limits.
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 <!-- br:models.chatVisible -->90<!-- /br:models.chatVisible --> models. You state an outcome and set a budget. Franklin Agent decides what to call, what to pay for, and when to stop. No subscriptions, no seats, no rate limits.

Funding it is your choice. Fund a **USDC wallet** and every paid action routes through the [x402](https://x402.org) micropayment protocol, settling on-chain against a wallet only you control — no signup, no account, the wallet is the identity. Or top up a **prepaid balance** at [user.blockrun.ai](https://user.blockrun.ai) and hand Franklin an API key. Same models, same tools, same agent. See [Two ways to pay](#two-ways-to-pay).

Expand Down Expand Up @@ -387,7 +387,7 @@ Every tool call is itemized. Every token is priced. When the wallet hits zero, F

## Smart Router

**<!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models. One decision. Zero guesswork.**
**<!-- br:models.chatVisible -->90<!-- /br:models.chatVisible --> models. One decision. Zero guesswork.**

You don't pick models. Franklin picks for you.

Expand Down Expand Up @@ -467,7 +467,7 @@ No email. No phone. No KYC. Your Solana, Base or Arc address is your account —
| -------------------------------------- | ---------------- | ----------------------- | -------------------- | ------------------------------- |
| **Spends money for you** | ❌ | ⚠️ you wire payments | ⚠️ trades only | ✅ **USDC wallet or prepaid key** |
| **Buys data + APIs + images + search** | ❌ | ⚠️ one key per service | ❌ | ✅ **one wallet pays for all** |
| Picks best model per task | ❌ single-vendor | ⚠️ you pick | ❌ | ✅ **Smart Router, <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models** |
| Picks best model per task | ❌ single-vendor | ⚠️ you pick | ❌ | ✅ **Smart Router, <!-- br:models.chatVisible -->90<!-- /br:models.chatVisible --> models** |
| **Money moves only on your approval** | — | ⚠️ build it yourself | ❌ runs on rules | ✅ **trade plan, every mode** |
| Spend guardrails | — | ⚠️ build it yourself | ⚠️ per-bot limits | ✅ **budget caps + hooks** |
| Works when a provider goes down | ❌ | ⚠️ if you code it | ❌ | ✅ **routes to another** |
Expand All @@ -494,14 +494,14 @@ Ask "what's BTC looking like?" — Franklin fetches live price data, computes RS
**🎨 AI image generation**
Ask "generate a logo" — Franklin calls DALL-E / GPT Image, saves the result locally, paid from your wallet.

**🧠 <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models via one wallet**
**🧠 <!-- br:models.chatVisible -->90<!-- /br:models.chatVisible --> models via one wallet**
Anthropic, OpenAI, Google, xAI, DeepSeek, GLM, Kimi, Minimax, plus a free tier. One wallet, one interface, automatic fallback.

**💳 x402 micropayments (YOPO)**
HTTP 402 native. Every paid action is a signed USDC micropayment — an EIP-712 authorization on Base and Arc, a signed SPL transfer on Solana. Non-custodial: your keys never leave your machine. YOPO: you pay only for outcomes.

**🧠 Learned model router**
Trained on 2M+ real requests. Classifies your task and picks the best model from <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> LLMs. Four profiles (auto/eco/premium/free). Adapts to your usage over time.
Trained on 2M+ real requests. Classifies your task and picks the best model from <!-- br:models.chatVisible -->90<!-- /br:models.chatVisible --> LLMs. Four profiles (auto/eco/premium/free). Adapts to your usage over time.

</td>
<td width="50%" valign="top">
Expand Down Expand Up @@ -581,13 +581,13 @@ Found a vulnerability? Please report it privately — see [SECURITY.md](SECURITY
│ Intent → Smart Router → Tool Use → Spend Control → Result │
├──────────────────────────────────────────────────────────────┤
│ Learned Router │
│ 2M+ requests · <!-- br:models.chatVisible@live -->88<!-- /br:models.chatVisible@live --> models · category detection · Elo scores │
│ 2M+ requests · <!-- br:models.chatVisible@live -->90<!-- /br:models.chatVisible@live --> models · category detection · Elo scores │
├──────────────────────────────────────────────────────────────┤
│ Agent Loop │
│ 60+ tools · Sessions · Compaction · Pricing · Plugin SDK │
├──────────────────────────────────────────────────────────────┤
│ BlockRun Gateway │
│ <!-- br:models.chatVisible@live -->88<!-- /br:models.chatVisible@live --> LLMs · CoinGecko · Search · Image APIs · paid services │
│ <!-- br:models.chatVisible@live -->90<!-- /br:models.chatVisible@live --> LLMs · CoinGecko · Search · Image APIs · paid services │
├──────────────────────────────────────────────────────────────┤
│ x402 Micropayment Protocol │
│ HTTP 402 · USDC on Solana, Base & Arc · signed payloads │
Expand Down Expand Up @@ -636,7 +636,7 @@ src/
├── stats/ Usage tracking + insights engine
├── ui/ Ink-based terminal UI
├── proxy/ Payment proxy for external tools
├── router/ Learned model router (<!-- br:models.chatVisible@live -->88<!-- /br:models.chatVisible@live --> models, Elo scoring)
├── router/ Learned model router (<!-- br:models.chatVisible@live -->90<!-- /br:models.chatVisible@live --> models, Elo scoring)
├── wallet/ Wallet management (Base/Arc + Solana)
├── mcp/ MCP server auto-discovery
└── commands/ CLI subcommands
Expand Down
12 changes: 6 additions & 6 deletions brand-numbers.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,23 +2,23 @@
"$schema": "https://blockrun.ai/brand/numbers.schema.json",
"version": 1,
"models": {
"chatVisible": 88,
"totalVisible": 115,
"chatVisible": 90,
"totalVisible": 117,
"free": 7,
"freeWithheld": 28,
"freeWithheld": 27,
"image": 12,
"video": 8,
"music": 1,
"speech": 5,
"soundfx": 1,
"withFallback": 28,
"withFallbackAllEntries": 68
"withFallback": 29,
"withFallbackAllEntries": 69
},
"clawrouter": {
"dimensions": 15,
"tiers": 4,
"profiles": 4,
"aliases": 276
"aliases": 295
},
"mcp": {
"tools": 19,
Expand Down
2 changes: 1 addition & 1 deletion docs/adr/0002-blockrun-gateway-as-aggregator.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

**Status:** accepted

Franklin makes every LLM and paid-tool call through a single counterparty — the BlockRun Gateway — instead of integrating directly with each model provider, image/video/audio service, search API, and market-data feed. The gateway aggregates <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models and a small set of paid APIs and accepts x402 uniformly.
Franklin makes every LLM and paid-tool call through a single counterparty — the BlockRun Gateway — instead of integrating directly with each model provider, image/video/audio service, search API, and market-data feed. The gateway aggregates <!-- br:models.chatVisible -->90<!-- /br:models.chatVisible --> models and a small set of paid APIs and accepts x402 uniformly.

## Considered options

Expand Down
2 changes: 1 addition & 1 deletion docs/anatomy-of-an-economic-agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -326,7 +326,7 @@ seamlessly.
│ signed USDC (HTTP 402)
▼
BlockRun Gateway
<!-- br:models.chatVisible@live -->88<!-- /br:models.chatVisible@live --> models / paid APIs
<!-- br:models.chatVisible@live -->90<!-- /br:models.chatVisible@live --> models / paid APIs
│
▼
User Wallet
Expand Down
4 changes: 2 additions & 2 deletions docs/why-ai-agents-need-a-wallet.md
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,7 @@ cheap models because cheapness is now something the agent can
agents both learn in real time.

**3. Single-vendor failure becomes a one-command swap.** A router
with <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models across every major provider can route around any
with <!-- br:models.chatVisible -->90<!-- /br:models.chatVisible --> models across every major provider can route around any
single vendor's bad release. The wallet doesn't know or care which
model answered — it only pays for the answer that arrived.

Expand All @@ -175,7 +175,7 @@ filled it.

Franklin is the reference implementation of the Economic Agent. It's
an AI agent CLI that holds USDC on Base or Solana, routes requests
across <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models, and settles every paid action in real time via
across <!-- br:models.chatVisible -->90<!-- /br:models.chatVisible --> models, and settles every paid action in real time via
the [x402](https://x402.org) HTTP-402 micropayment protocol. It is
Apache-2.0, written in TypeScript, and ships as one npm package.

Expand Down
Loading