@blockrun/mcp 0.22.2 → 0.23.0

package/skills/phone/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: phone
+description: Use when the user wants phone-number intelligence (lookup, carrier, line type, SIM-swap / call-forwarding fraud signals), US/CA number provisioning (rent a phone number), or outbound AI voice calls (Bland.ai under the hood — schedule, confirm, follow-up). Pay per call in USDC.
+triggers:
+  - "phone lookup"
+  - "carrier lookup"
+  - "phone number intelligence"
+  - "sim swap"
+  - "call forwarding"
+  - "phone fraud"
+  - "buy phone number"
+  - "rent phone number"
+  - "us phone number"
+  - "ai voice call"
+  - "voice call"
+  - "outbound call"
+  - "appointment confirmation"
+  - "bland.ai"
+---
+
+# Phone & Voice
+
+Two namespaces in one tool: **`/v1/phone/*`** for number intelligence + provisioning, **`/v1/voice/*`** for outbound AI calls. Pay per call in USDC.
+
+Phone numbers use **E.164 format** — `+` followed by country code and subscriber digits (US: `+1` + 10 digits; UK: `+44` + 10 digits; etc.). The examples below use `<+E.164-number>` as a placeholder — the LLM should substitute the actual number from the user's request, not copy the literal placeholder.
+
+## How to Call from MCP
+
+```ts
+const targetNumber = "<+E.164-number-from-user>"  // e.g. user said "call my doctor at 415-..."
+
+// Lookup carrier + line type
+blockrun_phone({ path: "phone/lookup", body: { phoneNumber: targetNumber } })
+
+// Buy a 30-day US number
+blockrun_phone({ path: "phone/numbers/buy", body: { country: "US", areaCode: "415" } })
+
+// Outbound AI call (requires `from` — see below)
+const r = await blockrun_phone({ path: "voice/call", body: {
+  to: targetNumber,
+  from: "<+E.164-number-you-own>",       // from phone/numbers/buy
+  task: "Confirm appointment for Friday at 3pm with Dr. Wong.",
+  voice: "june"
+}})
+// poll the result (free GET, no body)
+blockrun_phone({ path: `voice/call/${r.call_id}` })
+```
+
+## Endpoint Catalog
+
+### Phone intelligence + numbers (`/v1/phone/*`)
+
+| Path | Body | Price | Effect |
+|---|---|---|---|
+| `phone/lookup` | `{ phoneNumber }` | $0.01 | Carrier, line type (mobile/landline/VoIP) |
+| `phone/lookup/fraud` | `{ phoneNumber }` | $0.05 | + SIM-swap signals, call-forwarding detection |
+| `phone/numbers/buy` | `{ country?: "US"\|"CA", areaCode? }` | $5.00 | 30-day lease, US or CA |
+| `phone/numbers/renew` | `{ phoneNumber }` | $5.00 | Extend lease 30 days |
+| `phone/numbers/list` | `{}` | $0.001 | Your wallet-owned numbers |
+| `phone/numbers/release` | `{ phoneNumber }` | free | Return to pool |
+
+### Outbound AI calls (`/v1/voice/*`)
+
+| Path | Method | Body | Price |
+|---|---|---|---|
+| `voice/call` | POST | `{ to, task, from, voice?, max_duration?, language?, first_sentence?, wait_for_greeting? }` | $0.54 flat |
+| `voice/call/{call_id}` | GET (no body) | – | free poll |
+
+> **`from` is REQUIRED and must be a number your wallet owns.** Provision one first with `phone/numbers/buy` ($5, 30-day lease). 400 errors from `voice/call` are almost always missing `from`.
+
+## Voice Call Body Fields
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `to` | yes | – | Destination E.164 number |
+| `task` | yes | – | What the AI should do on the call (10–4000 chars) |
+| `from` | **yes** | – | Your provisioned BlockRun caller-ID number (from `phone/numbers/buy`) |
+| `voice` | no | `nat` | `nat` / `josh` / `maya` / `june` / `paige` / `derek` / `florian` |
+| `max_duration` | no | 5 | Minutes, 1–30 |
+| `language` | no | `en-US` | Language code, BCP-47 |
+| `first_sentence` | no | – | Custom opening line for the AI |
+| `wait_for_greeting` | no | false | Let recipient speak first, then AI starts |
+
+## Voice Presets
+
+| Voice | Tone |
+|---|---|
+| `nat` | Neutral / professional male, default |
+| `josh` | Friendly male |
+| `maya` | Warm female |
+| `june` | Calm professional female |
+| `paige` | Energetic female |
+| `derek` | Deep male |
+| `florian` | European-accented male |
+
+## Worked Examples
+
+### 1. Triage an inbound number for fraud
+
+```ts
+blockrun_phone({ path: "phone/lookup/fraud", body: { phoneNumber: "+14155550150" } })
+```
+Returns carrier, line type, SIM-swap indicator, call-forwarding state. **Cost: $0.05.**
+
+### 2. Spin up a US number with a 415 area code
+
+```ts
+blockrun_phone({ path: "phone/numbers/buy", body: { country: "US", areaCode: "415" } })
+// returns { phoneNumber: "+14155550199", expires_at: "..." }
+```
+Best-effort area code match. **Cost: $5.00 for 30 days.**
+
+### 3. Confirm an appointment via AI voice call
+
+```ts
+// Step 0 (one-time): provision a number you'll use as caller ID
+const { phoneNumber: myNumber } = await blockrun_phone({
+  path: "phone/numbers/buy", body: { country: "US", areaCode: "415" }
+})  // $5.00, 30-day lease
+
+// Step 1: place the call (from is REQUIRED)
+const r = await blockrun_phone({ path: "voice/call", body: {
+  to: "+14155550100",
+  from: myNumber,
+  task: "Call Dr. Wong's office. Confirm the appointment for Sarah Chen on Friday May 24th at 3pm. If the time isn't available, ask for the next opening on Friday afternoon and report back.",
+  voice: "june",
+  max_duration: 5,
+  wait_for_greeting: true
+}})
+// returns { call_id: "call_abc..." } — call runs async
+
+// Poll until done
+while (true) {
+  const status = await blockrun_phone({ path: `voice/call/${r.call_id}` })
+  if (status.status === "completed") {
+    console.log(status.summary, status.transcript)
+    break
+  }
+  await new Promise(r => setTimeout(r, 5000))
+}
+```
+**Cost: $0.54 flat for the call.** Status polling is free.
+
+### 4. List your wallet's leased numbers + release one
+
+```ts
+const { numbers } = await blockrun_phone({ path: "phone/numbers/list", body: {} })
+// Release the oldest
+await blockrun_phone({ path: "phone/numbers/release", body: { phoneNumber: numbers[0].phoneNumber } })
+```
+
+## Best Practices
+
+- **Always include task context the AI can act on.** "Confirm appointment" is vague; "Confirm Sarah Chen's appointment for Friday May 24 at 3pm with Dr. Wong" is actionable.
+- **Use `wait_for_greeting: true`** for human-answered calls (most cases). Set to `false` for known-IVR / known-bot destinations to skip the greeting wait.
+- **`max_duration` is a hard cap** — the call ends regardless of conversation state. Default 5 min covers most scripted tasks.
+- **`from` matters** for trust** — using a provisioned BlockRun number you own (from `numbers/buy`) makes the call look less spammy than a random caller ID.
+
+## When NOT to Use
+
+- **High-volume autodialer / robocall workloads** — pricing is per-call ($0.54 each) which doesn't amortize like wholesale telephony
+- **Receiving inbound calls** — `numbers/buy` provisions a number but inbound routing is not exposed via MCP; use Bland directly
+- **Two-way human-to-human calls** — this is for AI-driven outbound; for real-time human bridging, use a SIP provider
+
+## Notes
+
+- `phone/lookup` is cheap reconnaissance; `phone/lookup/fraud` is 5× the price but adds SIM-swap + call-forwarding signals you can't get from a basic carrier lookup
+- Voice calls return immediately with a `call_id`; the call runs in the background. Always poll `voice/call/{call_id}` to get the transcript
+- The poll endpoint is free — poll as often as you want, but every 5s is plenty
+- Calls that fail upstream (recipient hangs up, no answer) still charge the flat $0.54 — Bland's pricing model
+
+## Reference
+
+- Phone endpoints: `POST /v1/phone/*`
+- Voice endpoints: `POST /v1/voice/call` and `GET /v1/voice/call/{call_id}`
+- Upstream: number intelligence + provisioning is internal; voice calls are Bland.ai

