@blockrun/llm 2.7.0 → 2.8.0

package/README.md

@@ -84,8 +84,8 @@ Four call shapes cover every endpoint type:
 - `stream<T>(path, body?)` — async iterator over SSE chunks (chat)
 
 The per-API client classes (`LLMClient`, `ImageClient`, `VideoClient`,
-`VoiceClient`, `MusicClient`, `SearchClient`, `XClient`, `PriceClient`,
-`SurfClient`) all remain — they will be soft-deprecated in 2.6 (rewritten as
+`PortraitClient`, `VoiceClient`, `MusicClient`, `SearchClient`, `XClient`,
+`PriceClient`, `SurfClient`) all remain — they will be soft-deprecated in 2.6 (rewritten as
 shims over `BlockrunClient`) and removed in 3.0.
 
 ### Try It Free (No USDC Required)
@@ -441,6 +441,35 @@ const r3 = await client.generate('aerial drone shot over a snowy mountain', {
 });
 ```
 
+### Virtual Portraits
+
+`PortraitClient` wraps `POST /v1/portrait/enroll` (paid, flat **$0.01** promo,
+no KYC). Enroll a face image by URL and get back a Token360 asset id (`ta_xxxxxx`).
+Pass that id as `realFaceAssetId` on a Seedance 2.0 video generation to keep the
+same AI character across clips. Payment settles only after Token360 confirms the
+enrollment, so a failed enrollment never charges your wallet. The returned
+`image_url` is a gateway-mirrored copy of your source image (see `mirrored` /
+`source_image_url`). (Real-person likeness is not supported on BlockRun —
+enrolled portraits are AI characters.)
+
+```ts
+import { PortraitClient, VideoClient } from '@blockrun/llm';
+
+const portraits = new PortraitClient();
+const { asset_id } = await portraits.enroll({
+  name: 'Spokesperson',
+  imageUrl: 'https://example.com/face.jpg',  // public https JPG/PNG/WEBP, ≤10 MB
+});
+
+// Reuse the same character across Seedance 2.0 clips
+const video = new VideoClient();
+const clip = await video.generate('she waves and smiles', {
+  model: 'bytedance/seedance-2.0-fast',
+  realFaceAssetId: asset_id,
+});
+console.log(clip.data[0].url);
+```
+
 ### Voice Calls
 
 `VoiceClient` wraps `POST /v1/voice/call` (paid, $0.54/call) and

package/dist/index.cjs

@@ -41,8 +41,10 @@ __export(index_exports, {
   MusicClient: () => MusicClient,
   OpenAI: () => OpenAI,
   PHONE_PRICES: () => PHONE_PRICES,
+  PORTRAIT_ENROLLMENT_PRICE_USD: () => PORTRAIT_ENROLLMENT_PRICE_USD,
   PaymentError: () => PaymentError,
   PhoneClient: () => PhoneClient,
+  PortraitClient: () => PortraitClient,
   PriceClient: () => PriceClient,
   SOLANA_NETWORK: () => SOLANA_NETWORK,
   SOLANA_WALLET_FILE_PATH: () => SOLANA_WALLET_FILE,
@@ -2999,15 +3001,18 @@ var PhoneClient = class {
   }
 };
 
-// src/search.ts
+// src/portrait.ts
 var import_accounts8 = require("viem/accounts");
 var DEFAULT_API_URL7 = "https://blockrun.ai/api";
 var DEFAULT_TIMEOUT7 = 6e4;
-var SearchClient = class {
+var PORTRAIT_ENROLLMENT_PRICE_USD = 0.01;
+var PortraitClient = class {
   account;
   privateKey;
   apiUrl;
   timeout;
+  sessionTotalUsd = 0;
+  sessionCalls = 0;
   constructor(options = {}) {
     const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
     const privateKey = options.privateKey || envKey;
@@ -3024,6 +3029,157 @@ var SearchClient = class {
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT7;
   }
+  /** EVM wallet address used for payments. */
+  getWalletAddress() {
+    return this.account.address;
+  }
+  /** Session-cumulative USD spend + call count across this client instance. */
+  getSpending() {
+    return { totalUsd: this.sessionTotalUsd, calls: this.sessionCalls };
+  }
+  /**
+   * Enroll a Virtual Portrait from a face image URL. $0.01 (promo).
+   *
+   * Payment is settled only after Token360 confirms the enrollment, so failed
+   * enrollments never charge your wallet.
+   *
+   * @param options.name     Display name (1–64 chars).
+   * @param options.imageUrl Public HTTPS URL to a JPG/PNG/WEBP image (≤10 MB).
+   * @returns The enrollment record, including `asset_id` (`ta_xxxxxx`).
+   */
+  async enroll(options) {
+    const name = typeof options?.name === "string" ? options.name.trim() : "";
+    if (name.length < 1 || name.length > 64) {
+      throw new Error("name is required and must be 1\u201364 characters");
+    }
+    const imageUrl = typeof options?.imageUrl === "string" ? options.imageUrl.trim() : "";
+    if (!/^https?:\/\//i.test(imageUrl)) {
+      throw new Error(
+        "imageUrl must be a public http(s) URL to a JPG/PNG/WEBP image"
+      );
+    }
+    const data = await this.request({
+      name,
+      image_url: imageUrl
+    });
+    return data;
+  }
+  // ─── Internals ─────────────────────────────────────────────────────────
+  async request(body) {
+    const url = `${this.apiUrl}/v1/portrait/enroll`;
+    const response = await this.fetchWithTimeout(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    if (response.status === 402) {
+      return this.handlePaymentAndRetry(url, body, response);
+    }
+    return this.unwrap(response, false);
+  }
+  async handlePaymentAndRetry(url, body, response) {
+    let paymentHeader = response.headers.get("payment-required");
+    if (!paymentHeader) {
+      try {
+        const rb = await response.json();
+        if (rb.x402 || rb.accepts) paymentHeader = btoa(JSON.stringify(rb));
+      } catch {
+      }
+    }
+    if (!paymentHeader) {
+      throw new PaymentError("402 response but no payment requirements found");
+    }
+    const paymentRequired = parsePaymentRequired(paymentHeader);
+    const details = extractPaymentDetails(paymentRequired);
+    const paymentPayload = await createPaymentPayload(
+      this.privateKey,
+      this.account.address,
+      details.recipient,
+      details.amount,
+      details.network || "eip155:8453",
+      {
+        resourceUrl: details.resource?.url || url,
+        resourceDescription: details.resource?.description || "BlockRun Virtual Portrait",
+        maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+        extra: details.extra
+      }
+    );
+    const retry = await this.fetchWithTimeout(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "PAYMENT-SIGNATURE": paymentPayload
+      },
+      body: JSON.stringify(body)
+    });
+    if (retry.status === 402) {
+      throw new PaymentError("Payment was rejected. Check your wallet balance.");
+    }
+    const data = await this.unwrap(retry, true);
+    const costUsd = Number.parseFloat(details.amount) / 1e6;
+    this.sessionCalls += 1;
+    this.sessionTotalUsd += costUsd;
+    if (data && typeof data === "object" && !("txHash" in data)) {
+      const settlement = data.settlement;
+      if (settlement?.tx_hash) {
+        data.txHash = settlement.tx_hash;
+      }
+    }
+    return data;
+  }
+  async unwrap(response, afterPayment) {
+    if (response.ok) {
+      return response.json();
+    }
+    let errorBody;
+    try {
+      errorBody = await response.json();
+    } catch {
+      errorBody = { error: "Request failed" };
+    }
+    const prefix = afterPayment ? "API error after payment" : "API error";
+    throw new APIError(
+      `${prefix}: ${response.status}`,
+      response.status,
+      sanitizeErrorResponse(errorBody)
+    );
+  }
+  async fetchWithTimeout(url, init) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      return await fetch(url, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+};
+
+// src/search.ts
+var import_accounts9 = require("viem/accounts");
+var DEFAULT_API_URL8 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT8 = 6e4;
+var SearchClient = class {
+  account;
+  privateKey;
+  apiUrl;
+  timeout;
+  constructor(options = {}) {
+    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
+    const privateKey = options.privateKey || envKey;
+    if (!privateKey) {
+      throw new Error(
+        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+      );
+    }
+    validatePrivateKey(privateKey);
+    this.privateKey = privateKey;
+    this.account = (0, import_accounts9.privateKeyToAccount)(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL8;
+    validateApiUrl(apiUrl);
+    this.apiUrl = apiUrl.replace(/\/$/, "");
+    this.timeout = options.timeout || DEFAULT_TIMEOUT8;
+  }
   async search(query, options) {
     if (!query || query.length > 1e3) {
       throw new Error("query must be 1-1000 characters");
@@ -3136,9 +3292,9 @@ var SearchClient = class {
 };
 
 // src/x-client.ts
-var import_accounts9 = require("viem/accounts");
-var DEFAULT_API_URL8 = "https://blockrun.ai/api";
-var DEFAULT_TIMEOUT8 = 6e4;
+var import_accounts10 = require("viem/accounts");
+var DEFAULT_API_URL9 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT9 = 6e4;
 var XClient = class _XClient {
   account;
   privateKey;
@@ -3161,11 +3317,11 @@ var XClient = class _XClient {
     }
     validatePrivateKey(privateKey);
     this.privateKey = privateKey;
-    this.account = (0, import_accounts9.privateKeyToAccount)(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL8;
+    this.account = (0, import_accounts10.privateKeyToAccount)(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL9;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
-    this.timeout = options.timeout || DEFAULT_TIMEOUT8;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT9;
   }
   // ───────── User endpoints ─────────
   userLookup(usernames) {
@@ -3343,9 +3499,9 @@ var XClient = class _XClient {
 };
 
 // src/price.ts
-var import_accounts10 = require("viem/accounts");
-var DEFAULT_API_URL9 = "https://blockrun.ai/api";
-var DEFAULT_TIMEOUT9 = 3e4;
+var import_accounts11 = require("viem/accounts");
+var DEFAULT_API_URL10 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT10 = 3e4;
 var PriceClient = class {
   account = null;
   privateKey = null;
@@ -3363,12 +3519,12 @@ var PriceClient = class {
     if (privateKey) {
       validatePrivateKey(privateKey);
       this.privateKey = privateKey;
-      this.account = (0, import_accounts10.privateKeyToAccount)(privateKey);
+      this.account = (0, import_accounts11.privateKeyToAccount)(privateKey);
     }
-    const apiUrl = options.apiUrl || DEFAULT_API_URL9;
+    const apiUrl = options.apiUrl || DEFAULT_API_URL10;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
-    this.timeout = options.timeout || DEFAULT_TIMEOUT9;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT10;
   }
   async price(category, symbol, options) {
     if (!symbol) throw new Error("symbol is required");
@@ -3547,9 +3703,9 @@ function buildUrl(base, query) {
 }
 
 // src/surf.ts
-var import_accounts11 = require("viem/accounts");
-var DEFAULT_API_URL10 = "https://blockrun.ai/api";
-var DEFAULT_TIMEOUT10 = 6e4;
+var import_accounts12 = require("viem/accounts");
+var DEFAULT_API_URL11 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT11 = 6e4;
 var SURF_PREFIX = "/v1/surf";
 var SurfClient = class {
   account;
@@ -3566,11 +3722,11 @@ var SurfClient = class {
     }
     validatePrivateKey(privateKey);
     this.privateKey = privateKey;
-    this.account = (0, import_accounts11.privateKeyToAccount)(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL10;
+    this.account = (0, import_accounts12.privateKeyToAccount)(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL11;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
-    this.timeout = options.timeout || DEFAULT_TIMEOUT10;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT11;
   }
   /**
    * GET a Surf endpoint. `path` is everything after `/v1/surf` (a leading
@@ -3702,9 +3858,9 @@ var SurfClient = class {
 };
 
 // src/blockrun.ts
-var import_accounts12 = require("viem/accounts");
-var DEFAULT_API_URL11 = "https://blockrun.ai/api";
-var DEFAULT_TIMEOUT11 = 6e4;
+var import_accounts13 = require("viem/accounts");
+var DEFAULT_API_URL12 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT12 = 6e4;
 var DEFAULT_POLL_INTERVAL_MS = 5e3;
 var DEFAULT_POLL_BUDGET_MS = 3e5;
 var MAX_SIGNED_AUTH_SECONDS = 600;
@@ -3725,11 +3881,11 @@ var BlockrunClient = class {
     }
     validatePrivateKey(privateKey);
     this.privateKey = privateKey;
-    this.account = (0, import_accounts12.privateKeyToAccount)(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL11;
+    this.account = (0, import_accounts13.privateKeyToAccount)(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL12;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
-    this.timeout = options.timeout || DEFAULT_TIMEOUT11;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT12;
   }
   /**
    * GET a BlockRun endpoint. `path` is everything after `/api` (a leading
@@ -4080,7 +4236,7 @@ function sleep(ms) {
 }
 
 // src/wallet.ts
-var import_accounts13 = require("viem/accounts");
+var import_accounts14 = require("viem/accounts");
 var fs2 = __toESM(require("fs"), 1);
 var path2 = __toESM(require("path"), 1);
 var os2 = __toESM(require("os"), 1);
@@ -4089,8 +4245,8 @@ var BASE_CHAIN_ID2 = "8453";
 var WALLET_DIR = path2.join(os2.homedir(), ".blockrun");
 var WALLET_FILE = path2.join(WALLET_DIR, ".session");
 function createWallet() {
-  const privateKey = (0, import_accounts13.generatePrivateKey)();
-  const account = (0, import_accounts13.privateKeyToAccount)(privateKey);
+  const privateKey = (0, import_accounts14.generatePrivateKey)();
+  const account = (0, import_accounts14.privateKeyToAccount)(privateKey);
   return {
     address: account.address,
     privateKey
@@ -4146,12 +4302,12 @@ function loadWallet() {
 function getOrCreateWallet() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
   if (envKey) {
-    const account = (0, import_accounts13.privateKeyToAccount)(envKey);
+    const account = (0, import_accounts14.privateKeyToAccount)(envKey);
     return { address: account.address, privateKey: envKey, isNew: false };
   }
   const fileKey = loadWallet();
   if (fileKey) {
-    const account = (0, import_accounts13.privateKeyToAccount)(fileKey);
+    const account = (0, import_accounts14.privateKeyToAccount)(fileKey);
     return { address: account.address, privateKey: fileKey, isNew: false };
   }
   const { address, privateKey } = createWallet();
@@ -4161,11 +4317,11 @@ function getOrCreateWallet() {
 function getWalletAddress() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
   if (envKey) {
-    return (0, import_accounts13.privateKeyToAccount)(envKey).address;
+    return (0, import_accounts14.privateKeyToAccount)(envKey).address;
   }
   const fileKey = loadWallet();
   if (fileKey) {
-    return (0, import_accounts13.privateKeyToAccount)(fileKey).address;
+    return (0, import_accounts14.privateKeyToAccount)(fileKey).address;
   }
   return null;
 }
@@ -4345,7 +4501,7 @@ async function getOrCreateSolanaWallet() {
 // src/solana-client.ts
 var SOLANA_API_URL = "https://sol.blockrun.ai/api";
 var DEFAULT_MAX_TOKENS2 = 1024;
-var DEFAULT_TIMEOUT12 = 6e4;
+var DEFAULT_TIMEOUT13 = 6e4;
 var SDK_VERSION2 = "0.3.0";
 var USER_AGENT2 = `blockrun-ts/${SDK_VERSION2}`;
 var DEFAULT_SOLANA_RPC_URL = "https://sol.blockrun.ai/api/v1/solana/rpc";
@@ -4395,7 +4551,7 @@ var SolanaLLMClient = class {
     const rpc = resolveRpcConfig(options.rpcUrl, options.rpcHeaders);
     this.rpcUrl = rpc.url;
     this.rpcHeaders = rpc.headers;
-    this.timeout = options.timeout || DEFAULT_TIMEOUT12;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT13;
   }
   /** Get Solana wallet address (public key in base58). */
   async getWalletAddress() {
@@ -5305,7 +5461,7 @@ var OpenAI = class {
 };
 
 // src/anthropic-compat.ts
-var import_accounts14 = require("viem/accounts");
+var import_accounts15 = require("viem/accounts");
 var AnthropicClient = class {
   _client = null;
   _clientPromise = null;
@@ -5318,7 +5474,7 @@ var AnthropicClient = class {
     const key = options.privateKey ?? wallet.privateKey;
     validatePrivateKey(key);
     this._privateKey = key;
-    this._account = (0, import_accounts14.privateKeyToAccount)(this._privateKey);
+    this._account = (0, import_accounts15.privateKeyToAccount)(this._privateKey);
     const apiUrl = options.apiUrl ?? "https://blockrun.ai/api";
     validateApiUrl(apiUrl);
     this._apiUrl = apiUrl.replace(/\/$/, "");
@@ -5425,8 +5581,10 @@ var AnthropicClient = class {
   MusicClient,
   OpenAI,
   PHONE_PRICES,
+  PORTRAIT_ENROLLMENT_PRICE_USD,
   PaymentError,
   PhoneClient,
+  PortraitClient,
   PriceClient,
   SOLANA_NETWORK,
   SOLANA_WALLET_FILE_PATH,

package/dist/index.d.cts

@@ -497,7 +497,7 @@ interface VideoGenerateOptions {
     /**
      * Virtual Portrait asset ID (`ta_xxxxxx`) — keeps the same AI character
      * across multiple Seedance videos. Enroll via `POST /v1/portrait/enroll`
-     * ($0.50 USDC, no KYC). **Seedance 2.0 fast/pro only.** Mutually exclusive
+     * ($0.01 USDC promo, no KYC). **Seedance 2.0 fast/pro only.** Mutually exclusive
      * with `imageUrl`. Real-person likeness is not supported on BlockRun.
      */
     realFaceAssetId?: string;
@@ -867,6 +867,63 @@ interface PhoneReleaseResponse {
     phone_number: string;
     txHash?: string;
 }
+interface PortraitClientOptions {
+    /** EVM wallet private key (hex string starting with 0x) */
+    privateKey?: `0x${string}` | string;
+    /** API endpoint URL (default: https://blockrun.ai/api) */
+    apiUrl?: string;
+    /** Request timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+interface PortraitEnrollOptions {
+    /** Display name for the portrait (1–64 chars). */
+    name: string;
+    /**
+     * Public HTTPS URL to a JPG/PNG/WEBP face image (≤10 MB). The gateway fetches
+     * it server-side and forwards it to Token360 as multipart — only the URL is sent.
+     */
+    imageUrl: string;
+}
+/**
+ * Response from `POST /v1/portrait/enroll`. The `asset_id` (`ta_xxxxxx`) is what
+ * you pass as `realFaceAssetId` on a Seedance 2.0 video generation to keep the
+ * same AI character across clips.
+ */
+interface PortraitEnrollResponse {
+    object: "virtual_portrait";
+    /** Token360 asset id (`ta_xxxxxx`) — pass as `realFaceAssetId` in VideoGenerateOptions. */
+    asset_id: string;
+    /** Token360 asset-group id (internal/debugging). */
+    group_id: string;
+    name: string;
+    /**
+     * Persisted thumbnail URL. The gateway mirrors your source image to its own
+     * storage when possible (so the listing thumbnail survives a dead source
+     * host); falls back to the original URL if mirroring fails. See `mirrored`.
+     */
+    image_url: string;
+    /** The original URL you supplied (before any mirroring). */
+    source_image_url?: string;
+    /** Whether `image_url` is the gateway-mirrored copy (true) or your original (false). */
+    mirrored?: boolean;
+    /** ISO-8601 creation timestamp. */
+    created_at: string;
+    usage: {
+        compatible_models: string[];
+        how_to_use: string;
+    };
+    price: {
+        amount: string;
+        currency: string;
+    };
+    settlement: {
+        success: boolean;
+        tx_hash: string | null;
+        network: string;
+    };
+    /** On-chain payment receipt (tx hash), surfaced from the response header. */
+    txHash?: string;
+}
 interface BlockrunClientOptions {
     privateKey?: `0x${string}` | string;
     apiUrl?: string;
@@ -1774,6 +1831,75 @@ declare class PhoneClient {
     private fetchWithTimeout;
 }
 
+/**
+ * BlockRun Portrait Client — enroll a Virtual Portrait via x402.
+ *
+ * Wraps `POST /v1/portrait/enroll` ($0.01 USDC promo, no KYC). You upload a face image
+ * by URL and get back a Token360 asset id (`ta_xxxxxx`). Pass that id as
+ * `realFaceAssetId` on a Seedance 2.0 video generation (VideoClient.generate)
+ * to keep the same AI character across clips.
+ *
+ * SECURITY NOTE — your private key never leaves your machine. Only EIP-712
+ * signatures are sent in the PAYMENT-SIGNATURE header.
+ *
+ * @example
+ *   import { PortraitClient, VideoClient } from '@blockrun/llm';
+ *
+ *   const portraits = new PortraitClient({ privateKey: '0x...' });
+ *   const { asset_id } = await portraits.enroll({
+ *     name: 'Spokesperson',
+ *     imageUrl: 'https://example.com/face.jpg',
+ *   });
+ *
+ *   const video = new VideoClient({ privateKey: '0x...' });
+ *   const clip = await video.generate('she waves and smiles', {
+ *     model: 'bytedance/seedance-2.0-fast',
+ *     realFaceAssetId: asset_id,
+ *   });
+ */
+
+/**
+ * Flat enrollment price in USD — mirrors the backend's `ENROLLMENT_PRICE_USD`.
+ * Currently $0.01 (promotional, parity with RealFace). The authoritative price
+ * is whatever the gateway quotes in the 402; this constant is informational.
+ */
+declare const PORTRAIT_ENROLLMENT_PRICE_USD = 0.01;
+/**
+ * BlockRun Portrait Client.
+ *
+ * Enrolls a Virtual Portrait from a face image URL and returns the `ta_xxxxxx`
+ * asset id consumed by Seedance 2.0 video generation. Real-person likeness is
+ * not supported on BlockRun — enrolled portraits are AI characters.
+ */
+declare class PortraitClient {
+    private account;
+    private privateKey;
+    private apiUrl;
+    private timeout;
+    private sessionTotalUsd;
+    private sessionCalls;
+    constructor(options?: PortraitClientOptions);
+    /** EVM wallet address used for payments. */
+    getWalletAddress(): string;
+    /** Session-cumulative USD spend + call count across this client instance. */
+    getSpending(): Spending;
+    /**
+     * Enroll a Virtual Portrait from a face image URL. $0.01 (promo).
+     *
+     * Payment is settled only after Token360 confirms the enrollment, so failed
+     * enrollments never charge your wallet.
+     *
+     * @param options.name     Display name (1–64 chars).
+     * @param options.imageUrl Public HTTPS URL to a JPG/PNG/WEBP image (≤10 MB).
+     * @returns The enrollment record, including `asset_id` (`ta_xxxxxx`).
+     */
+    enroll(options: PortraitEnrollOptions): Promise<PortraitEnrollResponse>;
+    private request;
+    private handlePaymentAndRetry;
+    private unwrap;
+    private fetchWithTimeout;
+}
+
 /**
  * BlockRun Search Client - Standalone Grok Live Search via x402 micropayments.
  *
@@ -2762,4 +2888,4 @@ declare function validateTemperature(temperature?: number): void;
  */
 declare function validateTopP(topP?: number): void;
 
-export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, type RoutingDecision, type RoutingProfile, type RoutingTier, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XArticlesRisingResponse, type XAuthorAnalyticsResponse, XClient, type XClientOptions, type XCompareAuthorsResponse, type XFollower, type XFollowersResponse, type XFollowingsResponse, type XMentionsOptions, type XMentionsResponse, type XSearchOptions, type XSearchResponse, type XSearchSource, type XTrendingResponse, type XTweet, type XTweetLookupResponse, type XTweetRepliesOptions, type XTweetRepliesResponse, type XTweetThreadResponse, type XTweetsResponse, type XUser, type XUserInfoResponse, type XUserLookupResponse, type XUserTweetsOptions, type XVerifiedFollowersResponse, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };
+export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, type RoutingDecision, type RoutingProfile, type RoutingTier, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XArticlesRisingResponse, type XAuthorAnalyticsResponse, XClient, type XClientOptions, type XCompareAuthorsResponse, type XFollower, type XFollowersResponse, type XFollowingsResponse, type XMentionsOptions, type XMentionsResponse, type XSearchOptions, type XSearchResponse, type XSearchSource, type XTrendingResponse, type XTweet, type XTweetLookupResponse, type XTweetRepliesOptions, type XTweetRepliesResponse, type XTweetThreadResponse, type XTweetsResponse, type XUser, type XUserInfoResponse, type XUserLookupResponse, type XUserTweetsOptions, type XVerifiedFollowersResponse, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };

package/dist/index.d.ts

@@ -497,7 +497,7 @@ interface VideoGenerateOptions {
     /**
      * Virtual Portrait asset ID (`ta_xxxxxx`) — keeps the same AI character
      * across multiple Seedance videos. Enroll via `POST /v1/portrait/enroll`
-     * ($0.50 USDC, no KYC). **Seedance 2.0 fast/pro only.** Mutually exclusive
+     * ($0.01 USDC promo, no KYC). **Seedance 2.0 fast/pro only.** Mutually exclusive
      * with `imageUrl`. Real-person likeness is not supported on BlockRun.
      */
     realFaceAssetId?: string;
@@ -867,6 +867,63 @@ interface PhoneReleaseResponse {
     phone_number: string;
     txHash?: string;
 }
+interface PortraitClientOptions {
+    /** EVM wallet private key (hex string starting with 0x) */
+    privateKey?: `0x${string}` | string;
+    /** API endpoint URL (default: https://blockrun.ai/api) */
+    apiUrl?: string;
+    /** Request timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+interface PortraitEnrollOptions {
+    /** Display name for the portrait (1–64 chars). */
+    name: string;
+    /**
+     * Public HTTPS URL to a JPG/PNG/WEBP face image (≤10 MB). The gateway fetches
+     * it server-side and forwards it to Token360 as multipart — only the URL is sent.
+     */
+    imageUrl: string;
+}
+/**
+ * Response from `POST /v1/portrait/enroll`. The `asset_id` (`ta_xxxxxx`) is what
+ * you pass as `realFaceAssetId` on a Seedance 2.0 video generation to keep the
+ * same AI character across clips.
+ */
+interface PortraitEnrollResponse {
+    object: "virtual_portrait";
+    /** Token360 asset id (`ta_xxxxxx`) — pass as `realFaceAssetId` in VideoGenerateOptions. */
+    asset_id: string;
+    /** Token360 asset-group id (internal/debugging). */
+    group_id: string;
+    name: string;
+    /**
+     * Persisted thumbnail URL. The gateway mirrors your source image to its own
+     * storage when possible (so the listing thumbnail survives a dead source
+     * host); falls back to the original URL if mirroring fails. See `mirrored`.
+     */
+    image_url: string;
+    /** The original URL you supplied (before any mirroring). */
+    source_image_url?: string;
+    /** Whether `image_url` is the gateway-mirrored copy (true) or your original (false). */
+    mirrored?: boolean;
+    /** ISO-8601 creation timestamp. */
+    created_at: string;
+    usage: {
+        compatible_models: string[];
+        how_to_use: string;
+    };
+    price: {
+        amount: string;
+        currency: string;
+    };
+    settlement: {
+        success: boolean;
+        tx_hash: string | null;
+        network: string;
+    };
+    /** On-chain payment receipt (tx hash), surfaced from the response header. */
+    txHash?: string;
+}
 interface BlockrunClientOptions {
     privateKey?: `0x${string}` | string;
     apiUrl?: string;
@@ -1774,6 +1831,75 @@ declare class PhoneClient {
     private fetchWithTimeout;
 }
 
+/**
+ * BlockRun Portrait Client — enroll a Virtual Portrait via x402.
+ *
+ * Wraps `POST /v1/portrait/enroll` ($0.01 USDC promo, no KYC). You upload a face image
+ * by URL and get back a Token360 asset id (`ta_xxxxxx`). Pass that id as
+ * `realFaceAssetId` on a Seedance 2.0 video generation (VideoClient.generate)
+ * to keep the same AI character across clips.
+ *
+ * SECURITY NOTE — your private key never leaves your machine. Only EIP-712
+ * signatures are sent in the PAYMENT-SIGNATURE header.
+ *
+ * @example
+ *   import { PortraitClient, VideoClient } from '@blockrun/llm';
+ *
+ *   const portraits = new PortraitClient({ privateKey: '0x...' });
+ *   const { asset_id } = await portraits.enroll({
+ *     name: 'Spokesperson',
+ *     imageUrl: 'https://example.com/face.jpg',
+ *   });
+ *
+ *   const video = new VideoClient({ privateKey: '0x...' });
+ *   const clip = await video.generate('she waves and smiles', {
+ *     model: 'bytedance/seedance-2.0-fast',
+ *     realFaceAssetId: asset_id,
+ *   });
+ */
+
+/**
+ * Flat enrollment price in USD — mirrors the backend's `ENROLLMENT_PRICE_USD`.
+ * Currently $0.01 (promotional, parity with RealFace). The authoritative price
+ * is whatever the gateway quotes in the 402; this constant is informational.
+ */
+declare const PORTRAIT_ENROLLMENT_PRICE_USD = 0.01;
+/**
+ * BlockRun Portrait Client.
+ *
+ * Enrolls a Virtual Portrait from a face image URL and returns the `ta_xxxxxx`
+ * asset id consumed by Seedance 2.0 video generation. Real-person likeness is
+ * not supported on BlockRun — enrolled portraits are AI characters.
+ */
+declare class PortraitClient {
+    private account;
+    private privateKey;
+    private apiUrl;
+    private timeout;
+    private sessionTotalUsd;
+    private sessionCalls;
+    constructor(options?: PortraitClientOptions);
+    /** EVM wallet address used for payments. */
+    getWalletAddress(): string;
+    /** Session-cumulative USD spend + call count across this client instance. */
+    getSpending(): Spending;
+    /**
+     * Enroll a Virtual Portrait from a face image URL. $0.01 (promo).
+     *
+     * Payment is settled only after Token360 confirms the enrollment, so failed
+     * enrollments never charge your wallet.
+     *
+     * @param options.name     Display name (1–64 chars).
+     * @param options.imageUrl Public HTTPS URL to a JPG/PNG/WEBP image (≤10 MB).
+     * @returns The enrollment record, including `asset_id` (`ta_xxxxxx`).
+     */
+    enroll(options: PortraitEnrollOptions): Promise<PortraitEnrollResponse>;
+    private request;
+    private handlePaymentAndRetry;
+    private unwrap;
+    private fetchWithTimeout;
+}
+
 /**
  * BlockRun Search Client - Standalone Grok Live Search via x402 micropayments.
  *
@@ -2762,4 +2888,4 @@ declare function validateTemperature(temperature?: number): void;
  */
 declare function validateTopP(topP?: number): void;
 
-export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, type RoutingDecision, type RoutingProfile, type RoutingTier, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XArticlesRisingResponse, type XAuthorAnalyticsResponse, XClient, type XClientOptions, type XCompareAuthorsResponse, type XFollower, type XFollowersResponse, type XFollowingsResponse, type XMentionsOptions, type XMentionsResponse, type XSearchOptions, type XSearchResponse, type XSearchSource, type XTrendingResponse, type XTweet, type XTweetLookupResponse, type XTweetRepliesOptions, type XTweetRepliesResponse, type XTweetThreadResponse, type XTweetsResponse, type XUser, type XUserInfoResponse, type XUserLookupResponse, type XUserTweetsOptions, type XVerifiedFollowersResponse, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };
+export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, type RoutingDecision, type RoutingProfile, type RoutingTier, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XArticlesRisingResponse, type XAuthorAnalyticsResponse, XClient, type XClientOptions, type XCompareAuthorsResponse, type XFollower, type XFollowersResponse, type XFollowingsResponse, type XMentionsOptions, type XMentionsResponse, type XSearchOptions, type XSearchResponse, type XSearchSource, type XTrendingResponse, type XTweet, type XTweetLookupResponse, type XTweetRepliesOptions, type XTweetRepliesResponse, type XTweetThreadResponse, type XTweetsResponse, type XUser, type XUserInfoResponse, type XUserLookupResponse, type XUserTweetsOptions, type XVerifiedFollowersResponse, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };

package/dist/index.js

@@ -2898,15 +2898,18 @@ var PhoneClient = class {
   }
 };
 
-// src/search.ts
+// src/portrait.ts
 import { privateKeyToAccount as privateKeyToAccount7 } from "viem/accounts";
 var DEFAULT_API_URL7 = "https://blockrun.ai/api";
 var DEFAULT_TIMEOUT7 = 6e4;
-var SearchClient = class {
+var PORTRAIT_ENROLLMENT_PRICE_USD = 0.01;
+var PortraitClient = class {
   account;
   privateKey;
   apiUrl;
   timeout;
+  sessionTotalUsd = 0;
+  sessionCalls = 0;
   constructor(options = {}) {
     const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
     const privateKey = options.privateKey || envKey;
@@ -2923,6 +2926,157 @@ var SearchClient = class {
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT7;
   }
+  /** EVM wallet address used for payments. */
+  getWalletAddress() {
+    return this.account.address;
+  }
+  /** Session-cumulative USD spend + call count across this client instance. */
+  getSpending() {
+    return { totalUsd: this.sessionTotalUsd, calls: this.sessionCalls };
+  }
+  /**
+   * Enroll a Virtual Portrait from a face image URL. $0.01 (promo).
+   *
+   * Payment is settled only after Token360 confirms the enrollment, so failed
+   * enrollments never charge your wallet.
+   *
+   * @param options.name     Display name (1–64 chars).
+   * @param options.imageUrl Public HTTPS URL to a JPG/PNG/WEBP image (≤10 MB).
+   * @returns The enrollment record, including `asset_id` (`ta_xxxxxx`).
+   */
+  async enroll(options) {
+    const name = typeof options?.name === "string" ? options.name.trim() : "";
+    if (name.length < 1 || name.length > 64) {
+      throw new Error("name is required and must be 1\u201364 characters");
+    }
+    const imageUrl = typeof options?.imageUrl === "string" ? options.imageUrl.trim() : "";
+    if (!/^https?:\/\//i.test(imageUrl)) {
+      throw new Error(
+        "imageUrl must be a public http(s) URL to a JPG/PNG/WEBP image"
+      );
+    }
+    const data = await this.request({
+      name,
+      image_url: imageUrl
+    });
+    return data;
+  }
+  // ─── Internals ─────────────────────────────────────────────────────────
+  async request(body) {
+    const url = `${this.apiUrl}/v1/portrait/enroll`;
+    const response = await this.fetchWithTimeout(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    if (response.status === 402) {
+      return this.handlePaymentAndRetry(url, body, response);
+    }
+    return this.unwrap(response, false);
+  }
+  async handlePaymentAndRetry(url, body, response) {
+    let paymentHeader = response.headers.get("payment-required");
+    if (!paymentHeader) {
+      try {
+        const rb = await response.json();
+        if (rb.x402 || rb.accepts) paymentHeader = btoa(JSON.stringify(rb));
+      } catch {
+      }
+    }
+    if (!paymentHeader) {
+      throw new PaymentError("402 response but no payment requirements found");
+    }
+    const paymentRequired = parsePaymentRequired(paymentHeader);
+    const details = extractPaymentDetails(paymentRequired);
+    const paymentPayload = await createPaymentPayload(
+      this.privateKey,
+      this.account.address,
+      details.recipient,
+      details.amount,
+      details.network || "eip155:8453",
+      {
+        resourceUrl: details.resource?.url || url,
+        resourceDescription: details.resource?.description || "BlockRun Virtual Portrait",
+        maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+        extra: details.extra
+      }
+    );
+    const retry = await this.fetchWithTimeout(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "PAYMENT-SIGNATURE": paymentPayload
+      },
+      body: JSON.stringify(body)
+    });
+    if (retry.status === 402) {
+      throw new PaymentError("Payment was rejected. Check your wallet balance.");
+    }
+    const data = await this.unwrap(retry, true);
+    const costUsd = Number.parseFloat(details.amount) / 1e6;
+    this.sessionCalls += 1;
+    this.sessionTotalUsd += costUsd;
+    if (data && typeof data === "object" && !("txHash" in data)) {
+      const settlement = data.settlement;
+      if (settlement?.tx_hash) {
+        data.txHash = settlement.tx_hash;
+      }
+    }
+    return data;
+  }
+  async unwrap(response, afterPayment) {
+    if (response.ok) {
+      return response.json();
+    }
+    let errorBody;
+    try {
+      errorBody = await response.json();
+    } catch {
+      errorBody = { error: "Request failed" };
+    }
+    const prefix = afterPayment ? "API error after payment" : "API error";
+    throw new APIError(
+      `${prefix}: ${response.status}`,
+      response.status,
+      sanitizeErrorResponse(errorBody)
+    );
+  }
+  async fetchWithTimeout(url, init) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      return await fetch(url, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+};
+
+// src/search.ts
+import { privateKeyToAccount as privateKeyToAccount8 } from "viem/accounts";
+var DEFAULT_API_URL8 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT8 = 6e4;
+var SearchClient = class {
+  account;
+  privateKey;
+  apiUrl;
+  timeout;
+  constructor(options = {}) {
+    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
+    const privateKey = options.privateKey || envKey;
+    if (!privateKey) {
+      throw new Error(
+        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+      );
+    }
+    validatePrivateKey(privateKey);
+    this.privateKey = privateKey;
+    this.account = privateKeyToAccount8(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL8;
+    validateApiUrl(apiUrl);
+    this.apiUrl = apiUrl.replace(/\/$/, "");
+    this.timeout = options.timeout || DEFAULT_TIMEOUT8;
+  }
   async search(query, options) {
     if (!query || query.length > 1e3) {
       throw new Error("query must be 1-1000 characters");
@@ -3035,9 +3189,9 @@ var SearchClient = class {
 };
 
 // src/x-client.ts
-import { privateKeyToAccount as privateKeyToAccount8 } from "viem/accounts";
-var DEFAULT_API_URL8 = "https://blockrun.ai/api";
-var DEFAULT_TIMEOUT8 = 6e4;
+import { privateKeyToAccount as privateKeyToAccount9 } from "viem/accounts";
+var DEFAULT_API_URL9 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT9 = 6e4;
 var XClient = class _XClient {
   account;
   privateKey;
@@ -3060,11 +3214,11 @@ var XClient = class _XClient {
     }
     validatePrivateKey(privateKey);
     this.privateKey = privateKey;
-    this.account = privateKeyToAccount8(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL8;
+    this.account = privateKeyToAccount9(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL9;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
-    this.timeout = options.timeout || DEFAULT_TIMEOUT8;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT9;
   }
   // ───────── User endpoints ─────────
   userLookup(usernames) {
@@ -3242,9 +3396,9 @@ var XClient = class _XClient {
 };
 
 // src/price.ts
-import { privateKeyToAccount as privateKeyToAccount9 } from "viem/accounts";
-var DEFAULT_API_URL9 = "https://blockrun.ai/api";
-var DEFAULT_TIMEOUT9 = 3e4;
+import { privateKeyToAccount as privateKeyToAccount10 } from "viem/accounts";
+var DEFAULT_API_URL10 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT10 = 3e4;
 var PriceClient = class {
   account = null;
   privateKey = null;
@@ -3262,12 +3416,12 @@ var PriceClient = class {
     if (privateKey) {
       validatePrivateKey(privateKey);
       this.privateKey = privateKey;
-      this.account = privateKeyToAccount9(privateKey);
+      this.account = privateKeyToAccount10(privateKey);
     }
-    const apiUrl = options.apiUrl || DEFAULT_API_URL9;
+    const apiUrl = options.apiUrl || DEFAULT_API_URL10;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
-    this.timeout = options.timeout || DEFAULT_TIMEOUT9;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT10;
   }
   async price(category, symbol, options) {
     if (!symbol) throw new Error("symbol is required");
@@ -3446,9 +3600,9 @@ function buildUrl(base, query) {
 }
 
 // src/surf.ts
-import { privateKeyToAccount as privateKeyToAccount10 } from "viem/accounts";
-var DEFAULT_API_URL10 = "https://blockrun.ai/api";
-var DEFAULT_TIMEOUT10 = 6e4;
+import { privateKeyToAccount as privateKeyToAccount11 } from "viem/accounts";
+var DEFAULT_API_URL11 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT11 = 6e4;
 var SURF_PREFIX = "/v1/surf";
 var SurfClient = class {
   account;
@@ -3465,11 +3619,11 @@ var SurfClient = class {
     }
     validatePrivateKey(privateKey);
     this.privateKey = privateKey;
-    this.account = privateKeyToAccount10(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL10;
+    this.account = privateKeyToAccount11(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL11;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
-    this.timeout = options.timeout || DEFAULT_TIMEOUT10;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT11;
   }
   /**
    * GET a Surf endpoint. `path` is everything after `/v1/surf` (a leading
@@ -3601,9 +3755,9 @@ var SurfClient = class {
 };
 
 // src/blockrun.ts
-import { privateKeyToAccount as privateKeyToAccount11 } from "viem/accounts";
-var DEFAULT_API_URL11 = "https://blockrun.ai/api";
-var DEFAULT_TIMEOUT11 = 6e4;
+import { privateKeyToAccount as privateKeyToAccount12 } from "viem/accounts";
+var DEFAULT_API_URL12 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT12 = 6e4;
 var DEFAULT_POLL_INTERVAL_MS = 5e3;
 var DEFAULT_POLL_BUDGET_MS = 3e5;
 var MAX_SIGNED_AUTH_SECONDS = 600;
@@ -3624,11 +3778,11 @@ var BlockrunClient = class {
     }
     validatePrivateKey(privateKey);
     this.privateKey = privateKey;
-    this.account = privateKeyToAccount11(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL11;
+    this.account = privateKeyToAccount12(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL12;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
-    this.timeout = options.timeout || DEFAULT_TIMEOUT11;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT12;
   }
   /**
    * GET a BlockRun endpoint. `path` is everything after `/api` (a leading
@@ -3979,7 +4133,7 @@ function sleep(ms) {
 }
 
 // src/wallet.ts
-import { privateKeyToAccount as privateKeyToAccount12, generatePrivateKey } from "viem/accounts";
+import { privateKeyToAccount as privateKeyToAccount13, generatePrivateKey } from "viem/accounts";
 import * as fs2 from "fs";
 import * as path2 from "path";
 import * as os2 from "os";
@@ -3989,7 +4143,7 @@ var WALLET_DIR = path2.join(os2.homedir(), ".blockrun");
 var WALLET_FILE = path2.join(WALLET_DIR, ".session");
 function createWallet() {
   const privateKey = generatePrivateKey();
-  const account = privateKeyToAccount12(privateKey);
+  const account = privateKeyToAccount13(privateKey);
   return {
     address: account.address,
     privateKey
@@ -4045,12 +4199,12 @@ function loadWallet() {
 function getOrCreateWallet() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
   if (envKey) {
-    const account = privateKeyToAccount12(envKey);
+    const account = privateKeyToAccount13(envKey);
     return { address: account.address, privateKey: envKey, isNew: false };
   }
   const fileKey = loadWallet();
   if (fileKey) {
-    const account = privateKeyToAccount12(fileKey);
+    const account = privateKeyToAccount13(fileKey);
     return { address: account.address, privateKey: fileKey, isNew: false };
   }
   const { address, privateKey } = createWallet();
@@ -4060,11 +4214,11 @@ function getOrCreateWallet() {
 function getWalletAddress() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
   if (envKey) {
-    return privateKeyToAccount12(envKey).address;
+    return privateKeyToAccount13(envKey).address;
   }
   const fileKey = loadWallet();
   if (fileKey) {
-    return privateKeyToAccount12(fileKey).address;
+    return privateKeyToAccount13(fileKey).address;
   }
   return null;
 }
@@ -4244,7 +4398,7 @@ async function getOrCreateSolanaWallet() {
 // src/solana-client.ts
 var SOLANA_API_URL = "https://sol.blockrun.ai/api";
 var DEFAULT_MAX_TOKENS2 = 1024;
-var DEFAULT_TIMEOUT12 = 6e4;
+var DEFAULT_TIMEOUT13 = 6e4;
 var SDK_VERSION2 = "0.3.0";
 var USER_AGENT2 = `blockrun-ts/${SDK_VERSION2}`;
 var DEFAULT_SOLANA_RPC_URL = "https://sol.blockrun.ai/api/v1/solana/rpc";
@@ -4294,7 +4448,7 @@ var SolanaLLMClient = class {
     const rpc = resolveRpcConfig(options.rpcUrl, options.rpcHeaders);
     this.rpcUrl = rpc.url;
     this.rpcHeaders = rpc.headers;
-    this.timeout = options.timeout || DEFAULT_TIMEOUT12;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT13;
   }
   /** Get Solana wallet address (public key in base58). */
   async getWalletAddress() {
@@ -5204,7 +5358,7 @@ var OpenAI = class {
 };
 
 // src/anthropic-compat.ts
-import { privateKeyToAccount as privateKeyToAccount13 } from "viem/accounts";
+import { privateKeyToAccount as privateKeyToAccount14 } from "viem/accounts";
 var AnthropicClient = class {
   _client = null;
   _clientPromise = null;
@@ -5217,7 +5371,7 @@ var AnthropicClient = class {
     const key = options.privateKey ?? wallet.privateKey;
     validatePrivateKey(key);
     this._privateKey = key;
-    this._account = privateKeyToAccount13(this._privateKey);
+    this._account = privateKeyToAccount14(this._privateKey);
     const apiUrl = options.apiUrl ?? "https://blockrun.ai/api";
     validateApiUrl(apiUrl);
     this._apiUrl = apiUrl.replace(/\/$/, "");
@@ -5323,8 +5477,10 @@ export {
   MusicClient,
   OpenAI,
   PHONE_PRICES,
+  PORTRAIT_ENROLLMENT_PRICE_USD,
   PaymentError,
   PhoneClient,
+  PortraitClient,
   PriceClient,
   SOLANA_NETWORK,
   SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "type": "module",
   "description": "BlockRun SDK - Pay-per-request AI (LLM, Image, Video, Music, Voice) via x402 on Base and Solana",
   "main": "dist/index.cjs",