feat: support BlockRun account API billing

.env.example

@@ -1,9 +1,13 @@
 # Franklin.bet — generator config
 #
 # The generator (scripts/generate.mjs) calls the BlockRun gateway through the
-# @blockrun/llm SDK. Your wallet signature is your auth — no API keys.
+# @blockrun/llm SDK. Recommended: create an account at https://user.blockrun.ai,
+# add credits, then create a key at https://user.blockrun.ai/dashboard/keys.
+BLOCKRUN_API_KEY=
+# BLOCKRUN_API_BASE_URL=https://api.blockrun.ai
 
-# Base-chain wallet private key used to sign x402 micropayments.
+# Wallet fallback. Solana is recommended through Franklin agent mode; chat mode
+# currently accepts the Base x402 key below.
 # The flagship council models are paid (a few $0.001 calls per run).
 # Leave unset and run `npm run generate:free` to use the free NVIDIA tier instead.
 BASE_CHAIN_WALLET_KEY=

.github/workflows/predict-upcoming.yml

@@ -4,8 +4,7 @@ name: Predict upcoming matches
 # next ~3 days that aren't predicted yet — i.e. each match gets its prediction
 # JSON a couple of days before kickoff. Commits data/predictions.json.
 #
-# Requires repo secret BASE_CHAIN_WALLET_KEY (funded Base wallet). Agent mode also
-# needs the Franklin CLI with `franklin predict` (installed below).
+# Recommended repo secret: BLOCKRUN_API_KEY. A funded x402 wallet remains a fallback.
 
 on:
   workflow_dispatch:
@@ -39,6 +38,7 @@ jobs:
         run: npm install -g @blockrun/franklin
       - name: Generate predictions for upcoming matches
         env:
+          BLOCKRUN_API_KEY: ${{ secrets.BLOCKRUN_API_KEY }}
           BASE_CHAIN_WALLET_KEY: ${{ secrets.BASE_CHAIN_WALLET_KEY }}
           FRANKLIN_CMD: franklin
           UPCOMING: ${{ github.event.inputs.upcoming || '3' }}

.github/workflows/refresh.yml

@@ -4,10 +4,8 @@ name: Refresh predictions
 # does), it re-runs the council against the events, commits the updated
 # data/predictions.json, and pushes — which your static host redeploys.
 #
-# Required repo secret:
-#   BASE_CHAIN_WALLET_KEY — a funded Base wallet private key (0x…). Used by both
-#   the chat engine (@blockrun/llm) and the agent engine (Franklin). Keep it a
-#   secret; never commit it.
+# Recommended repo secret: BLOCKRUN_API_KEY. Create it at user.blockrun.ai.
+# BASE_CHAIN_WALLET_KEY remains available for the legacy x402 wallet flow.
 
 on:
   workflow_dispatch:
@@ -55,6 +53,7 @@ jobs:
 
       - name: Generate predictions
         env:
+          BLOCKRUN_API_KEY: ${{ secrets.BLOCKRUN_API_KEY }}
           BASE_CHAIN_WALLET_KEY: ${{ secrets.BASE_CHAIN_WALLET_KEY }}
           FRANKLIN_CMD: franklin
           ENGINE: ${{ inputs.engine }}

CONTRIBUTING.md

@@ -65,15 +65,15 @@ npm run generate:free                  # zero-USDC NVIDIA tier (chat)
 ```
 
 Agent mode needs the `franklin` CLI on PATH (`npm i -g @blockrun/franklin`) or
-`FRANKLIN_CMD` pointing at a local build, plus a funded wallet.
+`FRANKLIN_CMD` pointing at a local build, plus `BLOCKRUN_API_KEY` or a funded wallet.
 
-## Wallet & secrets
+## Billing & secrets
 
-- Generation is authenticated by an x402 wallet signature — no API keys.
-- Provide it via `BASE_CHAIN_WALLET_KEY` (env or CI secret) or the local
-  `~/.blockrun/.session` wallet (auto-discovered).
-- **Never commit a private key or `.env`.** They are gitignored. CI reads the
-  key from the `BASE_CHAIN_WALLET_KEY` repo secret.
+- Recommended: register at https://user.blockrun.ai, add credits, create an API key,
+  and set `BLOCKRUN_API_KEY` locally or as a CI secret.
+- x402 wallet fallback supports Solana through Franklin agent mode, then Base via
+  `BASE_CHAIN_WALLET_KEY` or the local session wallet.
+- **Never commit an API key, private key, or `.env`.** They are gitignored.
 
 ## Running locally
 

README.md

@@ -10,9 +10,9 @@ upset calls, and **how each model did its research before committing**.
 
 It's a marketing gimmick with a point: in grounded mode every prediction is a
 real agent that searches the live web for form and team news, reads
-prediction-market odds, and pays per call in USDC via x402 through one BlockRun
+prediction-market odds, and pays per call through the BlockRun account API or in USDC via x402 through one BlockRun
 endpoint. The whole pipeline is **open-source and reproducible** — anyone can
-re-run it with their own wallet. The site *is* the demo.
+re-run it with their own API key or wallet. The site *is* the demo.
 
 English-first, with Chinese accents. Fixtures are **curated by maintainers**;
 the site takes no user input. Built on [Franklin](https://blockrun.ai) ×
@@ -74,17 +74,18 @@ npm run dev        # → http://localhost:4173
 The data pipeline is fully open. There are two ways the `data/predictions.json`
 the site renders can be produced — and **anyone can run either**:
 
-- **The canonical site** is refreshed server-side (the GitHub Action below) using
-  the project's own funded wallet, then committed and redeployed.
-- **You** can fork the repo, point it at **your own wallet**, and regenerate the
-  exact same way. Every model call is metered on-chain via x402, so the cost and
-  provenance are transparent. Because grounded runs use live web search and model
+- **The canonical site** is refreshed server-side using a BlockRun account API key,
+  then committed and redeployed.
+- **You** can fork the repo, register at [user.blockrun.ai](https://user.blockrun.ai),
+  add [credits](https://user.blockrun.ai/dashboard/credits), create an
+  [API key](https://user.blockrun.ai/dashboard/keys), and regenerate the same way.
+  The x402 wallet flow remains available. Because grounded runs use live web search and model
   sampling, you reproduce the **method**, not bit-identical output — that's
   expected for forecasting.
 
 ```bash
 npm run seed                          # 0) zero-USDC placeholder data to render