package/skills/prediction-markets/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: prediction-markets
+description: Use when user asks about event probabilities, prediction market odds, what people are betting on, Polymarket or Kalshi prices, sports markets, wallet identity / clustering, or wants to find markets on a specific topic (elections, crypto, sports, macro events). Predexon v2 endpoints (canonical cross-venue markets, sports, wallet identity, keyset pagination) live in production as of 2026-05.
+triggers:
+  - "polymarket"
+  - "kalshi"
+  - "dflow"
+  - "prediction market"
+  - "event probability"
+  - "betting odds"
+  - "what are people betting on"
+  - "election odds"
+  - "crypto market odds"
+  - "binance futures"
+  - "yes/no market"
+  - "implied probability"
+  - "sports markets"
+  - "wallet identity"
+  - "wallet cluster"
+  - "cross-venue markets"
+  - "predexon"
+---
+
+# Prediction Markets
+
+Real-time prediction market data via BlockRun (powered by Predexon v2). Covers canonical cross-venue markets, Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, dFlow, sports, and Binance Futures.
+
+## Quick Decision Table
+
+| User wants... | Method | Path | Cost |
+|--------------|--------|------|------|
+| **Canonical cross-venue markets** | `client.pm(path)` | `"markets"` | $0.001 |
+| **Venue-native flattened listings** | `client.pm(path)` | `"markets/listings"` | $0.001 |
+| **Resolve canonical outcome ID** | `client.pm(path)` | `"outcomes/{predexon_id}"` | $0.001 |
+| **Search across all venues** | `client.pm(path, q=...)` | `"markets/search"` | $0.005 |
+| Active Polymarket events | `client.pm(path)` | `"polymarket/events"` | $0.001 |
+| Polymarket events (keyset paginated) | `client.pm(path, pagination_key=...)` | `"polymarket/events/keyset"` | $0.001 |
+| Polymarket markets (keyset paginated) | `client.pm(path, pagination_key=...)` | `"polymarket/markets/keyset"` | $0.001 |
+| Specific Kalshi market | `client.pm(path)` | `"kalshi/markets/TICKER"` | $0.001 |
+| **Sports categories** | `client.pm(path)` | `"sports/categories"` | $0.001 |
+| **Sports markets (by league/sport)** | `client.pm(path, league=...)` | `"sports/markets"` | $0.001 |
+| **Wallet identity (single)** | `client.pm(path)` | `"polymarket/wallet/identity/{wallet}"` | $0.005 |
+| **Wallet identity (bulk, up to 200)** | `client.pm_query(path, body)` | `"polymarket/wallet/identities"` | $0.005 |
+| **Wallet on-chain cluster** | `client.pm(path)` | `"polymarket/wallet/{address}/cluster"` | $0.005 |
+| dFlow markets | `client.pm(path)` | `"dflow/..."` | $0.001-$0.005 |
+| Binance Futures | `client.pm(path)` | `"binance/..."` | $0.005 |
+
+## Instructions
+
+### 1. Initialize
+
+```python
+import os
+from pathlib import Path
+
+chain_file = Path.home() / ".blockrun" / ".chain"
+chain = chain_file.read_text().strip() if chain_file.exists() else "base"
+
+if chain == "solana":
+    from blockrun_llm import setup_agent_solana_wallet
+    client = setup_agent_solana_wallet()
+else:
+    from blockrun_llm import setup_agent_wallet
+    client = setup_agent_wallet()
+```
+
+### 2. List Active Events
+
+```python
+# All active Polymarket events
+events = client.pm("polymarket/events")
+for event in events.get("data", events if isinstance(events, list) else [])[:10]:
+    print(f"{event.get('title', '?')} — {event.get('slug', '')}")
+```
+
+### 3. Search by Topic
+
+```python
+# Search Polymarket for a topic
+results = client.pm("polymarket/search", q="bitcoin ETF")
+for market in results.get("data", results if isinstance(results, list) else [])[:10]:
+    title = market.get("title", "?")
+    # Outcome prices are in the market object
+    print(f"{title}")
+    for outcome in market.get("outcomes", []):
+        print(f"  {outcome.get('title', '?')}: {outcome.get('price', '?')}")
+```
+
+### 4. Specific Kalshi Market
+
+```python
+# Get a specific Kalshi market by ticker
+market = client.pm("kalshi/markets/KXBTC-25MAR14")
+print(f"Market: {market.get('title', market.get('ticker', '?'))}")
+yes_price = market.get("yes_bid", market.get("yes_price", "?"))
+no_price = market.get("no_bid", market.get("no_price", "?"))
+print(f"YES: {yes_price} | NO: {no_price}")
+```
+
+### 5. Structured Query (POST)
+
+Use for complex filtering — active markets only, sorted by volume, with pagination.
+
+```python
+# Polymarket: active markets sorted by volume, limit 20
+data = client.pm_query("polymarket/query", {
+    "filter": "active",
+    "limit": 20,
+    "order": "volume",
+})
+
+# Kalshi: all markets in a specific series
+data = client.pm_query("kalshi/query", {
+    "series_ticker": "KXBTC",
+    "limit": 50,
+})
+```
+
+### 6. Canonical Cross-Venue Markets (v2)
+
+Predexon v2 unifies markets across Polymarket, Kalshi, Limitless, Opinion, Predict.Fun behind canonical IDs. One call returns the same question regardless of venue.
+
+```python
+# All canonical markets (filter by venue, status, category, league, event_id)
+markets = client.pm("markets", venue="polymarket", status="active")
+for m in markets.get("markets", [])[:10]:
+    print(f"{m.get('predexon_id')} — {m.get('title')}")
+
+# Flattened venue-native listings (each row = a tradable listing on one venue)
+listings = client.pm("markets/listings", category="elections")
+
+# Resolve a canonical outcome ID across venues
+detail = client.pm("outcomes/PXM-12345")
+print(detail.get("title"), detail.get("venue_listings"))
+```
+
+### 7. Sports Markets (v2)
+
+```python
+# List sports categories (NBA, NFL, MLB, soccer leagues, …)
+categories = client.pm("sports/categories")
+
+# Sports markets grouped by game — filter by league or venue
+nba = client.pm("sports/markets", league="NBA", status="open")
+for game in nba.get("markets", [])[:10]:
+    print(f"{game.get('title')} @ {game.get('start_time')}")
+    for venue in game.get("venue_listings", []):
+        print(f"  {venue.get('venue')}: {venue.get('price')}")
+```
+
+### 8. Keyset Pagination (v2)
+
+For large Polymarket result sets, prefer keyset pagination over offset. It is stable across writes and faster on big tables.
+
+```python
+# First page
+page = client.pm("polymarket/markets/keyset", limit="100")
+markets = page.get("markets", [])
+next_key = page.get("pagination", {}).get("next_key")
+
+# Subsequent pages
+while next_key:
+    page = client.pm("polymarket/markets/keyset", limit="100", pagination_key=next_key)
+    markets.extend(page.get("markets", []))
+    next_key = page.get("pagination", {}).get("next_key")
+```
+
+### 9. Wallet Identity & On-Chain Clustering (v2, Tier 2)
+
+Cross-context wallet labels (ENS, Twitter, Discord, portfolio metrics) plus on-chain relationship graph data — exposed as three endpoints. **All Tier 2 ($0.005/call).**
+
+```python
+# Single wallet identity
+ident = client.pm("polymarket/wallet/identity/0xabc...")
+print(ident.get("ens_name"), ident.get("twitter"), ident.get("portfolio_value"))
+
+# Bulk identity lookup (POST, up to 200 wallets per call)
+batch = client.pm_query("polymarket/wallet/identities", {
+    "addresses": ["0xabc...", "0xdef...", "0x123..."],
+})
+for row in batch.get("results", []):
+    print(row.get("wallet"), row.get("label"))
+
+# Cluster — discover wallets connected via on-chain transfers + identity proofs
+cluster = client.pm("polymarket/wallet/0xabc.../cluster")
+for related in cluster.get("cluster", []):
+    print(related.get("wallet"), related.get("relationship_type"), related.get("confidence_score"))
+```
+
+## Common Workflows
+
+**"What are people betting on in crypto right now?"**
+```python
+events = client.pm("polymarket/search", q="crypto bitcoin ethereum")
+for e in events.get("data", [])[:5]:
+    print(e.get("title", "?"))
+    for o in e.get("outcomes", []):
+        print(f"  {o.get('title')}: {o.get('price')} (implies {round(float(o.get('price', 0))*100)}%)")
+```
+
+**"Track a smart wallet's identity + cluster"**
+```python
+seed = "0xabc..."
+ident = client.pm(f"polymarket/wallet/identity/{seed}")
+cluster = client.pm(f"polymarket/wallet/{seed}/cluster")
+print(f"{ident.get('label')} (ENS {ident.get('ens_name')})")
+print(f"  Cluster size: {len(cluster.get('cluster', []))} wallets")
+```
+
+**"What's the probability of X event?"**
+```python
+# 1. Search for the event
+results = client.pm("polymarket/search", q="US election 2026")
+
+# 2. Get specific market details
+if results.get("data"):
+    market_id = results["data"][0].get("id", results["data"][0].get("slug"))
+    detail = client.pm(f"polymarket/events/{market_id}")
+    print(detail)
+```
+
+**"Show me all active Kalshi markets"**
+```python
+data = client.pm_query("kalshi/query", {"limit": 50, "status": "open"})
+markets = data.get("markets", data.get("data", []))
+for m in markets[:10]:
+    print(f"{m.get('ticker')} — {m.get('title')}: YES={m.get('yes_bid')} NO={m.get('no_bid')}")
+```
+
+## Data Case Study: Sentiment Signal from Markets
+
+Prediction markets are often better probability estimates than polls or pundit takes. Pattern:
+
+```python
+import json
+
+# 1. Find relevant markets
+crypto_markets = client.pm("polymarket/search", q="bitcoin price end of year")
+
+# 2. Extract implied probabilities
+for market in crypto_markets.get("data", [])[:3]:
+    print(f"\n{market.get('title', '?')}")
+    for outcome in market.get("outcomes", []):
+        p = float(outcome.get("price", 0)) * 100
+        print(f"  {outcome.get('title')}: {p:.0f}% implied probability")
+
+# 3. Save for later analysis
+with open(os.path.expanduser("~/.blockrun/data/markets_snapshot.json"), "w") as f:
+    json.dump(crypto_markets, f, indent=2, default=str)
+```
+
+## Notes on Response Shape
+
+Predexon returns raw API responses. Structure varies by exchange:
+- **Polymarket**: usually `{ "data": [...] }` or `{ "events": [...] }`
+- **Kalshi**: usually `{ "markets": [...] }` with `ticker`, `yes_bid`, `no_bid` fields
+- **Print raw response first** when exploring a new path: `print(json.dumps(result, indent=2)[:1000])`
+
+## Requirements
+
+- BlockRun SDK: `pip install blockrun-llm`
+- USDC wallet funded (`client.get_balance()`)
+- Kalshi tickers: format is `KXBTC-25MAR14` (series + expiry date)

