@blockrun/mcp 0.20.0 → 0.21.0

package/README.md

@@ -135,7 +135,7 @@ $5 covers ~5,000 market queries, ~500 Exa searches, ~250 image generations, or ~
 | `blockrun_chat` | 66+ LLMs (GPT, Claude, Gemini, DeepSeek, Kimi K2.6, GLM, NVIDIA free tier, ...) with `mode` tier routing | per token |
 | `blockrun_image` | GPT Image 1/2, Nano Banana / Pro (up to 4K), Grok Imagine, CogView-4 — generation + img2img editing | $0.015–0.15 |
 | `blockrun_video` | Sora 2 + xAI Grok Imagine Video + ByteDance Seedance 1.5/2.0/2.0-fast (720p + audio defaults); RealFace asset → real-person video | $0.05–0.30/sec |
-| `blockrun_realface` | Enroll a real person (phone liveness → `ta_xxxx` asset) for Seedance 2.0 real-person video | free; $0.01 to enroll |
+| `blockrun_realface` | Enroll a real person (phone liveness) or an AI character (Virtual Portrait, no liveness) as a `ta_xxxx` asset for Seedance 2.0 video | free; $0.01 to enroll |
 | `blockrun_music` | MiniMax music generation | per track |
 | `blockrun_speech` | ElevenLabs text-to-speech (Flash/Turbo/Multilingual/v3, 8 voice aliases) + cinematic sound effects; free voice listing | $0.05–0.10/1k chars; $0.0525/effect |
 | `blockrun_price` | Pyth-backed realtime + OHLC — crypto / FX / commodity (free), 12 stock markets (paid) | free or $0.001/call |
@@ -145,6 +145,7 @@ $5 covers ~5,000 market queries, ~500 Exa searches, ~250 image generations, or ~
 | `blockrun_search` | Grok Live Search — web + news with citations | $0.025 × max_results (default 10) |
 | `blockrun_dex` | Live DEX prices via DexScreener | free |
 | `blockrun_rpc` | Raw JSON-RPC on 40+ chains (Ethereum, Base, Solana, Bitcoin, Sui, NEAR, ...) via Tatum gateway — eth_call, balances, blocks, logs | $0.002/call |
+| `blockrun_defi` | DefiLlama — protocol TVL, chain TVL, yield pools (APY), token prices | $0.001–0.005/call |
 | `blockrun_modal` | Isolated code execution in a BlockRun-hosted Modal sandbox — disposable container, optional GPU (T4 → H100) | $0.01 create; $0.001/op |
 | `blockrun_phone` | Outbound AI voice calls (Bland) + wallet-owned US/CA numbers (Twilio), carrier + fraud lookups | $0.54/call; $5/number |
 | `blockrun_models` | Live catalogue of every LLM/image/video/music model + pricing | free |

package/dist/index.js

@@ -1907,6 +1907,46 @@ async function fetchWithTimeout4(url, options, timeoutMs) {
     clearTimeout(id);
   }
 }
