@blockrun/llm 3.13.6 → 3.14.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +95 -33
  2. package/dist/index.cjs +683 -319
  3. package/dist/index.d.cts +133 -469
  4. package/dist/index.d.ts +133 -469
  5. package/dist/index.js +680 -319
  6. package/package.json +11 -8
package/README.md CHANGED
@@ -5,7 +5,7 @@
5
5
  ### Cut your LLM bill by <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->%. One line of TypeScript.
6
6
 
7
7
  The smart-routing SDK for <!-- br:models.chatVisible -->74<!-- /br:models.chatVisible --> models — every request goes to the cheapest model that can handle it,
8
- paid per-request in USDC. No API keys. No subscriptions. No vendor lock-in.
8
+ paid with an API key or per-request USDC on Solana or Base. No vendor lock-in.
9
9
 
10
10
  [![npm](https://img.shields.io/npm/v/@blockrun/llm.svg?style=flat-square)](https://www.npmjs.com/package/@blockrun/llm)
11
11
  [![npm downloads](https://img.shields.io/npm/dm/@blockrun/llm.svg?style=flat-square)](https://www.npmjs.com/package/@blockrun/llm)
@@ -14,12 +14,13 @@ paid per-request in USDC. No API keys. No subscriptions. No vendor lock-in.
14
14
  [![Node](https://img.shields.io/badge/Node-%E2%89%A520-brightgreen?style=flat-square&logo=node.js&logoColor=white)](package.json)
15
15
  [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white)](tsconfig.json)
16
16
 
17
- [![Base Network](https://img.shields.io/badge/Base-USDC-0052FF?style=flat-square&logo=coinbase&logoColor=white)](https://base.org)
17
+ [![API Key](https://img.shields.io/badge/API%20Key-user.blockrun.ai-2ea44f?style=flat-square)](https://user.blockrun.ai)
18
18
  [![Solana](https://img.shields.io/badge/Solana-USDC-9945FF?style=flat-square&logo=solana&logoColor=white)](https://solana.com)
19
+ [![Base Network](https://img.shields.io/badge/Base-USDC-0052FF?style=flat-square&logo=coinbase&logoColor=white)](https://base.org)
19
20
  [![x402](https://img.shields.io/badge/x402-micropayments-orange?style=flat-square)](https://x402.org)
20
21
  [![Telegram](https://img.shields.io/badge/Telegram-Community-26A5E4?style=flat-square&logo=telegram)](https://t.me/blockrunAI)
21
22
 
22
- [Website](https://blockrun.ai) · [Models & Pricing](https://blockrun.ai/models) · [ClawRouter](https://github.com/BlockRunAI/ClawRouter) · [Python SDK](https://github.com/BlockRunAI/blockrun-llm) · [Telegram](https://t.me/blockrunAI)
23
+ [Sign up / Get an API key](https://user.blockrun.ai) · [Website](https://blockrun.ai) · [Models & Pricing](https://blockrun.ai/models) · [ClawRouter](https://github.com/BlockRunAI/ClawRouter) · [Python SDK](https://github.com/BlockRunAI/blockrun-llm) · [Telegram](https://t.me/blockrunAI)
23
24
 
24
25
  </div>
25
26
 
@@ -28,6 +29,8 @@ paid per-request in USDC. No API keys. No subscriptions. No vendor lock-in.
28
29
  ```typescript
29
30
  import { LLMClient } from '@blockrun/llm';
30
31
 
32
+ // Reads BLOCKRUN_API_KEY (sign up at https://user.blockrun.ai),
33
+ // or a wallet key if you'd rather pay per request in USDC.
31
34
  const client = new LLMClient();
32
35
 
33
36
  const r = await client.smartChat('Prove step by step that the sum of two odd integers is even.');
@@ -42,22 +45,22 @@ console.log(r.response); // the proof
42
45
 
43
46
  - 🧠 **Smart routing that pays for itself** — the bundled [Router Core V3](https://github.com/BlockRunAI/router-core) engine (shared with [ClawRouter](https://github.com/BlockRunAI/ClawRouter)) classifies every request locally in <1ms across <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions --> dimensions and routes to the cheapest capable model. The main event.
44
47
  - 🆓 **<!-- br:models.free -->7<!-- /br:models.free --> genuinely free models** — $0 in and out, incl. two 1M-context Nemotrons, a multimodal one, and free coding models from Cohere and Poolside. No rate-limit gimmicks.
45
- - 🔐 **No API keys** — your wallet signature is your authentication. No accounts, no dashboards, no key rotation.
46
- - 💸 **Pay per request in USDC** — x402 micropayments on Base or Solana. $5 covers thousands of requests; agents can pay their own way.
48
+ - 🔐 **Two ways to connect** — a **BlockRun API key** billed against account credit ([sign up at user.blockrun.ai](https://user.blockrun.ai), [create a key](https://user.blockrun.ai/dashboard/keys), [add credit](https://user.blockrun.ai/dashboard/credits)), or a wallet signature with x402 micropayments and no account at all. Same code either way.
49
+ - 💸 **Pay per request in USDC** — x402 micropayments on Solana or Base. $5 covers thousands of requests; agents can pay their own way.
47
50
  - 🛡️ **Automatic failover** — transient errors (timeouts, 429, 5xx) walk the router's ranked fallback chain instead of failing your request.
48
51
  - ⚡ **Streaming, OpenAI & Anthropic compat** — drop-in `chat.completions` / `messages` layers, SSE streaming, strict TypeScript.
49
- - 🎨 **Beyond chat** — image, video, music, speech, live search, prediction markets, crypto data, and 40-chain RPC through the same wallet.
52
+ - 🎨 **Beyond chat** — image, video, music, speech, live search, prediction markets, crypto data, and 40-chain RPC through the same API key or wallet.
50
53
 
51
54
  ## How It Compares
52
55
 
53
56
  | | OpenAI SDK | OpenRouter | LiteLLM | **@blockrun/llm** |
54
57
  | ------------------ | -------------- | ----------------- | ---------------- | ----------------------------------------------------------------------- |
55
58
  | **Cost routing** | ✗ one vendor | Manual selection | Manual selection | **Automatic — <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% cheaper** |
56
- | **Models** | GPT only | 200+ | 100+ (BYO keys) | **<!-- br:models.chatVisible -->74<!-- /br:models.chatVisible -->, one wallet** |
59
+ | **Models** | GPT only | 200+ | 100+ (BYO keys) | **<!-- br:models.chatVisible -->74<!-- /br:models.chatVisible -->, one credential** |
57
60
  | **Free tier** | ✗ | Rate-limited | ✗ | **<!-- br:models.free -->7<!-- /br:models.free --> models, no signup** |
58
- | **Auth** | API key | Account + API key | Your API keys | **Wallet signature** |
59
- | **Payment** | Card + invoice | Credit card | BYO keys | **USDC per-request** |
60
- | **Agent-ready** | ✗ | ✗ | ✗ | **✓ — agents fund their own wallet** |
61
+ | **Auth** | API key | Account + API key | Your API keys | **API key *or* wallet signature** |
62
+ | **Payment** | Card + invoice | Credit card | BYO keys | **Account credit or USDC per-request** |
63
+ | **Agent-ready** | ✗ | ✗ | ✗ | **✓ — one key, or agents fund their own wallet** |
61
64
 
62
65
  ## Installation
63
66
 
@@ -83,19 +86,72 @@ without them throws an error naming the exact install command.
83
86
  </details>
84
87
 
85
88
  <details>
86
- <summary><strong>Supported chains</strong> — Base (primary), Base Sepolia, Solana</summary>
89
+ <summary><strong>Supported chains</strong> — Solana (recommended), Base, Base Sepolia</summary>
87
90
 
88
91
  | Chain | Network | Payment | Status |
89
92
  |-------|---------|---------|--------|
90
- | **Base** | Base Mainnet (Chain ID: 8453) | USDC | Primary |
93
+ | **Solana** | Solana Mainnet | USDC (SPL) | Recommended for new wallets |
94
+ | **Base** | Base Mainnet (Chain ID: 8453) | USDC | Supported |
91
95
  | **Base Testnet** | Base Sepolia (Chain ID: 84532) | Testnet USDC | Development |
92
- | **Solana** | Solana Mainnet | USDC (SPL) | New |
93
96
 
94
97
  **Protocol:** x402 v2 (CDP Facilitator)
95
98
 
96
99
  </details>
97
100
 
98
- ## Quick Start (Base - Default)
101
+ ## Quick Start: API Key
102
+
103
+ 1. [Sign up or sign in](https://user.blockrun.ai).
104
+ 2. Create a key on [API Keys](https://user.blockrun.ai/dashboard/keys) and add credit on [Credits](https://user.blockrun.ai/dashboard/credits).
105
+ 3. Set the key and use any SDK client. No wallet or payment chain is required.
106
+
107
+ ```bash
108
+ export BLOCKRUN_API_KEY=brk_live_...
109
+ ```
110
+
111
+ ```typescript
112
+ import { LLMClient, ImageClient, VideoClient, BlockrunClient } from '@blockrun/llm';
113
+
114
+ const llm = new LLMClient(); // Reads BLOCKRUN_API_KEY
115
+ console.log(await llm.chat('openai/gpt-5.2', 'Hello!'));
116
+ const images = new ImageClient({ apiKey: process.env.BLOCKRUN_API_KEY });
117
+ const videos = new VideoClient(); // Same account; async jobs are polled automatically
118
+ const api = new BlockrunClient();
119
+ // Generic access to Responses and other service endpoints:
120
+ const response = await api.post('/v1/responses', { model: 'openai/gpt-5.2', input: 'Hello!' });
121
+ ```
122
+
123
+ All named service clients, `SolanaLLMClient`, and the OpenAI/Anthropic compatibility
124
+ wrappers accept `apiKey`. They use `https://api.blockrun.ai`; an OpenAI-style
125
+ `https://api.blockrun.ai/v1` base is also accepted. Override with `apiUrl`
126
+ (`baseURL` for `OpenAI`) or `BLOCKRUN_API_BASE_URL`.
127
+
128
+ An explicit `apiKey` wins over the environment. An explicit `privateKey` selects
129
+ wallet mode even when `BLOCKRUN_API_KEY` is set; passing both explicit credentials
130
+ is an error. With no explicit credential, `BLOCKRUN_API_KEY` beats the wallet key
131
+ env vars — a process holding both runs in account mode. Invalid or exhausted API keys never fall back to wallet payments.
132
+ Errors preserve `statusCode`, account error `response.code`, and `retryAfter`.
133
+ Account credentials are restricted to the configured origin, including polling.
134
+
135
+ Use the [account dashboard](https://user.blockrun.ai/dashboard) for account usage.
136
+ `getSpending()` reports x402 settlements only and throws in account mode; wallet
137
+ address/balance helpers require a wallet. Account credit does not sign trades or
138
+ transfer wallet funds. Service availability depends on the account gateway and model.
139
+
140
+ ## Quick Start: Solana (Recommended Wallet Chain)
141
+
142
+ ```typescript
143
+ import { setupAgentClient, SolanaLLMClient } from '@blockrun/llm';
144
+
145
+ // API key when configured; otherwise new wallets use Solana.
146
+ // Existing chain preferences and Base-only wallets are preserved.
147
+ const client = await setupAgentClient();
148
+ console.log(await client.smartChat('Explain photosynthesis.'));
149
+
150
+ // Explicit Solana wallet; requires the optional Solana dependencies below.
151
+ const solana = new SolanaLLMClient({ privateKey: process.env.SOLANA_WALLET_KEY });
152
+ ```
153
+
154
+ ## Quick Start: Base Wallet
99
155
 
100
156
  ```typescript
101
157
  import { LLMClient } from '@blockrun/llm';
@@ -383,7 +439,7 @@ const tweet = await client.chat('xai/grok-4.5', 'What is trending on X?', { sear
383
439
 
384
440
  ## How Payment Works
385
441
 
386
- 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:
442
+ In wallet mode, no API key is required. You hold USDC in your own wallet, and **every request pays for itself** with an on-chain micropayment. Two phases:
387
443
 
388
444
  ### Phase 1 — Fund your wallet once
389
445
 
@@ -443,7 +499,7 @@ const summary = getCostSummary(); // across sessions (~/.blockr
443
499
  console.log(`Lifetime: $${summary.totalUsd.toFixed(2)} over ${summary.calls} calls`);
444
500
  ```
445
501
 
446
- 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.
502
+ In wallet mode, 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.
447
503
 
448
504
  **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.
449
505
 
@@ -601,9 +657,9 @@ only ranks what `/v1/models` lists.
601
657
 
602
658
  | Model | Input Price | Output Price | Context | Notes |
603
659
  |-------|-------------|--------------|---------|-------|
604
- | `xai/grok-4.5` | $2.50/M | $9.00/M | 500K | Flagship — reasoning + vision, native Live Search (`search: true`) |
605
- | `xai/grok-4.3` | $1.50/M | $4.00/M | 1M | Reasoning + vision, tuned for agentic workflows |
606
- | `xai/grok-build-0.1` | $1.50/M | $3.00/M | 256K | Fast agentic coding model |
660
+ | `xai/grok-4.5` | $2.00/M | $6.00/M | 500K | Flagship — reasoning + vision, native Live Search (`search: true`) |
661
+ | `xai/grok-4.3` | $1.25/M | $2.50/M | 1M | Reasoning + vision, tuned for agentic workflows |
662
+ | `xai/grok-build-0.1` | $1.00/M | $2.00/M | 256K | Fast agentic coding model |
607
663
 
608
664
  ### Moonshot, MiniMax, Z.ai, Qwen
609
665
 
@@ -1335,9 +1391,15 @@ const client = new LLMClient({
1335
1391
 
1336
1392
  | Variable | Description |
1337
1393
  |----------|-------------|
1394
+ | `BLOCKRUN_API_KEY` | Your BlockRun account key (`brk_...`) — account billing, no wallet needed. Create one at [user.blockrun.ai/dashboard/keys](https://user.blockrun.ai/dashboard/keys) |
1395
+ | `BLOCKRUN_API_BASE_URL` | Account API endpoint (optional, default: https://api.blockrun.ai) |
1338
1396
  | `BASE_CHAIN_WALLET_KEY` | Your Base chain wallet private key (for Base / `LLMClient`) |
1339
1397
  | `SOLANA_WALLET_KEY` | Your Solana wallet secret key - bs58 encoded (for `SolanaLLMClient`) |
1340
- | `BLOCKRUN_API_URL` | API endpoint (optional, default: https://blockrun.ai/api) |
1398
+ | `BLOCKRUN_API_URL` | x402 gateway endpoint (optional, default: https://blockrun.ai/api) |
1399
+
1400
+ `BLOCKRUN_API_KEY` takes precedence: if it is set alongside a wallet key env var and
1401
+ you pass no explicit credential, the client runs in account mode. Pass an explicit
1402
+ `privateKey` to force wallet mode.
1341
1403
 
1342
1404
  ## Error Handling
1343
1405
 
@@ -1385,16 +1447,6 @@ Integration tests are automatically skipped if `BASE_CHAIN_WALLET_KEY` is not se
1385
1447
 
1386
1448
  ## Setting Up Your Wallet
1387
1449
 
1388
- ### Base (EVM)
1389
- 1. Create a wallet on Base (Coinbase Wallet, MetaMask, etc.)
1390
- 2. Get USDC on Base for API payments
1391
- 3. Export your private key and set as `BASE_CHAIN_WALLET_KEY`
1392
-
1393
- ```bash
1394
- # .env
1395
- BASE_CHAIN_WALLET_KEY=0x...
1396
- ```
1397
-
1398
1450
  ### Solana
1399
1451
  1. Create a Solana wallet (Phantom, Backpack, Solflare, etc.)
1400
1452
  2. Get USDC on Solana for API payments
@@ -1405,6 +1457,16 @@ BASE_CHAIN_WALLET_KEY=0x...
1405
1457
  SOLANA_WALLET_KEY=...your_bs58_secret_key
1406
1458
  ```
1407
1459
 
1460
+ ### Base (EVM)
1461
+ 1. Create a wallet on Base (Coinbase Wallet, MetaMask, etc.)
1462
+ 2. Get USDC on Base for API payments
1463
+ 3. Export your private key and set as `BASE_CHAIN_WALLET_KEY`
1464
+
1465
+ ```bash
1466
+ # .env
1467
+ BASE_CHAIN_WALLET_KEY=0x...
1468
+ ```
1469
+
1408
1470
  Note: Solana transactions are gasless for the user - the CDP facilitator pays for transaction fees.
1409
1471
 
1410
1472
  ## Security
@@ -1652,7 +1714,7 @@ The `AnthropicClient` wraps the official `@anthropic-ai/sdk` with a custom fetch
1652
1714
  ## Frequently Asked Questions
1653
1715
 
1654
1716
  ### What is @blockrun/llm?
1655
- @blockrun/llm is a TypeScript SDK that cuts LLM costs by up to <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% with built-in smart routing: every request is routed to the cheapest of <!-- br:models.chatVisible -->74<!-- /br:models.chatVisible --> models (OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot, and more) that can handle it, then paid per-request in USDC via the x402 protocol — no API keys, no subscriptions, no vendor lock-in.
1717
+ @blockrun/llm is a TypeScript SDK that cuts LLM costs by up to <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% with built-in smart routing: every request is routed to the cheapest of <!-- br:models.chatVisible -->74<!-- /br:models.chatVisible --> models (OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot, and more) that can handle it, then paid per-request in USDC via the x402 protocol — with API key account billing or x402 wallet payments on Solana or Base.
1656
1718
 
1657
1719
  ### How does payment work?
1658
1720
  When you make an API call, the SDK automatically handles x402 payment. It signs a USDC transaction locally using your wallet private key (which never leaves your machine), and includes the payment proof in the request header. Settlement is non-custodial and instant on Base or Solana.
@@ -1666,8 +1728,8 @@ Yes — as of v1.6.1. Use `client.chatCompletionStream()` for native streaming o
1666
1728
  ### How much does it cost?
1667
1729
  Pay only for what you use. Prices start at $0.0002 per request (GPT-5 Nano). There are no minimums, subscriptions, or monthly fees. $5 in USDC gets you thousands of requests.
1668
1730
 
1669
- ### Does it support both Base and Solana?
1670
- Yes. Use `LLMClient` for Base (EVM) payments and `SolanaLLMClient` for Solana payments. Same API, different payment chain.
1731
+ ### Does it support both Solana and Base?
1732
+ Yes. Use `SolanaLLMClient` for Solana payments (recommended) and `LLMClient` for Base payments. Use `apiKey` for account billing without selecting a chain.
1671
1733
 
1672
1734
  ---
1673
1735