# Franklin Agent: a USDC wallet bolted to an AI agent

> BlockRun's TypeScript agent holds a Solana or Base USDC wallet and pays per action through x402. Here is what the README actually commits to, where the design gets awkward, and who should stay away.

**BlockRunAI/Franklin** — The AI agent with a wallet — spends USDC autonomously to get real work done. Apache-2.0, TypeScript.

- Repository: https://github.com/BlockRunAI/Franklin
- Website: https://franklin.run
- Stars: 558 · Forks: 56
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/blockrunai-franklin

## The problem Franklin Agent picks: an agent that cannot pay for anything

Most LLM agents can call tools you have already wired up and paid for. They cannot decide, mid-task, that a piece of live market data is worth two cents and buy it. The README frames this as the gap: "Other agents just talk." Franklin Agent's answer is to give the agent a USDC wallet and route every paid action through the x402 micropayment protocol, settling on-chain against a wallet the user controls. The wallet is the identity, so there is no signup and no account on that path.

The intended user is someone running autonomous work where the inputs have a price: trading research, market data, long-running goals that span sessions. The README names trading as the "flagship arena" and describes the agent buying live market data, proposing trade plans for approval before a cent moves, and keeping a wallet-bound trading journal. That approval step is the interesting design choice. The agent is autonomous in what it buys, not in what it commits to the market.

If your agent only needs to call an LLM and a couple of free APIs, the wallet machinery is dead weight. This is a tool for workflows where the marginal action has a real cost.

## Two payment rails and the YOPO pricing model

Franklin Agent has two funding routes that unlock the same catalogue. The first is a USDC wallet, created with franklin setup solana or franklin setup base, with no signup, credit card or phone verification. The second is a prepaid balance at user.blockrun.ai that yields an API key passed to franklin login. The README states either route unlocks the same thing: five dollars buys every frontier model and every paid tool in the BlockRun gateway.

The pricing model is called YOPO, You Only Pay Outcome. The README positions it against two alternatives: a subscription, which it describes as paying for access, and generic pay-per-call, which it describes as paying for trying. Franklin's claim is that you pay only for delivered work, at provider cost plus 5%, settled per action in USDC, with no monthly fees, rate limits or overdraft. The 5% is a flat markup, so cost scales linearly with usage rather than with seats.

That model has an obvious consequence the marketing copy does not dwell on. A long-running goal that buys a lot of data is a bill that grows with the agent's ambition. The budget and guardrail features exist precisely because the default failure mode of a spending agent is spending.

## Installing Franklin Agent and running the first paid action

Franklin ships as a single npm package, @blockrun/franklin, with a franklin binary. The README requires Node.js 20.19 or newer and recommends Node 22 LTS. It is explicit that older Node crashes at startup with ERR_REQUIRE_ESM, and calls this the number one cause of a crash on first run. Check the version before anything else.

```bash
node -v
npm install -g @blockrun/franklin
```

Running the bare command starts the agent on free models. The README says the free tier uses NVIDIA Nemotron and Qwen3 Coder out of the box, so you can evaluate the interface without funding anything.

```bash
franklin
```

To unlock paid models and paid APIs, pick one funding route. The wallet route needs no account; the balance command prints the address and USDC balance so you can confirm the deposit landed.

```bash
franklin setup solana
franklin balance
```

If you would rather not install globally, the README gives npx as an equivalent with no permissions and no -g flag.

```bash
npx @blockrun/franklin
```

If npm install fails with EACCES on /usr/local/lib/node_modules, the README is direct: do not use sudo. Either run through npx or move to a user-owned Node via nvm or fnm, installing Node 22 and reinstalling the package from there. That is the permanent fix for both the permissions error and the ESM crash.

## Where the wallet design gets uncomfortable

The wallet route is the part that deserves scrutiny. Franklin Agent holds a hot wallet that spends autonomously. The README's guardrail language (budgets, approval before a trade plan executes) is the mitigation, but the README does not document a rollback path for a payment that has already settled on-chain, and it does not describe key custody beyond the fact that the wallet is one you control. Anyone evaluating this should read the wallet and reservation code in src/ and test/ rather than trusting the pitch. The test list includes reservation.local.mjs and solana-migration.local.mjs, which suggests the project treats spending limits and wallet migration as first-class concerns, but a test file existing is not the same as a documented recovery procedure.