+async function payAndPostJson(url, reqBody, fallbackDescription) {
+  const privateKey = getOrCreateWalletKey();
+  const account = privateKeyToAccount4(privateKey);
+  const resp402 = await fetchWithTimeout4(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: reqBody
+  }, 15e3);
+  if (resp402.status !== 402) {
+    const data2 = await resp402.json().catch(() => ({}));
+    throw new Error(`Expected 402, got ${resp402.status}: ${data2.message || data2.error || JSON.stringify(data2)}`);
+  }
+  const prHeader = resp402.headers.get("payment-required") || resp402.headers.get("PAYMENT-REQUIRED");
+  if (!prHeader) throw new Error("No PAYMENT-REQUIRED header in 402 response");
+  const paymentRequired = parsePaymentRequired4(prHeader);
+  const details = extractPaymentDetails4(paymentRequired);
+  const paymentPayload = await createPaymentPayload4(
+    privateKey,
+    account.address,
+    details.recipient,
+    details.amount,
+    details.network || "eip155:8453",
+    {
+      resourceUrl: details.resource?.url || url,
+      resourceDescription: details.resource?.description || fallbackDescription,
+      maxTimeoutSeconds: Math.max(details.maxTimeoutSeconds || 0, 120),
+      extra: details.extra
+    }
+  );
+  const resp = await fetchWithTimeout4(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "PAYMENT-SIGNATURE": paymentPayload
+    },
+    body: reqBody
+  }, 9e4);
+  const data = await resp.json().catch(() => ({}));
+  return { status: resp.status, data };
+}
 function registerRealfaceTool(server, budget) {
   server.registerTool(
     "blockrun_realface",
@@ -1919,7 +1959,8 @@ Actions:
 - init: FREE. Create an asset group + a phone H5 link. The tool renders the link as a QR code and opens it; the real person scans it on their phone and completes the ~1 min liveness check. Pass group_id to refresh an expired link.
 - status: FREE. Poll a group until status:"active" (ready_to_finalize:true). The H5 link is valid ~120s \u2014 re-init if it expires.
 - enroll: PAID ($0.01 USDC, Base only). After the group is active, upload a clear front-facing photo (image_url) of the SAME person. Returns the ta_xxxx asset id.
-- list: FREE. List the RealFace assets enrolled by this wallet (their ta_xxxx ids + names) so you can pick one for blockrun_video.
+- portrait: PAID ($0.01 USDC, Base only). Virtual Portrait \u2014 enroll an AI-GENERATED character from an image URL directly, NO liveness needed (one step: name + image_url \u2192 ta_xxxx). For fictional/AI characters only; for a real person use the init\u2192status\u2192enroll liveness flow.
+- list: FREE. List the RealFace + Virtual Portrait assets enrolled by this wallet (their ta_xxxx ids + names) so you can pick one for blockrun_video.
 
 Typical flow:
   1. blockrun_realface action:"init" name:"Alice"          \u2192 scan QR on phone, do liveness
@@ -1929,10 +1970,10 @@ Typical flow:
 
 Privacy: BlockRun does not store face/liveness data \u2014 only the asset id, name, and the photo URL you supply.`,
       inputSchema: {
-        action: z8.enum(["init", "status", "enroll", "list"]).describe("What to do"),
-        name: z8.string().min(1).max(64).optional().describe("Display name for the person (required for init and enroll)."),
-        group_id: z8.string().regex(/^legacy_rf_\d+$/).optional().describe("Asset-group id from init (required for status and enroll; pass to init to refresh an expired H5 link)."),
-        image_url: z8.string().url().optional().describe("Public HTTPS URL to a clear front-facing face photo (JPG/PNG/WEBP, \u226410MB). Required for enroll."),
+        action: z8.enum(["init", "status", "enroll", "portrait", "list"]).describe("What to do"),
+        name: z8.string().min(1).max(64).optional().describe("Display name for the person/character (required for init, enroll, and portrait)."),
+        group_id: z8.string().regex(/^legacy_rf_\d+$/).optional().describe("Asset-group id from init (required for status and enroll; pass to init to refresh an expired H5 link). Not used by portrait."),
+        image_url: z8.string().url().optional().describe("Public HTTPS URL to a clear front-facing face image (JPG/PNG/WEBP, \u226410MB). Required for enroll and portrait."),
         agent_id: z8.string().optional().describe("Agent identifier for budget tracking and enforcement (enroll only).")
       }
     },
@@ -2022,30 +2063,88 @@ QR opened for scanning (${qrPath}).`;
         }
         if (action === "list") {
           const account = privateKeyToAccount4(getOrCreateWalletKey());
-          const resp = await fetchWithTimeout4(`${BLOCKRUN_API4}/v1/wallet/${account.address}/realfaces`, {
-            method: "GET"
-          }, 3e4);
-          const data = await resp.json().catch(() => ({}));
-          if (!resp.ok) {
-            return { content: [{ type: "text", text: formatError(`list failed (${resp.status}): ${data.error || JSON.stringify(data)}`) }], isError: true };
+          const [rfResp, vpResp] = await Promise.all([
+            fetchWithTimeout4(`${BLOCKRUN_API4}/v1/wallet/${account.address}/realfaces`, { method: "GET" }, 3e4),
+            fetchWithTimeout4(`${BLOCKRUN_API4}/v1/wallet/${account.address}/portraits`, { method: "GET" }, 3e4).catch(() => null)
+          ]);
+          const data = await rfResp.json().catch(() => ({}));
+          if (!rfResp.ok) {
+            return { content: [{ type: "text", text: formatError(`list failed (${rfResp.status}): ${data.error || JSON.stringify(data)}`) }], isError: true };
           }
           const faces = Array.isArray(data.realfaces) ? data.realfaces : [];
-          if (faces.length === 0) {
+          let portraits = [];
+          if (vpResp?.ok) {
+            const vpData = await vpResp.json().catch(() => ({}));
+            portraits = Array.isArray(vpData.portraits) ? vpData.portraits : [];
+          }
+          if (faces.length === 0 && portraits.length === 0) {
             return {
-              content: [{ type: "text", text: `No RealFace assets enrolled for ${account.address}.
-Enroll one: blockrun_realface action:"init" name:"\u2026".` }],
-              structuredContent: { wallet: account.address, realfaces: [], count: 0 }
+              content: [{ type: "text", text: `No RealFace or Virtual Portrait assets enrolled for ${account.address}.
+Enroll one: blockrun_realface action:"init" name:"\u2026" (real person) or action:"portrait" name:"\u2026" image_url:"https://\u2026" (AI character).` }],
+              structuredContent: { wallet: account.address, realfaces: [], portraits: [], count: 0 }
             };
           }
+          const first = faces[0] ?? portraits[0];
           const lines = [
-            `RealFace assets for ${account.address} (${faces.length}):`,
-            ...faces.map((f) => `  \u2022 ${f.assetId}  \u2014  "${f.name}"${f.createdAt ? `  (${f.createdAt})` : ""}`),
+            `Assets for ${account.address} (${faces.length} RealFace, ${portraits.length} Virtual Portrait):`,
+            ...faces.map((f) => `  \u2022 ${f.assetId}  \u2014  "${f.name}" [realface]${f.createdAt ? `  (${f.createdAt})` : ""}`),
+            ...portraits.map((p) => `  \u2022 ${p.assetId}  \u2014  "${p.name}" [portrait]${p.createdAt ? `  (${p.createdAt})` : ""}`),
             ``,
-            `Use one: blockrun_video model:"bytedance/seedance-2.0" real_face_asset_id:"${faces[0].assetId}" prompt:"\u2026".`
+            `Use one: blockrun_video model:"bytedance/seedance-2.0" real_face_asset_id:"${first.assetId}" prompt:"\u2026".`
           ];
           return {
             content: [{ type: "text", text: lines.join("\n") }],
-            structuredContent: { wallet: account.address, realfaces: faces, count: faces.length }
+            structuredContent: { wallet: account.address, realfaces: faces, portraits, count: faces.length + portraits.length }
+          };
+        }
+        if (action === "portrait") {
+          if (getChain() !== "base") {
+            return { content: [{ type: "text", text: formatError("blockrun_realface portrait settles on Base only. Switch BlockRun to Base (run blockrun_wallet with action:chain chain:base) and fund the Base wallet with USDC.") }], isError: true };
+          }
+          if (!name || !image_url) {
+            return { content: [{ type: "text", text: formatError("portrait requires name and image_url (public HTTPS URL of an AI-generated character image).") }], isError: true };
+          }
+          const budgetCheck = checkBudget(budget, agent_id, ENROLLMENT_PRICE_USD);
+          if (!budgetCheck.allowed) {
+            return { content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }], isError: true };
+          }
+          const { status, data } = await payAndPostJson(
+            `${BLOCKRUN_API4}/v1/portrait/enroll`,
+            JSON.stringify({ name, image_url }),
+            "BlockRun Virtual Portrait enrollment"
+          );
+          if (status === 402) {
+            throw new Error("Payment rejected. Check your wallet balance.");
+          }
+          if (status === 422) {
+            return { content: [{ type: "text", text: formatError(`Portrait rejected \u2014 ${data.hint || data.message || "use a clear front-facing character image"}. No payment taken.`) }], isError: true };
+          }
+          if (status < 200 || status >= 300) {
+            throw new Error(`Portrait enroll error ${status}: ${data.error || JSON.stringify(data)}`);
+          }
+          const assetId = data.asset_id;
+          if (!assetId) throw new Error(`Portrait response missing asset_id: ${JSON.stringify(data)}`);
+          recordSpending(budget, ENROLLMENT_PRICE_USD, agent_id);
+          const txHash = data.settlement?.tx_hash || void 0;
+          const lines = [
+            `\u2705 Virtual Portrait enrolled!`,
+            `Asset ID: ${assetId}`,
+            `Name: ${data.name || name}`,
+            `Cost: $${ENROLLMENT_PRICE_USD.toFixed(2)} USDC`,
+            ...txHash ? [`Tx: ${txHash}`] : [],
+            ``,
+            `Use it: blockrun_video model:"bytedance/seedance-2.0" real_face_asset_id:"${assetId}" prompt:"\u2026".`
+          ];
+          return {
+            content: [{ type: "text", text: lines.join("\n") }],
+            structuredContent: {
+              asset_id: assetId,
+              group_id: data.group_id,
+              name: data.name || name,
+              image_url: data.image_url,
+              price_usd: ENROLLMENT_PRICE_USD,
+              ...txHash ? { txHash } : {}
+            }
           };
         }
         if (action === "enroll") {
@@ -2874,6 +2973,63 @@ Prefer blockrun_price (free quotes), blockrun_dex (free DEX data), or blockrun_s
   );
 }
 
