@blockrun/clawrouter 0.12.270 → 0.12.272

package/README.md

@@ -444,11 +444,22 @@ Surf is BlockRun's unified crypto data API — **84 endpoints across 13 domains*
 
 ClawRouter ships Surf as a **skill, not as typed wrappers**. The proxy whitelists `/v1/surf/*` so any call through the local proxy is paid x402 from the same wallet; the agent reads `skills/surf/SKILL.md` for the endpoint catalog and crafts the HTTP call. No `blockrun_surf_*` tool definitions to maintain; a new Surf endpoint requires zero ClawRouter release.
 
-| Tier |       Cost | Examples                                                      |
-| ---- | ---------: | ------------------------------------------------------------- |
-| 1    | **$0.001** | prices, rankings, lists, news                                 |
-| 2    | **$0.005** | orderbooks, candles, search, wallet details, social mindshare |
-| 3    | **$0.020** | on-chain SQL / query / schema, chat completions               |
+**Flat per-call pricing** — every Surf endpoint costs the same. The old
+$0.001/$0.005/$0.020 tiers no longer apply; upstream prices all three tiers
+identically, and the tier now describes only endpoint weight.
+
+| Rail                        | Price per call                     |
+| --------------------------- | ---------------------------------- |
+| API key (`api.blockrun.ai`) | **$0.0075** (base rate, no tx fee) |
+| Wallet — Solana             | **$0.0075**                        |
+| Wallet — Base               | **$0.0085**                        |
+
+Measured 2026-09-05: the API-key rate from the account ledger, the wallet rates
+from the x402 challenge, which quotes the price before anything is signed. That
+quote is authoritative for the rail that issued it — the key rail issues no 402,
+and the wallet quote includes a transaction fee account credit does not pay, so
+the two are not interchangeable. Solana being cheaper than Base is deliberate
+(the $0.001 is Base's transaction fee), not drift.
 
 **Usage (HTTP):**
 
@@ -652,11 +663,36 @@ npx @blockrun/clawrouter
 **3. Check it, and switch back whenever**
 
 ```bash
-clawrouter status     # names the mode, the gateway, and the masked key
+clawrouter status     # names the mode, the gateway, the masked key and your credit
 clawrouter doctor     # verifies the key against the gateway (401 = revoked or mistyped)
+clawrouter reconcile  # diff your local usage journal against BlockRun's billing ledger
 clawrouter logout     # delete the key and go back to paying from the wallet
 ```
 
+**Checking your bill without opening a dashboard.** `clawrouter reconcile`
+compares what ClawRouter recorded locally against `GET /v1/usage` — BlockRun's
+authoritative ledger — joined on the gateway's own request id:
+
+```
+BlockRun reconciliation — last 7 days
+
+  Gateway charged:  $12.41   (438 settled calls)
+  Journal recorded: $12.41
+  Matched:          438, of which 0 disagree on amount
+```
+
+Three outcomes are worth acting on. **Amount mismatches** mean the local price
+table has drifted from the gateway's. **Charged but not in this machine's
+journal** is the one to look at hardest: money left the account for a call this
+machine did not make — expected if the same key is used on another machine or by
+another BlockRun product, and worth investigating if not. Exit code `2` in that
+case, so a scheduled check can alert on it. Rows still **pending pricing** are
+excluded from the totals rather than counted as $0.
+
+Your per-call sum will always be less than your card statement by exactly the
+top-up fees, which are charged at purchase and never appear as ledger rows. That
+gap is arithmetic, not a discrepancy.
+
 **Using it directly, without ClawRouter.** The same key works against
 `api.blockrun.ai` from any OpenAI or Anthropic SDK — `Authorization: Bearer` for
 OpenAI clients, `x-api-key` for Anthropic ones:
@@ -729,7 +765,7 @@ For basic usage, no configuration needed. For advanced options:
 | `BLOCKRUN_PROXY_PORT`       | `8402`                                | Local proxy port                                                                                                            |
 | `CLAWROUTER_DISABLED`       | `false`                               | Disable smart routing                                                                                                       |
 | `CLAWROUTER_DEBUG_HEADERS`  | `on`                                  | Set to `off` to suppress `x-clawrouter-*` debug response headers                                                            |
-| `CLAWROUTER_SOLANA_RPC_URL` | `https://api.mainnet-beta.solana.com` | Solana RPC endpoint                                                                                                         |
+| `CLAWROUTER_SOLANA_RPC_URL` | `https://api.mainnet-beta.solana.com` | Solana RPC endpoint — balance checks and payment signing                                                                    |
 
 **Full reference:** [docs/configuration.md](docs/configuration.md)