The second constraint is versioning. The package.json in the repository is at 3.46.0, and the desktop app is on 0.2.0-beta.3 as of 2026-09-03. A fast-moving 3.x with a beta GUI means the CLI surface can shift between releases. If you need a frozen interface, pin a version.

Third, the agent is broad by design: trading, research, image and video generation, a VS Code extension, a desktop app. The README markets 55+ providers and a smart router that picks the best model per task. Breadth here is a maintenance surface, and the repository layout reflects it, with apps/desktop as a workspace alongside src/ and a plugin SDK exported from the package.

## Franklin Agent versus a plain agent framework with your own API keys

The obvious alternative is a general agent framework where you supply provider keys and pay each vendor directly. The difference is where the billing and the model selection live. In that setup you manage N accounts, N keys and N billing relationships, and the agent cannot buy a capability you have not pre-provisioned. Franklin Agent collapses that into one balance and one gateway, and the agent can pay for a data source mid-task without you having set it up in advance.

The trade-off is the opposite of what you would expect. With your own keys you have a direct relationship with each provider, predictable per-token pricing and no intermediary markup. With Franklin you have one bill, one wallet and a 5% markup on provider cost, in exchange for not having to hold accounts with 55+ providers. If your agent uses two models and no paid data, the framework route is cheaper and simpler. The gateway only pays off once the number of paid capabilities grows past what you want to manage by hand.

A second, narrower alternative is the same agent without the wallet: Franklin's own API-key route. It needs an account at user.blockrun.ai but no crypto, and the README states it unlocks the same models and tools. If the wallet is the part you object to, the project already ships the version you want.

## Licence, upgrade cost and what the repository tells you about maintenance

Franklin Agent is Apache-2.0, and the repository carries a LICENSE file at the top level. Apache-2.0 is permissive with an explicit patent grant, which matters for a project that touches payment rails. The licence permits commercial use and modification. It does not grant you any rights to the BlockRun gateway service or to the USDC you fund; those are separate from the code. Nothing here is legal advice, and if you plan to redistribute a modified franklin binary you should read the LICENSE and NOTICE handling yourself.

The repository was not archived at the time of writing, and the last push was on 2026-09-09. The release cadence visible in the desktop line, three beta releases across 2026-09-01 to 2026-09-03, indicates active work on the GUI rather than a frozen CLI. The practical upgrade cost is the Node floor: staying on Node 20.19+ or 22 LTS is a prerequisite, not a preference, so an environment pinned to Node 18 cannot run this at all. The package also declares a workspace for apps/desktop, which means a source checkout pulls the desktop build into the same install.

## Conclusion

Adopt Franklin Agent if you already run an agent workflow and want per-action billing in USDC instead of a model subscription, and you are comfortable with Node 20.19+ plus a funded wallet or a blockrun.ai key. Do not adopt it if you need a stable API surface, because the package is at 3.46.0 with a desktop client still in beta, or if you cannot hold a hot wallet. Verify first that your Node version is 20.19 or newer with node -v, that ~/.blockrun/ is where you want session history to live, and that the 5% markup over provider cost is acceptable for your volume.

## FAQ

### What is Franklin Agent from BlockRun?

It is a TypeScript AI agent that holds a USDC wallet and spends it on paid models and APIs to complete tasks. The README describes it as an autonomous economic agent with trading as its flagship use case, distributed as the npm package @blockrun/franklin.

### How do I install Franklin Agent?

Install it globally with npm install -g @blockrun/franklin, or run npx @blockrun/franklin without a global install. The README requires Node.js 20.19 or newer and recommends Node 22 LTS.

### Does Franklin Agent need a crypto wallet to work?

No. The README gives two funding routes: a USDC wallet created with franklin setup solana or franklin setup base, or a prepaid balance at user.blockrun.ai that yields an API key for franklin login. Either route unlocks the same models and tools.

### Why does Franklin Agent crash with ERR_REQUIRE_ESM on first run?

The README attributes this to running Node older than 20.19, because Franklin's Solana dependencies need the require(esm) support added in that version. It calls this the number one cause of a crash on first run and recommends upgrading to Node 20.19+ or 22 LTS.

## Sources

- [BlockRunAI/Franklin on GitHub](https://github.com/BlockRunAI/Franklin)
- [License: Apache-2.0](https://github.com/BlockRunAI/Franklin/blob/main/LICENSE)
- [Project website](https://franklin.run)
- [README](https://github.com/BlockRunAI/Franklin/blob/main/README.md)
- [Releases](https://github.com/BlockRunAI/Franklin/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/blockrunai-franklin