+// src/tools/defi.ts
+import { z as z18 } from "zod";
+function estimateDefiCost(path5) {
+  return path5.startsWith("prices") ? 1e-3 : 5e-3;
+}
+function registerDefiTool(server, budget) {
+  server.registerTool(
+    "blockrun_defi",
+    {
+      description: `DeFi fundamentals via DefiLlama \u2014 protocol TVL, chain TVL, yield pools (APY), token prices. Pays per call in USDC, no API key.
+
+Paths (GET only):
+- protocols                      ($0.005) \u2014 all DeFi protocols ranked by TVL
+- protocol/{slug}                ($0.005) \u2014 one protocol's TVL history + chain breakdown, e.g. protocol/aave-v3
+- chains                         ($0.005) \u2014 TVL by chain
+- yields                         ($0.005) \u2014 yield pools with APY + TVL (large; filter client-side)
+- prices/{coins}                 ($0.001) \u2014 token prices, coins like 'base:0x833589...,coingecko:ethereum'
+
+Examples:
+  blockrun_defi({ path: "protocol/uniswap-v3" })
+  blockrun_defi({ path: "prices/coingecko:bitcoin,coingecko:ethereum" })
+  blockrun_defi({ path: "chains" })
+
+Use blockrun_price (free) for plain spot quotes, blockrun_dex (free) for DEX pairs, blockrun_surf for labeled on-chain data \u2014 this tool is for protocol/TVL/yield fundamentals.`,
+      inputSchema: {
+        path: z18.string().describe("Endpoint under /v1/defillama/, e.g. 'protocols', 'protocol/aave-v3', 'chains', 'yields', 'prices/coingecko:ethereum'"),
+        agent_id: z18.string().optional().describe("Agent identifier for budget tracking and enforcement.")
+      }
+    },
+    async ({ path: path5, agent_id }) => {
+      try {
+        const cleanPath = path5.replace(/^\/+/, "").replace(/^v1\/defillama\//, "").replace(/^api\/v1\/defillama\//, "");
+        const estimatedCost = estimateDefiCost(cleanPath);
+        const budgetCheck = checkBudget(budget, agent_id, estimatedCost);
+        if (!budgetCheck.allowed) {
+          return {
+            content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
+            isError: true
+          };
+        }
+        const client = getClient();
+        const result = await client.getWithPaymentRaw(`/v1/defillama/${cleanPath}`);
+        recordSpending(budget, estimatedCost, agent_id);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+          structuredContent: typeof result === "object" && result !== null && !Array.isArray(result) ? result : { result }
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: formatError(extractErrorMessage(err)) }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
 // src/mcp-handler.ts
 function initializeMcpServer(server) {
   const budget = { limit: null, spent: 0, calls: 0, agents: /* @__PURE__ */ new Map() };
@@ -2895,6 +3051,7 @@ function initializeMcpServer(server) {
   registerPhoneTool(server, budget);
   registerSurfTool(server, budget);
   registerRpcTool(server, budget);
+  registerDefiTool(server, budget);
   server.registerResource(
     "wallet",
     "blockrun://wallet",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/mcp",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "mcpName": "io.github.BlockRunAI/blockrun-mcp",
   "description": "BlockRun MCP Server - Give your AI agent web search, deep research, prediction markets, crypto data, X/Twitter intelligence. Paid via x402 micropayments.",
   "type": "module",