kompass-sdk 0.14.0 → 0.16.0

package/src/wallet/handlers/locus.ts

@@ -0,0 +1,262 @@
+/**
+ * Locus Payment Handler
+ * Calls Locus wrapped APIs — pay-per-use via USDC on Base.
+ * No upstream API keys needed — Locus proxies the call and charges the wallet.
+ *
+ * Flow:
+ * 1. Get or create Locus API key (self-register if needed)
+ * 2. Wait for wallet deployment
+ * 3. Call the wrapped API endpoint
+ * 4. Locus charges USDC from wallet, returns response
+ *
+ * Docs: https://beta.paywithlocus.com/skill.md
+ */
+
+import type { KompassWallet } from "../index.js";
+import type { UnifiedAgent } from "../../sources/types.js";
+
+const LOCUS_API = "https://beta-api.paywithlocus.com/api";
+
+export async function handleLocusPayment(
+  wallet: KompassWallet,
+  agent: UnifiedAgent,
+  task: string,
+): Promise<{ success: boolean; deliverable?: unknown; txHash?: string }> {
+  let apiKey = process.env.LOCUS_API_KEY;
+
+  try {
+    // Step 1: Self-register if no API key
+    if (!apiKey) {
+      const walletAddress = wallet.getAddress();
+      const registerRes = await fetch(`${LOCUS_API}/register`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          wallet_address: walletAddress,
+          agent_name: "kompass-agent",
+        }),
+        signal: AbortSignal.timeout(15000),
+      });
+
+      if (!registerRes.ok) {
+        const errBody = await registerRes.text().catch(() => "");
+        return {
+          success: false,
+          deliverable: {
+            error: `Locus registration failed: ${registerRes.status}`,
+            details: errBody,
+            hint: "Set LOCUS_API_KEY env var or fund a Locus wallet at paywithlocus.com",
+          },
+        };
+      }
+
+      const registerData = await registerRes.json();
+      apiKey = registerData.data?.apiKey;
+
+      if (!apiKey) {
+        return {
+          success: false,
+          deliverable: { error: "Locus registration did not return an API key" },
+        };
+      }
+
+      // Wait for wallet deployment
+      for (let i = 0; i < 10; i++) {
+        const statusRes = await fetch(`${LOCUS_API}/status`, {
+          headers: { "Authorization": `Bearer ${apiKey}` },
+          signal: AbortSignal.timeout(5000),
+        }).catch(() => null);
+
+        if (statusRes?.ok) {
+          const statusData = await statusRes.json();
+          if (statusData.data?.walletStatus === "deployed") break;
+        }
+        await new Promise((r) => setTimeout(r, 3000));
+      }
+    }
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${apiKey}`,
+    };
+
+    // Step 2: Determine if this is a wrapped API call or a direct payment
+    const rawData = agent.raw as any;
+    const isWrappedApi = rawData?.type === "locus-wrapped-api";
+
+    if (isWrappedApi) {
+      // Call the wrapped API directly
+      // The endpoint URL is like: /api/wrapped/{provider}/{endpoint}
+      // We need to figure out the best endpoint for the task
+      const provider = rawData.provider;
+      const availableEndpoints = rawData.endpoints as string[] || [];
+
+      // Pick the best endpoint and build the right params for each provider
+      const { endpoint, params } = buildLocusRequest(provider, availableEndpoints, task);
+
+      const callUrl = `${LOCUS_API}/wrapped/${provider}/${endpoint}`;
+
+      const callRes = await fetch(callUrl, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(params),
+        signal: AbortSignal.timeout(30000),
+      });
+
+      if (!callRes.ok) {
+        const errBody = await callRes.text().catch(() => "");
+        return {
+          success: false,
+          deliverable: {
+            error: `Locus wrapped API call failed: ${callRes.status}`,
+            provider,
+            endpoint,
+            details: errBody,
+          },
+        };
+      }
+
+      const result = await callRes.json();
+      return {
+        success: true,
+        deliverable: result,
+      };
+    }
+
+    // Step 3: Direct USDC payment to agent address
+    const toAddress = agent.endpoints.acp?.walletAddress ?? agent.endpoints.http;
+    const amount = agent.pricing?.amount ?? "0.01";
+
+    if (!toAddress || !toAddress.startsWith("0x")) {
+      return {
+        success: false,
+        deliverable: { error: "No valid target address for Locus payment" },
+      };
+    }
+
+    const sendRes = await fetch(`${LOCUS_API}/pay/send`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        to_address: toAddress,
+        amount: parseFloat(amount),
+        memo: `Kompass task: ${task.slice(0, 100)}`,
+      }),
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!sendRes.ok) {
+      const errBody = await sendRes.text().catch(() => "");
+      return {
+        success: false,
+        deliverable: { error: `Locus payment failed: ${sendRes.status}`, details: errBody },
+      };
+    }
+
+    const sendData = await sendRes.json();
+
+    return {
+      success: true,
+      deliverable: sendData,
+      txHash: sendData.data?.tx_hash ?? sendData.data?.transaction_id,
+    };
+  } catch (err) {
+    return {
+      success: false,
+      deliverable: { error: err instanceof Error ? err.message : String(err) },
+    };
+  }
+}
+
+/**
+ * Build the right endpoint and params for each Locus wrapped API provider.
+ * Each provider has different input formats — this maps the natural language task
+ * to the correct API call based on the provider's docs.
+ */
+function buildLocusRequest(
+  provider: string,
+  endpoints: string[],
+  task: string,
+): { endpoint: string; params: Record<string, unknown> } {
+  // Extract URLs from task
+  const urlMatch = task.match(/https?:\/\/[^\s"']+/);
+  const url = urlMatch?.[0];
+
+  switch (provider) {
+    // Web scraping providers — need "url" param
+    case "firecrawl":
+      return { endpoint: url ? "scrape" : "search", params: url ? { url } : { query: task } };
+    case "abstract-web-scraping":
+      return { endpoint: "scrape", params: { url: url || task } };
+    case "diffbot":
+      return { endpoint: "analyze", params: { url: url || task } };
+    case "tavily":
+      return { endpoint: url ? "extract" : "search", params: url ? { urls: [url] } : { query: task } };
+
+    // Search providers — need "query" or "q" param
+    case "brave":
+      return { endpoint: "web-search", params: { q: task } };
+    case "exa":
+      return { endpoint: "search", params: { query: task } };
+    case "perplexity":
+      return { endpoint: "sonar-chat", params: { messages: [{ role: "user", content: task }] } };
+
+    // Crypto / Finance
+    case "coingecko": {
+      // Extract coin name from task
+      const coins = ["bitcoin", "ethereum", "solana", "base", "usdc"];
+      const coin = coins.find(c => task.toLowerCase().includes(c)) || "ethereum";
+      const coinId = coin === "eth" ? "ethereum" : coin;
+      return { endpoint: "simple-price", params: { ids: coinId, vs_currencies: "usd" } };
+    }
+    case "alphavantage":
+      return { endpoint: "global-quote", params: { symbol: task.match(/[A-Z]{1,5}/)?.[0] || "ETH" } };
+
+    // LLM providers — need "messages" or "prompt"
+    case "openai":
+    case "anthropic":
+    case "gemini":
+    case "deepseek":
+    case "grok":
+    case "groq":
+    case "mistral":
+      return { endpoint: "chat", params: { messages: [{ role: "user", content: task }] } };
+
+    // Image/Media generation
+    case "fal":
+      return { endpoint: "generate", params: { prompt: task } };
+    case "stability-ai":
+      return { endpoint: "generate-core", params: { prompt: task } };
+    case "replicate":
+      return { endpoint: "run-model", params: { input: { prompt: task } } };
+    case "suno":
+      return { endpoint: "generate-music", params: { prompt: task } };
+
+    // Code execution
+    case "judge0":
+      return { endpoint: "execute-code", params: { source_code: task, language_id: 63 } }; // 63 = JavaScript
+
+    // Screenshot
+    case "screenshotone":
+      return { endpoint: "take-screenshot", params: { url: url || task } };
+
+    // Social
+    case "x":
+      return { endpoint: "search-recent-tweets", params: { query: task } };
+
+    // Knowledge
+    case "wolframalpha":
+      return { endpoint: "short-answer", params: { input: task } };
+
+    // Security
+    case "virustotal":
+      return { endpoint: url ? "url-report" : "domain-report", params: url ? { resource: url } : { domain: task } };
+
+    // Default — try common param names
+    default:
+      return {
+        endpoint: endpoints[0]?.toLowerCase().replace(/\s+/g, "-") || "search",
+        params: { query: task, prompt: task, q: task, input: task },
+      };
+  }
+}

package/src/wallet/payment-router.ts

@@ -11,6 +11,8 @@ import { handleL402Payment } from "./handlers/l402.js";
 import { handleMPPPayment } from "./handlers/mpp.js";
 import { handleNanopayment } from "./handlers/nanopayments.js";
 import { handleFreePayment } from "./handlers/free.js";
+import { handleBankrPayment } from "./handlers/bankr.js";
+import { handleLocusPayment } from "./handlers/locus.js";
 import { ensureSufficientBalance } from "./bridge.js";
 
 export interface PaymentResult {
@@ -72,6 +74,16 @@ export async function routePayment(
         return { ...result, protocol: "circle-nanopayments", costUSDC: parseFloat(agent.pricing?.amount ?? "0") };
       }
 
+      case "bankr": {
+        const result = await handleBankrPayment(wallet, agent, task);
+        return { ...result, protocol: "bankr", costUSDC: parseFloat(agent.pricing?.amount ?? "0") };
+      }
+
+      case "locus": {
+        const result = await handleLocusPayment(wallet, agent, task);
+        return { ...result, protocol: "locus", costUSDC: parseFloat(agent.pricing?.amount ?? "0") };
+      }
+
       case "free":
       case "mcp": {
         // MCP servers and free tools — try to execute directly
@@ -130,6 +142,8 @@ function determinePaymentProtocol(agent: UnifiedAgent): string {
     case "l402-directory": return "l402";
     case "mcp-registry": return "free";
     case "skills-registry": return "free";
+    case "bankr": return "bankr";
+    case "locus": return "locus";
     default: return agent.protocol === "onchain" ? "acp" : "free";
   }
 }