package/skills/rpc/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: rpc
+description: Use when the user needs raw blockchain JSON-RPC access — contract reads (eth_call), native balances, blocks, transactions, logs, gas estimates, or any chain-native RPC method across 40+ chains. One endpoint per chain via BlockRun's Tatum-backed gateway, $0.002 per call, no node, no API key. Prefer blockrun_price / blockrun_dex / blockrun_surf when they already cover the question.
+triggers:
+  - "rpc"
+  - "json-rpc"
+  - "eth_call"
+  - "contract read"
+  - "raw chain"
+  - "node access"
+  - "blockchain rpc"
+  - "getBalance"
+  - "block number"
+  - "transaction receipt"
+  - "event logs"
+  - "tatum"
+---
+
+# Multi-chain RPC — 40+ chains, one tool
+
+`blockrun_rpc` POSTs a standard JSON-RPC 2.0 body to `/v1/rpc/{network}`. Flat **$0.002 per call**; a JSON-RPC **batch array charges per element**. Settlement in USDC via x402. Responses are cached briefly server-side for identical read calls (`X-Cache: HIT` is free of upstream latency but still billed).
+
+## When to use which tool
+
+| Question | Tool |
+|---|---|
+| "What's ETH trading at?" | `blockrun_price` (free) |
+| "PEPE/WETH pool liquidity?" | `blockrun_dex` (free) |
+| "What's this wallet labeled as / holding?" | `blockrun_surf` |
+| "Call `balanceOf(0x...)` on this ERC-20" | **`blockrun_rpc`** |
+| "Latest block / tx receipt / event logs / gas price" | **`blockrun_rpc`** |
+| "Solana account info / slot / signatures" | **`blockrun_rpc`** |
+
+## Networks
+
+EVM (use `eth_*` methods):
+
+| Key | Chain | | Key | Chain |
+|---|---|---|---|---|
+| `ethereum` | Ethereum | | `zksync` | zkSync Era |
+| `base` | Base | | `berachain` | Berachain |
+| `arbitrum` | Arbitrum One | | `unichain` | Unichain |
+| `arbitrum-nova` | Arbitrum Nova | | `monad` | Monad |
+| `optimism` | Optimism | | `chiliz` | Chiliz |
+| `polygon` | Polygon | | `moonbeam` | Moonbeam |
+| `bsc` | BNB Smart Chain | | `aurora` | Aurora |
+| `avalanche` | Avalanche C-Chain | | `flare` | Flare |
+| `fantom` | Fantom | | `oasis` | Oasis Sapphire |
+| `cronos` | Cronos | | `kaia` | Kaia (Klaytn) |
+| `celo` | Celo | | `sonic` | Sonic |
+| `gnosis` | Gnosis | | `xdc` | XDC Network |
+| `abstract` | Abstract | | `hyperevm` | HyperEVM |
+| `plume` | Plume | | `ronin` | Ronin |
+| `rootstock` | Rootstock (RSK) | | | |
+
+Non-EVM (chain-native methods):
+
+| Key | Chain | Method family |
+|---|---|---|
+| `solana` | Solana | `getSlot`, `getBalance`, `getAccountInfo`, `getSignaturesForAddress` |
+| `bitcoin` | Bitcoin | `getblockchaininfo`, `getblockcount`, `getrawtransaction` |
+| `litecoin` / `dogecoin` / `bitcoin-cash` / `zcash` | UTXO chains | Bitcoin-style RPC |
+| `near` | NEAR | `status`, `query` |
+| `sui` | Sui | `sui_getLatestCheckpointSequenceNumber`, `suix_getBalance` |
+| `ripple` | XRP Ledger | `account_info`, `ledger` |
+| `polkadot` / `kusama` | Substrate | `chain_getHeader`, `state_getStorage` |
+
+Unknown-but-wellformed slugs pass through to the Tatum gateway untouched — newly added chains work without an MCP update. A bad slug returns HTTP 400 with the supported list (no charge).
+
+## Recipes
+
+ERC-20 balance (eth_call):
+
+```
+blockrun_rpc({
+  network: "base",
+  method: "eth_call",
+  params: [{
+    to: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",   // USDC on Base
+    data: "0x70a08231000000000000000000000000<ADDRESS_NO_0x_PADDED_TO_32B>"
+  }, "latest"]
+})
+```
+
+Native balance: `method: "eth_getBalance", params: ["0x...", "latest"]`
+Tx receipt: `method: "eth_getTransactionReceipt", params: ["0x<txhash>"]`
+Event logs: `method: "eth_getLogs", params: [{ fromBlock, toBlock, address, topics }]` — keep ranges small; huge ranges are rejected upstream (no charge).
+Gas: `method: "eth_gasPrice"` / `eth_estimateGas`
+
+Solana token account: `network: "solana", method: "getTokenAccountsByOwner", params: ["<owner>", {"mint": "<mint>"}, {"encoding": "jsonParsed"}]`
+
+Batch (charged per element — 3 calls = $0.006):
+
+```
+blockrun_rpc({ network: "ethereum", body: [
+  { jsonrpc: "2.0", id: 1, method: "eth_blockNumber" },
+  { jsonrpc: "2.0", id: 2, method: "eth_gasPrice" },
+  { jsonrpc: "2.0", id: 3, method: "eth_chainId" }
+]})
+```
+
+## Failure semantics
+
+- Upstream timeout / 5xx → **no charge**, retry safe.
+- Malformed body / bad network → HTTP 400, **no charge**.
+- JSON-RPC-level errors (e.g. revert on `eth_call`) come back inside `result.error` — the call **is** charged (the node did the work).

