@blockrun/llm 1.2.0 → 1.3.0

package/README.md

@@ -1,6 +1,9 @@
-# @blockrun/llm
+# @blockrun/llm (TypeScript SDK)
 
-Pay-per-request access to GPT-4o, Claude 4, Gemini 3.1, and more via x402 micropayments on Base and Solana.
+> **@blockrun/llm** is a TypeScript/Node.js SDK for accessing 40+ large language models (GPT-5, Claude, Gemini, Grok, DeepSeek, Kimi, and more) with automatic pay-per-request USDC micropayments via the x402 protocol. No API keys required — your wallet signature is your authentication. Supports Base and Solana chains.
+
+[![npm](https://img.shields.io/npm/v/@blockrun/llm.svg)](https://www.npmjs.com/package/@blockrun/llm)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
 **Networks:**
 - **Base Mainnet:** Chain ID 8453 - Production with real USDC
@@ -159,6 +162,7 @@ const tweet = await client.chat('xai/grok-3-mini', 'What is trending on X?', { s
 ### MiniMax
 | Model | Input Price | Output Price |
 |-------|-------------|--------------|
+| `minimax/minimax-m2.7` | $0.30/M | $1.20/M |
 | `minimax/minimax-m2.5` | $0.30/M | $1.20/M |
 
 ### NVIDIA (Free & Hosted)
@@ -343,6 +347,67 @@ const [gpt, claude, gemini] = await Promise.all([
 ]);
 ```
 
+## Prediction Markets (Powered by Predexon)
+
+Access real-time prediction market data from Polymarket, Kalshi, and Binance Futures via [Predexon](https://predexon.com). No API keys needed — pay-per-request via x402.
+
+### Polymarket
+
+```typescript
+import { LLMClient } from '@blockrun/llm';
+
+const client = new LLMClient();
+
+// List markets with optional filters ($0.001/request)
+const markets = await client.pm("polymarket/markets");
+const filtered = await client.pm("polymarket/markets", { status: "active", limit: 10 });
+const searched = await client.pm("polymarket/markets", { search: "bitcoin" });
+
+// List events ($0.001/request)
+const events = await client.pm("polymarket/events");
+
+// Historical trades ($0.001/request)
+const trades = await client.pm("polymarket/trades");
+
+// OHLCV candlestick data for a specific condition ($0.001/request)
+const candles = await client.pm("polymarket/candlesticks/0x1234abcd...");
+
+// Wallet profile ($0.005/request — tier 2)
+const profile = await client.pm("polymarket/wallet/0xABC123...");
+
+// Wallet P&L ($0.005/request — tier 2)
+const pnl = await client.pm("polymarket/wallet/pnl/0xABC123...");
+
+// Global leaderboard ($0.001/request)
+const leaderboard = await client.pm("polymarket/leaderboard");
+```
+
+### Kalshi & Binance
+
+```typescript
+// Kalshi markets ($0.001/request)
+const kalshiMarkets = await client.pm("kalshi/markets");
+
+// Kalshi trades ($0.001/request)
+const kalshiTrades = await client.pm("kalshi/trades");
+
+// Binance candles for supported pairs ($0.001/request)
+const btcCandles = await client.pm("binance/candles/BTCUSDT");
+const ethCandles = await client.pm("binance/candles/ETHUSDT");
+// Also: SOLUSDT, XRPUSDT
+```
+
+### Cross-Platform
+
+```typescript
+// Cross-platform matching pairs ($0.001/request)
+const pairs = await client.pm("matching-markets/pairs");
+```
+
+All current endpoints are GET. The `pmQuery()` method is available for future POST endpoints.
+
+Works on both `LLMClient` (Base) and `SolanaLLMClient`.
+
 ## Configuration
 
 ```typescript
@@ -493,6 +558,84 @@ import {
 } from '@blockrun/llm';
 ```
 
+## Agent Wallet Setup
+
+One-line setup for agent runtimes (Claude Code skills, MCP servers, etc.):
+
+```typescript
+import { setupAgentWallet } from '@blockrun/llm';
+
+// Auto-creates wallet if none exists, returns ready client
+const client = setupAgentWallet();
+const response = await client.chat('openai/gpt-5.4', 'Hello!');
+```
+
+For Solana:
+
+```typescript
+import { setupAgentSolanaWallet } from '@blockrun/llm';
+
+const client = await setupAgentSolanaWallet();
+const response = await client.chat('anthropic/claude-sonnet-4.6', 'Hello!');
+```
+
+Check wallet status:
+
+```typescript
+import { status } from '@blockrun/llm';
+
+await status();
+// Wallet: 0xCC8c...5EF8
+// Balance: $5.30 USDC
+```
+
+## Wallet Scanning
+
+The SDK auto-detects wallets from any provider on your system:
+
+```typescript
+import { scanWallets, scanSolanaWallets } from '@blockrun/llm';
+
+// Scans ~/.<dir>/wallet.json for Base wallets
+const baseWallets = scanWallets();
+
+// Scans ~/.<dir>/solana-wallet.json and ~/.brcc/wallet.json
+const solWallets = scanSolanaWallets();
+```
+
+`getOrCreateWallet()` checks scanned wallets first, so if you already have a wallet from another BlockRun tool, it will be reused automatically.
+
+## Response Caching
+
+The SDK caches responses to avoid duplicate payments:
+
+```typescript
+import { getCachedByRequest, saveToCache, clearCache } from '@blockrun/llm';
+
+// Automatic TTLs by endpoint:
+// - X/Twitter: 1 hour
+// - Search: 15 minutes
+// - Models: 24 hours
+// - Chat/Image: no cache (every call is unique)
+
+// Manual cache management
+clearCache(); // Remove all cached responses
+```
+
+## Cost Logging
+
+Track spending across sessions:
+
+```typescript
+import { logCost, getCostSummary } from '@blockrun/llm';
+
+// Costs are logged to ~/.blockrun/data/costs.jsonl
+const summary = getCostSummary();
+console.log(`Total: $${summary.totalUsd.toFixed(2)}`);
+console.log(`Calls: ${summary.calls}`);
+console.log(`By model:`, summary.byModel);
+```
+
 ## Links
 
 - [Website](https://blockrun.ai)
@@ -500,6 +643,23 @@ import {
 - [GitHub](https://github.com/blockrunai/blockrun-llm-ts)
 - [Telegram](https://t.me/+mroQv4-4hGgzOGUx)
 
+## Frequently Asked Questions
+
+### What is @blockrun/llm?
+@blockrun/llm is a TypeScript SDK that provides pay-per-request access to 40+ large language models from OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot, and more. It uses the x402 protocol for automatic USDC micropayments — no API keys, no subscriptions, no vendor lock-in.
+
+### How does payment work?
+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.
+
+### What is smart routing / ClawRouter?
+ClawRouter is a built-in smart routing engine that analyzes your request across 14 dimensions and automatically picks the cheapest model capable of handling it. Routing happens locally in under 1ms. It can save up to 78% on LLM costs compared to using premium models for every request.
+
+### How much does it cost?
+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.
+
+### Does it support both Base and Solana?
+Yes. Use `LLMClient` for Base (EVM) payments and `SolanaLLMClient` for Solana payments. Same API, different payment chain.
+
 ## License
 
 MIT