-export BASE_CHAIN_WALLET_KEY=0x...     # your funded Base wallet (or ~/.blockrun/.session)
+export BLOCKRUN_API_KEY=brk_...         # recommended account billing
 npm run generate -- --agent           # 1) grounded: each model researches + bets
 npm run generate -- --agent --event wc26-arg-nga   # one match, merged in
 npm run generate:free                 # zero-USDC NVIDIA tier (chat engine)
@@ -123,8 +124,8 @@ npm run add-event -- "Who wins Euro 2028?" --generate                      # app
 
 `.github/workflows/refresh.yml` lets a maintainer trigger a regenerate from the
 Actions tab (choose `chat`/`agent`, optional single event), commits the updated
-`predictions.json`, and pushes — your static host redeploys. Set the
-`BASE_CHAIN_WALLET_KEY` repo secret first. A weekly schedule is included
+`predictions.json`, and pushes — your static host redeploys. Set the `BLOCKRUN_API_KEY` repo secret first. Wallet fallback order is Solana, then Base;
+agent mode inherits either wallet from Franklin while chat mode supports the Base wallet. A weekly schedule is included
 (commented out — agent mode spends real USDC).
 
 ## Deploy on a BlockRun subdomain

index.html

@@ -105,10 +105,10 @@ <h3 data-en="Each AI researches the match" data-es="Cada IA investiga el partido
         <div class="how-card">
           <div class="how-num">02</div>
           <h3 data-en="Pay-per-call, no keys" data-es="Pago por llamada, sin claves" data-zh="按次付费，无需密钥" data-ja="従量課金、APIキー不要">Pay-per-call, no keys</h3>
-          <p data-en="Every prediction is metered calls settled in USDC via the x402 protocol — one BlockRun endpoint, no subscriptions, no API keys. The whole pipeline is open-source and reproducible with your own wallet."
-             data-es="Cada predicción son llamadas medidas y liquidadas en USDC vía el protocolo x402: un único endpoint de BlockRun, sin suscripciones ni claves API. Todo el pipeline es de código abierto y reproducible con tu propia cartera."
-             data-zh="每条预测都是按次计费、通过 x402 协议用 USDC 结算的调用——一个 BlockRun 端点，无订阅、无 API 密钥。整套流程开源，可用你自己的钱包复现。"
-             data-ja="各予測は x402 プロトコルで USDC 決済される従量課金の呼び出しです。BlockRun の単一エンドポイントで、サブスクや API キーは不要。パイプライン全体がオープンソースで、自分のウォレットで再現できます。">Metered USDC calls via x402.</p>
+          <p data-en="Every prediction is a metered call billed through the BlockRun account API or settled in USDC via x402. The open-source pipeline is reproducible with your own API key or wallet."
+             data-es="Cada predicción es una llamada medida, facturada por la API de BlockRun o liquidada en USDC vía x402. El pipeline abierto se reproduce con tu clave API o cartera."
+             data-zh="每条预测都按次计费，可使用 BlockRun 账户 API，或通过 x402 以 USDC 结算。整套流程开源，可用自己的 API 密钥或钱包复现。"
+             data-ja="各予測は BlockRun アカウント API、または x402 の USDC 決済による従量課金です。オープンソースのパイプラインは自分の API キーまたはウォレットで再現できます。">Account API or metered USDC calls via x402.</p>
         </div>
         <div class="how-card">
           <div class="how-num">03</div>