@blockrun/clawrouter 0.12.85 → 0.12.87

package/docs/11-free-ai-models-zero-cost-blockrun.md

@@ -18,19 +18,19 @@ BlockRun's answer: just take them.
 
 Through [ClawRouter](https://github.com/blockrunai/ClawRouter) — BlockRun's local AI routing proxy — you get zero-cost access to the following:
 
-| Model | Parameters | Context | Reasoning | Best For |
-|-------|-----------|---------|-----------|----------|
-| **GPT-OSS 120B** | 120B | 128K | — | General chat, summaries, formatting |
-| **GPT-OSS 20B** | 20B | 128K | — | Fast lightweight tasks |
-| **Nemotron Ultra 253B** | 253B | 131K | ✅ | Complex reasoning, math, analysis |
-| **Nemotron 3 Super 120B** | 120B | 131K | ✅ | Balanced reasoning + general |
-| **Nemotron Super 49B** | 49B | 131K | ✅ | Quick reasoning, low latency |
-| **DeepSeek V3.2** | — | 128K | ✅ | Code generation, technical reasoning |
-| **Mistral Large 675B** | 675B | 128K | ✅ | Multilingual, long-form, complex instructions |
-| **Qwen3 Coder 480B** | 480B | 128K | — | Professional code generation |
-| **Devstral 2 123B** | 123B | 128K | — | Developer tooling, code review |
-| **GLM-4.7** | — | 128K | ✅ | Chinese-English bilingual reasoning |
-| **Llama 4 Maverick** | — | 128K | ✅ | Meta's latest open-source all-rounder |
+| Model                     | Parameters | Context | Reasoning | Best For                                      |
+| ------------------------- | ---------- | ------- | --------- | --------------------------------------------- |
+| **GPT-OSS 120B**          | 120B       | 128K    | —         | General chat, summaries, formatting           |
+| **GPT-OSS 20B**           | 20B        | 128K    | —         | Fast lightweight tasks                        |
+| **Nemotron Ultra 253B**   | 253B       | 131K    | ✅        | Complex reasoning, math, analysis             |
+| **Nemotron 3 Super 120B** | 120B       | 131K    | ✅        | Balanced reasoning + general                  |
+| **Nemotron Super 49B**    | 49B        | 131K    | ✅        | Quick reasoning, low latency                  |
+| **DeepSeek V3.2**         | —          | 128K    | ✅        | Code generation, technical reasoning          |
+| **Mistral Large 675B**    | 675B       | 128K    | ✅        | Multilingual, long-form, complex instructions |
+| **Qwen3 Coder 480B**      | 480B       | 128K    | —         | Professional code generation                  |
+| **Devstral 2 123B**       | 123B       | 128K    | —         | Developer tooling, code review                |
+| **GLM-4.7**               | —          | 128K    | ✅        | Chinese-English bilingual reasoning           |
+| **Llama 4 Maverick**      | —          | 128K    | ✅        | Meta's latest open-source all-rounder         |
 
 **Price: $0.00 per million tokens. Input free. Output free. No hidden fees. No daily caps. No trial period.**
 
@@ -56,30 +56,31 @@ ClawRouter's value proposition isn't just "here are free models." It's **intelli
 
 ClawRouter classifies every incoming request into one of four complexity tiers:
 
-| Tier | Typical Tasks | ECO Route (Cheapest) | AUTO Route (Balanced) |
-|------|--------------|---------------------|----------------------|
-| **SIMPLE** | Formatting, translation, Q&A | 🆓 GPT-OSS 120B (FREE) | GPT-4o Mini |
-| **MEDIUM** | Summaries, analysis, general coding | 🆓 DeepSeek V3.2 (FREE) | DeepSeek V3.2 |
-| **COMPLEX** | Architecture, complex code | 🆓 Nemotron Ultra 253B (FREE) | Claude Sonnet 4 |
-| **REASONING** | Mathematical proofs, multi-step logic | DeepSeek R1 | Claude Opus 4 |
+| Tier          | Typical Tasks                         | ECO Route (Cheapest)          | AUTO Route (Balanced) |
+| ------------- | ------------------------------------- | ----------------------------- | --------------------- |
+| **SIMPLE**    | Formatting, translation, Q&A          | 🆓 GPT-OSS 120B (FREE)        | GPT-4o Mini           |
+| **MEDIUM**    | Summaries, analysis, general coding   | 🆓 DeepSeek V3.2 (FREE)       | DeepSeek V3.2         |
+| **COMPLEX**   | Architecture, complex code            | 🆓 Nemotron Ultra 253B (FREE) | Claude Sonnet 4       |
+| **REASONING** | Mathematical proofs, multi-step logic | DeepSeek R1                   | Claude Opus 4         |
 
 Look at the ECO column. **Three out of four tiers route to free models.** Unless you're doing the hardest reasoning tasks, your daily work costs nothing.
 
 ### Real-World Cost Comparison
 
 Assume 100 requests per day, distributed roughly as:
+
 - 40% SIMPLE (chat, translation, formatting)
 - 30% MEDIUM (coding, analysis)
 - 20% COMPLEX (architecture, deep debugging)
 - 10% REASONING (math, formal logic)
 
-| Approach | Estimated Monthly Cost |
-|----------|----------------------|
-| Pure Claude Opus 4 | ~$75–150 |
-| Pure GPT-4o | ~$15–30 |
-| ClawRouter AUTO mode | ~$5–10 |
-| ClawRouter ECO mode | ~$1–3 |
-| Manual free model selection | **$0** |
+| Approach                    | Estimated Monthly Cost |
+| --------------------------- | ---------------------- |
+| Pure Claude Opus 4          | ~$75–150               |
+| Pure GPT-4o                 | ~$15–30                |
+| ClawRouter AUTO mode        | ~$5–10                 |
+| ClawRouter ECO mode         | ~$1–3                  |
+| Manual free model selection | **$0**                 |
 
 **ECO mode saves 92%+ compared to Claude Opus alone.**
 
@@ -273,4 +274,4 @@ Go build something.
 
 ---
 
-*Based on ClawRouter v0.12.84. Model availability may change with future releases. For the latest information, visit [blockrun.ai](https://blockrun.ai).*
+_Based on ClawRouter v0.12.84. Model availability may change with future releases. For the latest information, visit [blockrun.ai](https://blockrun.ai)._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/clawrouter",
-  "version": "0.12.85",
+  "version": "0.12.87",
   "description": "Smart LLM router — save 85% on inference costs. 55+ models (11 free), one wallet, x402 micropayments.",
   "type": "module",
   "main": "dist/index.js",
@@ -74,9 +74,9 @@
     "@scure/bip32": "^2.0.1",
     "@scure/bip39": "^1.5.0",
     "@solana/kit": "^5.0.0",
-    "@x402/evm": "^2.7.0",
-    "@x402/fetch": "^2.7.0",
-    "@x402/svm": "^2.7.0",
+    "@x402/evm": "^2.8.0",
+    "@x402/fetch": "^2.8.0",
+    "@x402/svm": "^2.8.0",
     "viem": "^2.39.3"
   },
   "peerDependencies": {

package/skills/imagegen/SKILL.md

@@ -1,80 +1,114 @@
 ---
 name: imagegen
-description: Generate images via BlockRun's image API. Trigger when the user asks to generate, create, draw, or make an image.
+description: Generate or edit images via BlockRun's image API. Trigger when the user asks to generate, create, draw, make an image — or to edit, modify, change, or retouch an existing image.
 metadata: { "openclaw": { "emoji": "🖼️", "requires": { "config": ["models.providers.blockrun"] } } }
 ---
 
-# Image Generation
+# Image Generation & Editing
 
-When the user asks to generate, create, draw, or make an image, generate it by calling ClawRouter's image API directly — no extra setup needed.
+Generate or edit images through ClawRouter. Payment is automatic via x402.
 
-## How to Generate
+---
+
+## Generate an Image
 
 POST to `http://localhost:8402/v1/images/generations`:
 
 ```json
 {
   "model": "google/nano-banana",
-  "prompt": "<user's prompt>",
+  "prompt": "a golden retriever surfing on a wave",
   "size": "1024x1024",
   "n": 1
 }
 ```
 
-The response contains a public image URL:
+Response:
 
 ```json
 {
   "created": 1741460000,
-  "data": [{ "url": "https://files.catbox.moe/abc123.png" }]
+  "data": [{ "url": "http://localhost:8402/images/abc123.png" }]
 }
 ```
 
-Display the image inline in your response:
+Display inline: `![generated image](http://localhost:8402/images/abc123.png)`
 
-```markdown
-![generated image](https://files.catbox.moe/abc123.png)
-```
+### Model Selection
 
-## Model Selection
+| Model | Full ID | Price | Sizes | Best for |
+|-------|---------|-------|-------|----------|
+| `nano-banana` | `google/nano-banana` | $0.05 | 1024×1024, 1216×832, 1024×1792 | Default — fast, cheap, good quality |
+| `banana-pro` | `google/nano-banana-pro` | $0.10 | up to 4096×4096 | High-res, large format |
+| `dall-e-3` | `openai/dall-e-3` | $0.04 | 1024×1024, 1792×1024, 1024×1792 | Photorealistic, complex scenes |
+| `gpt-image` | `openai/gpt-image-1` | $0.02 | 1024×1024, 1536×1024, 1024×1536 | Budget option |
+| `flux` | `black-forest/flux-1.1-pro` | $0.04 | 1024×1024, 1216×832, 832×1216 | Artistic styles, fewer restrictions |
 
-Pick the model based on what the user asks for (or default to `nano-banana`):
+**Choosing a model:**
+- Default → `nano-banana`
+- "high res" / "large" → `banana-pro`
+- "photorealistic" / "dall-e" → `dall-e-3`
+- "artistic" / flexible content → `flux`
 
-| Model shorthand | Full ID                     | Price | Best for                            |
-| --------------- | --------------------------- | ----- | ----------------------------------- |
-| `nano-banana`   | `google/nano-banana`        | $0.05 | Default — fast, cheap, good quality |
-| `banana-pro`    | `google/nano-banana-pro`    | $0.10 | High-res up to 4096×4096            |
-| `dall-e-3`      | `openai/dall-e-3`           | $0.04 | Photorealistic, complex scenes      |
-| `gpt-image`     | `openai/gpt-image-1`        | $0.02 | Budget option                       |
-| `flux`          | `black-forest/flux-1.1-pro` | $0.04 | Artistic styles, fewer restrictions |
+**Choosing a size:**
+- Default: `1024x1024`
+- Portrait: `1024x1792`
+- Landscape: `1792x1024` (dall-e-3) or `1216x832` (nano-banana / flux)
+- High-res: `2048x2048` or `4096x4096` with `banana-pro` only
 
-If the user mentions "high res" or "large", use `banana-pro`. If they want "photorealistic" or "dall-e", use `dall-e-3`. Otherwise default to `nano-banana`.
+---
 
-## Size Options
+## Edit an Existing Image
 
-Default is `1024x1024`. Adjust based on user request:
+POST to `http://localhost:8402/v1/images/image2image`:
 
-- Portrait: `1024x1792`
-- Landscape: `1792x1024` (dall-e-3) or `1216x832` (nano-banana / flux)
-- High-res: up to `4096x4096` with `banana-pro` only
+```json
+{
+  "model": "openai/gpt-image-1",
+  "prompt": "make the background a snowy mountain landscape",
+  "image": "https://example.com/photo.jpg",
+  "size": "1024x1024",
+  "n": 1
+}
+```
 
-## Example Interactions
+ClawRouter automatically downloads URLs and reads local file paths — pass them directly, no manual base64 conversion needed.
+
+Optional `mask` field: a second image (URL or path) that marks which areas to edit (white = edit, black = keep).
+
+Response is identical to generation:
+
+```json
+{
+  "created": 1741460000,
+  "data": [{ "url": "http://localhost:8402/images/xyz456.png", "revised_prompt": "..." }]
+}
+```
 
-**User:** Draw me a golden retriever surfing on a wave
+**Supported models for editing:** `openai/gpt-image-1` only ($0.02)
 
-→ Call `nano-banana` with prompt `"a golden retriever surfing on a wave"`, display the image.
+---
 
-**User:** Generate a high-res mountain landscape, landscape format
+## Example Interactions
 
-→ Call `banana-pro` with size `1024x1024` (max varies by model), prompt `"mountain landscape"`.
+**User:** Draw me a cyberpunk city at night
+→ POST to `/v1/images/generations`, model `nano-banana`, prompt as given.
 
-**User:** Make a cyberpunk city with dall-e
+**User:** Generate a high-res portrait of a samurai
+→ POST to `/v1/images/generations`, model `banana-pro`, size `1024x1792`.
 
-→ Call `dall-e-3` with prompt `"a futuristic cyberpunk city"`.
+**User:** Edit this photo to add a sunset background: https://example.com/portrait.jpg
+→ POST to `/v1/images/image2image`, model `gpt-image`, image = the URL, prompt = "add a warm sunset background".
+
+**User:** Change the background in my image to a beach (attaches local file)
+→ POST to `/v1/images/image2image`, image = the local file path, prompt describes the change.
+
+---
 
 ## Notes
 
 - Payment is automatic via x402 — deducted from the user's BlockRun wallet
 - If the call fails with a payment error, tell the user to fund their wallet at [blockrun.ai](https://blockrun.ai)
-- DALL-E 3 applies OpenAI content policy; use `flux` or `nano-banana` for more flexibility
-- Google models may return base64 — ClawRouter handles uploading automatically, you'll get a URL back
+- Google models may return base64 internally — ClawRouter uploads automatically and returns a hosted URL
+- DALL-E 3 enforces OpenAI content policy; use `flux` or `nano-banana` for more flexibility
+- Image editing is only available with `gpt-image-1`; generation supports all 5 models

package/skills/predexon/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: predexon
+description: Query prediction market data via BlockRun. Trigger when the user asks about Polymarket, Kalshi, prediction markets, betting odds, smart money positioning, or wants to analyze a prediction market wallet.
+homepage: https://blockrun.ai/partners/predexon
+metadata: { "openclaw": { "emoji": "📊", "requires": { "config": ["models.providers.blockrun"] } } }
+---
+
+# Predexon — Prediction Market Data
+
+Real-time prediction market data (Polymarket, Kalshi, dFlow, Binance) via BlockRun's x402 gateway. Payment is automatic — deducted from the user's BlockRun wallet.
+
+**All responses are wrapped:** `{ "data": { ... } }` — always read from `response.data`.
+
+**Pricing:** GET $0.001 · Wallet analytics / smart money / Binance / matching $0.005
+
+---
+
+## Browse Markets & Events
+
+GET `http://localhost:8402/v1/pm/polymarket/events?limit=20`
+
+Common params: `limit`, `offset`, `tag` (e.g. `crypto`, `politics`, `sports`)
+
+Response fields in `data`:
+- `events[].title` — market name
+- `events[].outcomes` — array of `{ name, price }` (price = implied probability 0–1)
+- `events[].volume` — total volume in USD
+- `events[].endDate` — resolution date
+- `events[].conditionId` — use this for follow-up calls
+
+To search by keyword: `GET /v1/pm/polymarket/markets?search=bitcoin&limit=10`
+
+Response fields in `data`:
+- `markets[].question` — market question
+- `markets[].conditionId`
+- `markets[].outcomes[].price`
+- `markets[].volumeNum`
+
+---
+
+## Smart Money on a Market
+
+Find the `conditionId` first (from events/markets above), then:
+
+GET `http://localhost:8402/v1/pm/polymarket/market/{conditionId}/smart-money`
+
+Response fields in `data`:
+- `positions[].wallet` — wallet address
+- `positions[].side` — YES or NO
+- `positions[].size` — position size in USD
+- `positions[].pnl` — profit/loss on this position
+- `positions[].winRate` — wallet's historical win rate
+
+---
+
+## Leaderboard
+
+GET `http://localhost:8402/v1/pm/polymarket/leaderboard?limit=20`
+
+Response fields in `data`:
+- `wallets[].address`
+- `wallets[].profit` — total realized profit in USD
+- `wallets[].volume`
+- `wallets[].winRate`
+- `wallets[].marketsTraded`
+
+---
+
+## Wallet Analysis
+
+GET `http://localhost:8402/v1/pm/polymarket/wallet/{walletAddress}`
+
+Response fields in `data`:
+- `profit` — total realized profit
+- `volume` — total traded volume
+- `winRate` — fraction of winning trades (0–1)
+- `marketsTraded` — number of distinct markets
+- `currentPositions[]` — open positions
+
+For P&L over time: GET `/v1/pm/polymarket/wallet/pnl/{walletAddress}`
+- `data.pnlSeries[]` — `{ date, cumulativePnl }`
+- `data.totalProfit`, `data.totalLoss`
+
+---
+
+## Compare Polymarket vs Kalshi
+
+GET `http://localhost:8402/v1/pm/matching-markets?limit=10`
+
+Response fields in `data`:
+- `pairs[].polymarketTitle`
+- `pairs[].kalshiTitle`
+- `pairs[].polymarketPrice` — YES price on Polymarket (0–1)
+- `pairs[].kalshiPrice` — YES price on Kalshi (0–1)
+- `pairs[].spread` — price difference (arbitrage signal)
+
+---
+
+## Example Interactions
+
+**User:** What are the top prediction markets right now?
+→ `GET /v1/pm/polymarket/events?limit=20` — summarize top events with titles, outcomes, and current YES/NO prices.
+
+**User:** What's the smart money doing on the 2026 election markets?
+→ First `GET /v1/pm/polymarket/markets?search=election&limit=5` to get `conditionId`s, then `GET /v1/pm/polymarket/market/{conditionId}/smart-money` for each. Show top positions, sides, and P&L.
+
+**User:** Who are the top Polymarket whales?
+→ `GET /v1/pm/polymarket/leaderboard?limit=10` — table with wallet (shortened), profit, win rate, markets traded.
+
+**User:** Analyze this wallet: 0xabc...
+→ `GET /v1/pm/polymarket/wallet/0xabc...` + `GET /v1/pm/polymarket/wallet/pnl/0xabc...` — summarize trading style, win rate, total P&L, current open positions.
+
+**User:** Compare Polymarket vs Kalshi on the Fed rate decision
+→ `GET /v1/pm/matching-markets?limit=20` — find the Fed pair, show both prices and the spread.
+
+---
+
+## Full Endpoint Reference
+
+All endpoints are GET. Query params go in the URL.
+
+| Endpoint | Price | Key params |
+|----------|-------|------------|
+| `/v1/pm/polymarket/events` | $0.001 | `limit`, `offset`, `tag` |
+| `/v1/pm/polymarket/markets` | $0.001 | `search`, `limit`, `offset` |
+| `/v1/pm/polymarket/crypto-updown` | $0.001 | — |
+| `/v1/pm/polymarket/leaderboard` | $0.001 | `limit`, `offset` |
+| `/v1/pm/polymarket/leaderboard/market/{conditionId}` | $0.001 | `limit` |
+| `/v1/pm/polymarket/market/{conditionId}/top-holders` | $0.001 | `limit` |
+| `/v1/pm/polymarket/cohorts/stats` | $0.001 | — |
+| `/v1/pm/polymarket/positions` | $0.001 | `wallet`, `limit` |
+| `/v1/pm/polymarket/trades` | $0.001 | `wallet`, `limit`, `start_ts`, `end_ts` |
+| `/v1/pm/polymarket/orderbooks` | $0.001 | `tokenId`, `limit` |
+| `/v1/pm/polymarket/market-price/{tokenId}` | $0.001 | `startTs`, `endTs` |
+| `/v1/pm/polymarket/candlesticks/{conditionId}` | $0.001 | `period`, `limit` |
+| `/v1/pm/polymarket/volume-chart/{conditionId}` | $0.001 | — |
+| `/v1/pm/polymarket/wallet/{wallet}` | $0.005 | — |
+| `/v1/pm/polymarket/wallet/{wallet}/markets` | $0.005 | `limit` |
+| `/v1/pm/polymarket/wallet/{wallet}/similar` | $0.005 | — |
+| `/v1/pm/polymarket/wallet/pnl/{wallet}` | $0.005 | — |
+| `/v1/pm/polymarket/wallet/positions/{wallet}` | $0.005 | — |
+| `/v1/pm/polymarket/wallet/volume-chart/{wallet}` | $0.005 | — |
+| `/v1/pm/polymarket/wallets/profiles` | $0.005 | `wallets` (comma-separated) |
+| `/v1/pm/polymarket/wallets/filter` | $0.005 | `conditionId`, `side` |
+| `/v1/pm/polymarket/market/{conditionId}/smart-money` | $0.005 | `limit` |
+| `/v1/pm/polymarket/markets/smart-activity` | $0.005 | `limit` |
+| `/v1/pm/kalshi/markets` | $0.001 | `search`, `limit` |
+| `/v1/pm/kalshi/trades` | $0.001 | `limit` |
+| `/v1/pm/kalshi/orderbooks` | $0.001 | `marketId` |
+| `/v1/pm/dflow/trades` | $0.001 | `wallet`, `limit` |
+| `/v1/pm/dflow/wallet/positions/{wallet}` | $0.005 | — |
+| `/v1/pm/dflow/wallet/pnl/{wallet}` | $0.005 | — |
+| `/v1/pm/binance/candles/{symbol}` | $0.005 | `interval`, `limit` |
+| `/v1/pm/binance/ticks/{symbol}` | $0.005 | `limit` |
+| `/v1/pm/matching-markets` | $0.005 | `limit`, `offset` |
+| `/v1/pm/matching-markets/pairs` | $0.005 | — |
+| `/v1/pm/limitless/orderbooks` | $0.001 | `marketId` |
+| `/v1/pm/opinion/orderbooks` | $0.001 | `marketId` |
+| `/v1/pm/predictfun/orderbooks` | $0.001 | `marketId` |
+
+---
+
+## Notes
+
+- Payment is automatic via x402 — deducted from the user's BlockRun wallet
+- If payment fails, tell the user to fund their wallet at [blockrun.ai](https://blockrun.ai)
+- Retry once on 502 — Predexon can occasionally be slow
+- Always read from `response.data` — every response is wrapped `{ data: ... }`
+- Synthesize data into plain-language analysis — never dump raw JSON