package/skills/search/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: search
+description: Use when the user wants real-time web, news, or X/Twitter results with AI-summarized answers and citations — Grok Live Search via BlockRun. Cheapest path for "what just happened" questions where freshness beats neural-semantic ranking.
+triggers:
+  - "live search"
+  - "grok live"
+  - "what just happened"
+  - "real time news"
+  - "breaking news"
+  - "today's news"
+  - "search with citations"
+  - "cited search"
+  - "x search"
+  - "twitter search"
+  - "news search"
+---
+
+# Live Search (Grok)
+
+Real-time web + X/Twitter + news search with AI-summarized results and citations. **$0.025 × `max_results`** (default 10 → $0.25 per call). Best for *fresh* queries; for semantic / neural research use `blockrun_exa` instead.
+
+## How to Call from MCP
+
+```ts
+blockrun_search({ body: {
+  query: "what's the consensus on the Fed's next move",
+  sources: ["web", "news"],
+  max_results: 10
+}})
+```
+
+## Body Shape
+
+| Field | Required | Type | Notes |
+|---|---|---|---|
+| `query` | yes | string | Natural-language search query |
+| `sources` | no | string[] | Subset of `["web","x","news"]`. Default: all three. Does NOT multiply price. |
+| `max_results` | no | number | 1–50, default 10. **Drives the price** at $0.025 each. |
+| `from_date` | no | string | `YYYY-MM-DD` lower bound on result date |
+| `to_date` | no | string | `YYYY-MM-DD` upper bound |
+
+## When to Reach for Which Source
+
+| User intent | `sources` setting |
+|---|---|
+| Breaking news / today's headlines | `["news"]` |
+| What's the CT / KOL sentiment on X | `["x"]` |
+| Backgrounder / explainer / docs | `["web"]` |
+| General "find current info" question | omit — defaults to all three |
+
+## Worked Examples
+
+### 1. "What's the latest on the ETH ETF approval timeline?"
+
+```ts
+blockrun_search({ body: { query: "Ethereum ETF approval SEC", sources: ["news","web"], max_results: 8 } })
+```
+**Cost: $0.025 × 8 = $0.20.**
+
+### 2. "What is X saying about Solana's latest outage?"
+
+```ts
+blockrun_search({ body: { query: "Solana outage today", sources: ["x"], max_results: 15 } })
+```
+**Cost: $0.025 × 15 = $0.375.**
+
+### 3. "Background on Pectra upgrade, last 90 days only"
+
+```ts
+blockrun_search({ body: {
+  query: "Ethereum Pectra upgrade",
+  sources: ["web","news"],
+  from_date: "2026-02-17"
+}})
+```
+**Cost: $0.025 × 10 (default) = $0.25.**
+
+## search vs exa — Pick the Right Tool
+
+| Use case | Tool |
+|---|---|
+| "What's happening *right now*?" — freshness matters | `blockrun_search` |
+| "Find the canonical paper on X" — semantic relevance matters | `blockrun_exa` |
+| "Pull the full text of these 5 URLs" — content fetch | `blockrun_exa` `contents` |
+| "Cited answer to a question" | both work; `blockrun_exa answer` is grounded in pre-indexed corpus, `blockrun_search` searches the live web |
+
+## Notes
+
+- Returns AI-summarized text + a list of sources with URLs. The summary is one paragraph; sources let you drill in.
+- **Price is per result, not per source.** `max_results: 20` with one source or three sources both cost $0.025 × 20 = $0.50. Pass a smaller `max_results` to cap spend.
+- Date filters are strict — results outside the window are dropped, not down-ranked.
+
+## Reference
+
+- Endpoint: `POST /v1/search`
+- Upstream: xAI Grok Live Search