@blockrun/llm 3.3.0 → 3.5.0

package/README.md

@@ -165,15 +165,59 @@ const tweet = await client.chat('xai/grok-3-mini', 'What is trending on X?', { s
 **Supported endpoint:** `https://sol.blockrun.ai/api`
 **Payment:** Solana USDC (SPL, mainnet)
 
-## How It Works
+## How Payment Works
 
-1. You send a request to BlockRun's API
-2. The API returns a 402 Payment Required with the price
-3. The SDK automatically signs a USDC payment on Base
-4. The request is retried with the payment proof
-5. You receive the AI response
+No API keys, no subscription. You hold USDC in your own wallet, and **every request pays for itself** with an on-chain micropayment. Two phases:
 
-**Your private key never leaves your machine** - it's only used for local signing.
+### Phase 1 — Fund your wallet once
+
+You only do this when your balance runs low. Three ways to get USDC into your wallet:
+
+- **(a) Buy with a card (Base USDC).** Call the new `onramp()` method to mint a one-time Coinbase Onramp link, then open the returned `pay.coinbase.com` URL — pay by card/bank in 60+ fiat currencies and the USDC lands in your wallet. The call itself is **free**. Onramp is **Base-only** (buying USDC with a card always lands Base USDC), and the funding address must equal your signing wallet:
+
+  ```typescript
+  const { url } = await client.onramp(client.getWalletAddress());
+  console.log(`Fund your wallet: ${url}`);  // single-use, expires ~5 min — mint at click time
+  ```
+
+- **(b) Transfer existing USDC.** Send USDC you already hold to your wallet address (`client.getWalletAddress()`). On Base, send Base USDC; on Solana (`SolanaLLMClient`), send Solana SPL USDC.
+
+- **(c) Skip funding entirely.** Use the free NVIDIA models (e.g. `nvidia/deepseek-v4-flash`) — every call is **$0**, no balance required.
+
+$5 of USDC covers thousands of paid requests. Check your balance any time:
+
+```typescript
+const balance = await client.getBalance();        // USDC on Base
+console.log(`Balance: $${balance.toFixed(2)} USDC`);
+```
+
+### Phase 2 — Every request pays itself (automatic x402)
+
+You just call e.g. `client.chat(...)` — the payment is invisible:
+
+1. You send a request to BlockRun's API.
+2. The gateway returns **402 Payment Required** with the price.
+3. The SDK signs a USDC payment **locally** (EIP-712) — on **Base** for `LLMClient`, on **Solana** for `SolanaLLMClient` — using your wallet key.
+4. The request is retried automatically with the payment proof.
+5. The gateway settles on-chain and returns the AI response.
+
+One call, no separate pay step. Free NVIDIA models settle at **$0** (no payment signed).
+
+### Track spend and verify settlements
+
+```typescript
+import { getCostSummary } from '@blockrun/llm';
+
+const spent = client.getSpending();               // this session
+console.log(`Spent $${spent.totalUsd.toFixed(4)} across ${spent.calls} calls`);
+
+const summary = getCostSummary();                  // across sessions (~/.blockrun/data/costs.jsonl)
+console.log(`Lifetime: $${summary.totalUsd.toFixed(2)} over ${summary.calls} calls`);
+```
+
+Every paid request is a real on-chain USDC transfer — look up your wallet address on [Basescan](https://basescan.org) (or a Solana explorer) to verify each settlement independently.
+
+**Non-custodial by design: your private key never leaves your machine** — it is only used for local signing, and no funds are ever held by BlockRun.
 
 ## Smart Routing (ClawRouter)
 
@@ -298,6 +342,7 @@ Released 2026-04-23 — first fully retrained base since GPT-4.5. 1M context, 12
 ### Anthropic Claude
 | Model | Input Price | Output Price | Context | Notes |
 |-------|-------------|--------------|---------|-------|
+| `anthropic/claude-fable-5` | $10.00/M | $50.00/M | **1M** | Mythos-class flagship above Opus — always-on thinking, 128K output, fallback `claude-opus-4.8`. Alias: `claude-fable-5` |
 | `anthropic/claude-opus-4.8` | $5.00/M | $25.00/M | **1M** | Flagship — agentic coding + adaptive thinking, 128K output |
 | `anthropic/claude-opus-4.7` | $5.00/M | $25.00/M | **1M** | Agentic coding + adaptive thinking, 128K output |
 | `anthropic/claude-opus-4.6` | $5.00/M | $25.00/M | 200K | Hidden but still callable — kept as in-family hot-swap fallback |
@@ -1320,7 +1365,7 @@ const gptResponse = await client.messages.create({
 });
 ```
 
-The `AnthropicClient` wraps the official `@anthropic-ai/sdk` with a custom fetch that handles x402 payment automatically. Your private key never leaves your machine.
+The `AnthropicClient` wraps the official `@anthropic-ai/sdk` with a custom fetch that handles x402 payment automatically. Your private key never leaves your machine. The Mythos-class `claude-fable-5` alias is available here too (1M context, always-on thinking).
 
 ## Links
 

package/dist/index.cjs

@@ -544,7 +544,17 @@ function mapRawToImageModel(m) {
 }
 var DEFAULT_API_URL = "https://blockrun.ai/api";
 var DEFAULT_MAX_TOKENS = 1024;
-var DEFAULT_TIMEOUT = 6e4;
+function resolveDefaultTimeout() {
+  const envVal = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_CHAT_TIMEOUT : void 0;
+  if (envVal !== void 0) {
+    const seconds = Number(envVal);
+    if (Number.isFinite(seconds) && seconds > 0) {
+      return seconds * 1e3;
+    }
+  }
+  return 6e5;
+}
+var DEFAULT_TIMEOUT = resolveDefaultTimeout();
 var SDK_VERSION = "1.5.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 var LLMClient = class _LLMClient {
@@ -1581,6 +1591,40 @@ var LLMClient = class _LLMClient {
     const data = await this.requestWithPaymentRaw("/v1/exa/find-similar", body);
     return data.data;
   }
+  /**
+   * Mint a one-time Coinbase Onramp link to fund this wallet with USDC on Base.
+   *
+   * FREE — the x402 signature only authenticates the wallet (no payment is
+   * charged). Because the funding address must equal the signing wallet, this
+   * mints a `pay.coinbase.com` link prefilled for `address` so a card/bank can
+   * top it up (60+ fiat currencies → Base USDC). Base / USDC only.
+   *
+   * The returned URL is single-use and expires in ~5 minutes — mint it at click
+   * time and never cache it. The funding `address` must match the signing wallet.
+   *
+   * @param address - Destination Base wallet address (0x + 40 hex chars). Must
+   *                  equal the signing wallet that funds it.
+   * @returns `{ url }` — a one-time https://pay.coinbase.com/... link.
+   *
+   * @example
+   * const { url } = await client.onramp(client.getWalletAddress());
+   * console.log(`Fund your wallet: ${url}`);
+   */
+  async onramp(address) {
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+      throw new Error("address must be a 0x-prefixed 40-hex-character Base address");
+    }
+    const data = await this.requestWithPaymentRaw("/v1/onramp/token", {
+      address,
+      network: "base",
+      asset: "USDC"
+    });
+    const url = typeof data.url === "string" ? data.url : "";
+    if (!url.startsWith("https://pay.coinbase.com/")) {
+      throw new APIError("gateway returned no onramp url", 502, { message: "gateway returned no onramp url" });
+    }
+    return { url };
+  }
   /**
    * Get USDC balance on Base mainnet.
    *
@@ -5770,7 +5814,7 @@ var OpenAI = class {
   constructor(options = {}) {
     const privateKey = options.walletKey || options.privateKey;
     const apiUrl = options.baseURL || "https://blockrun.ai/api";
-    const timeout = options.timeout || 6e4;
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
     this.client = new LLMClient({
       privateKey,
       apiUrl,
@@ -5804,7 +5848,7 @@ var AnthropicClient = class {
     const apiUrl = options.apiUrl ?? "https://blockrun.ai/api";
     validateApiUrl(apiUrl);
     this._apiUrl = apiUrl.replace(/\/$/, "");
-    this._timeout = options.timeout ?? 6e4;
+    this._timeout = options.timeout ?? DEFAULT_TIMEOUT;
   }
   async _getClient() {
     if (this._client) return this._client;

package/dist/index.d.cts

@@ -245,7 +245,7 @@ interface LLMClientOptions {
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
     apiUrl?: string;
-    /** Request timeout in milliseconds (default: 60000) */
+    /** Request timeout in milliseconds (default: 600000 / 600s; override via BLOCKRUN_CHAT_TIMEOUT env, in seconds) */
     timeout?: number;
 }
 /**
@@ -727,6 +727,10 @@ interface ExaFindSimilarOptions {
     /** Exclude pages from the same domain as the reference URL */
     excludeSourceDomain?: boolean;
 }
+interface OnrampResult {
+    /** One-time https://pay.coinbase.com/... URL prefilled for this wallet. */
+    url: string;
+}
 type PriceCategory = "crypto" | "fx" | "commodity" | "usstock" | "stocks";
 type StockMarket = "us" | "hk" | "jp" | "kr" | "gb" | "de" | "fr" | "nl" | "ie" | "lu" | "cn" | "ca";
 type BarResolution = "1" | "5" | "15" | "60" | "240" | "D" | "W" | "M";
@@ -806,7 +810,7 @@ interface PhoneClientOptions {
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
     apiUrl?: string;
-    /** Request timeout in milliseconds (default: 60000) */
+    /** Request timeout in milliseconds (default: 600000 / 600s; override via BLOCKRUN_CHAT_TIMEOUT env, in seconds) */
     timeout?: number;
 }
 /**
@@ -875,7 +879,7 @@ interface PortraitClientOptions {
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
     apiUrl?: string;
-    /** Request timeout in milliseconds (default: 60000) */
+    /** Request timeout in milliseconds (default: 600000 / 600s; override via BLOCKRUN_CHAT_TIMEOUT env, in seconds) */
     timeout?: number;
 }
 interface PortraitEnrollOptions {
@@ -1220,6 +1224,26 @@ declare class LLMClient {
      * @param options - Optional filters (numResults, excludeSourceDomain)
      */
     exaFindSimilar(url: string, options?: ExaFindSimilarOptions): Promise<ExaSearchResponse>;
+    /**
+     * Mint a one-time Coinbase Onramp link to fund this wallet with USDC on Base.
+     *
+     * FREE — the x402 signature only authenticates the wallet (no payment is
+     * charged). Because the funding address must equal the signing wallet, this
+     * mints a `pay.coinbase.com` link prefilled for `address` so a card/bank can
+     * top it up (60+ fiat currencies → Base USDC). Base / USDC only.
+     *
+     * The returned URL is single-use and expires in ~5 minutes — mint it at click
+     * time and never cache it. The funding `address` must match the signing wallet.
+     *
+     * @param address - Destination Base wallet address (0x + 40 hex chars). Must
+     *                  equal the signing wallet that funds it.
+     * @returns `{ url }` — a one-time https://pay.coinbase.com/... link.
+     *
+     * @example
+     * const { url } = await client.onramp(client.getWalletAddress());
+     * console.log(`Fund your wallet: ${url}`);
+     */
+    onramp(address: string): Promise<OnrampResult>;
     /**
      * Get USDC balance on Base mainnet.
      *

package/dist/index.d.ts

@@ -245,7 +245,7 @@ interface LLMClientOptions {
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
     apiUrl?: string;
-    /** Request timeout in milliseconds (default: 60000) */
+    /** Request timeout in milliseconds (default: 600000 / 600s; override via BLOCKRUN_CHAT_TIMEOUT env, in seconds) */
     timeout?: number;
 }
 /**
@@ -727,6 +727,10 @@ interface ExaFindSimilarOptions {
     /** Exclude pages from the same domain as the reference URL */
     excludeSourceDomain?: boolean;
 }
+interface OnrampResult {
+    /** One-time https://pay.coinbase.com/... URL prefilled for this wallet. */
+    url: string;
+}
 type PriceCategory = "crypto" | "fx" | "commodity" | "usstock" | "stocks";
 type StockMarket = "us" | "hk" | "jp" | "kr" | "gb" | "de" | "fr" | "nl" | "ie" | "lu" | "cn" | "ca";
 type BarResolution = "1" | "5" | "15" | "60" | "240" | "D" | "W" | "M";
@@ -806,7 +810,7 @@ interface PhoneClientOptions {
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
     apiUrl?: string;
-    /** Request timeout in milliseconds (default: 60000) */
+    /** Request timeout in milliseconds (default: 600000 / 600s; override via BLOCKRUN_CHAT_TIMEOUT env, in seconds) */
     timeout?: number;
 }
 /**
@@ -875,7 +879,7 @@ interface PortraitClientOptions {
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
     apiUrl?: string;
-    /** Request timeout in milliseconds (default: 60000) */
+    /** Request timeout in milliseconds (default: 600000 / 600s; override via BLOCKRUN_CHAT_TIMEOUT env, in seconds) */
     timeout?: number;
 }
 interface PortraitEnrollOptions {
@@ -1220,6 +1224,26 @@ declare class LLMClient {
      * @param options - Optional filters (numResults, excludeSourceDomain)
      */
     exaFindSimilar(url: string, options?: ExaFindSimilarOptions): Promise<ExaSearchResponse>;
+    /**
+     * Mint a one-time Coinbase Onramp link to fund this wallet with USDC on Base.
+     *
+     * FREE — the x402 signature only authenticates the wallet (no payment is
+     * charged). Because the funding address must equal the signing wallet, this
+     * mints a `pay.coinbase.com` link prefilled for `address` so a card/bank can
+     * top it up (60+ fiat currencies → Base USDC). Base / USDC only.
+     *
+     * The returned URL is single-use and expires in ~5 minutes — mint it at click
+     * time and never cache it. The funding `address` must match the signing wallet.
+     *
+     * @param address - Destination Base wallet address (0x + 40 hex chars). Must
+     *                  equal the signing wallet that funds it.
+     * @returns `{ url }` — a one-time https://pay.coinbase.com/... link.
+     *
+     * @example
+     * const { url } = await client.onramp(client.getWalletAddress());
+     * console.log(`Fund your wallet: ${url}`);
+     */
+    onramp(address: string): Promise<OnrampResult>;
     /**
      * Get USDC balance on Base mainnet.
      *

package/dist/index.js

@@ -437,7 +437,17 @@ function mapRawToImageModel(m) {
 }
 var DEFAULT_API_URL = "https://blockrun.ai/api";
 var DEFAULT_MAX_TOKENS = 1024;
-var DEFAULT_TIMEOUT = 6e4;
+function resolveDefaultTimeout() {
+  const envVal = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_CHAT_TIMEOUT : void 0;
+  if (envVal !== void 0) {
+    const seconds = Number(envVal);
+    if (Number.isFinite(seconds) && seconds > 0) {
+      return seconds * 1e3;
+    }
+  }
+  return 6e5;
+}
+var DEFAULT_TIMEOUT = resolveDefaultTimeout();
 var SDK_VERSION = "1.5.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 var LLMClient = class _LLMClient {
@@ -1474,6 +1484,40 @@ var LLMClient = class _LLMClient {
     const data = await this.requestWithPaymentRaw("/v1/exa/find-similar", body);
     return data.data;
   }
+  /**
+   * Mint a one-time Coinbase Onramp link to fund this wallet with USDC on Base.
+   *
+   * FREE — the x402 signature only authenticates the wallet (no payment is
+   * charged). Because the funding address must equal the signing wallet, this
+   * mints a `pay.coinbase.com` link prefilled for `address` so a card/bank can
+   * top it up (60+ fiat currencies → Base USDC). Base / USDC only.
+   *
+   * The returned URL is single-use and expires in ~5 minutes — mint it at click
+   * time and never cache it. The funding `address` must match the signing wallet.
+   *
+   * @param address - Destination Base wallet address (0x + 40 hex chars). Must
+   *                  equal the signing wallet that funds it.
+   * @returns `{ url }` — a one-time https://pay.coinbase.com/... link.
+   *
+   * @example
+   * const { url } = await client.onramp(client.getWalletAddress());
+   * console.log(`Fund your wallet: ${url}`);
+   */
+  async onramp(address) {
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+      throw new Error("address must be a 0x-prefixed 40-hex-character Base address");
+    }
+    const data = await this.requestWithPaymentRaw("/v1/onramp/token", {
+      address,
+      network: "base",
+      asset: "USDC"
+    });
+    const url = typeof data.url === "string" ? data.url : "";
+    if (!url.startsWith("https://pay.coinbase.com/")) {
+      throw new APIError("gateway returned no onramp url", 502, { message: "gateway returned no onramp url" });
+    }
+    return { url };
+  }
   /**
    * Get USDC balance on Base mainnet.
    *
@@ -5663,7 +5707,7 @@ var OpenAI = class {
   constructor(options = {}) {
     const privateKey = options.walletKey || options.privateKey;
     const apiUrl = options.baseURL || "https://blockrun.ai/api";
-    const timeout = options.timeout || 6e4;
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
     this.client = new LLMClient({
       privateKey,
       apiUrl,
@@ -5697,7 +5741,7 @@ var AnthropicClient = class {
     const apiUrl = options.apiUrl ?? "https://blockrun.ai/api";
     validateApiUrl(apiUrl);
     this._apiUrl = apiUrl.replace(/\/$/, "");
-    this._timeout = options.timeout ?? 6e4;
+    this._timeout = options.timeout ?? DEFAULT_TIMEOUT;
   }
   async _getClient() {
     if (this._client) return this._client;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "type": "module",
   "description": "BlockRun SDK - Pay-per-request AI (LLM, Image, Video, Music, Voice) via x402 on Base and Solana",
   "main": "dist/index.cjs",