kompass-sdk 0.14.0 → 0.15.0

package/src/sources/locus.ts

@@ -0,0 +1,156 @@
+/**
+ * Locus Wrapped API Source Adapter
+ * Fetches Locus's live API catalog and indexes 50+ pay-per-use providers
+ * as discoverable capabilities. Each wrapped API becomes a searchable agent.
+ * Agents pay per-call via USDC on Base — no upstream API keys needed.
+ *
+ * Docs: https://beta.paywithlocus.com/skill.md
+ * Live index: https://beta.paywithlocus.com/wapi/index.md
+ */
+
+import type { SourceAdapter, UnifiedAgent, SourceSearchOptions } from "./types.js";
+
+const LOCUS_API = "https://beta-api.paywithlocus.com/api";
+const WAPI_INDEX_URL = "https://beta.paywithlocus.com/wapi/index.md";
+
+interface LocusProvider {
+  name: string;
+  slug: string;
+  category: string;
+  endpoints: string;
+  description: string;
+}
+
+// Cache fetched providers — refresh every 10 minutes
+let providerCache: LocusProvider[] | null = null;
+let cacheTime = 0;
+const CACHE_TTL = 10 * 60 * 1000;
+
+/**
+ * Parse the live markdown index from Locus into structured provider data.
+ * The index is a markdown table with columns: Provider, Category, Endpoints, Description
+ */
+function parseMarkdownIndex(md: string): LocusProvider[] {
+  const providers: LocusProvider[] = [];
+  const lines = md.split("\n");
+
+  for (const line of lines) {
+    // Match table rows: | [Provider Name](url) | Category | Endpoints | Description |
+    const match = line.match(/^\| \[([^\]]+)\]\(https:\/\/[^)]*\/wapi\/([^.]+)\.md\)\s*\|\s*([^|]+)\|\s*([^|]+)\|\s*([^|]+)\|/);
+    if (match) {
+      providers.push({
+        name: match[1].trim(),
+        slug: match[2].trim(),
+        category: match[3].trim().toLowerCase(),
+        endpoints: match[4].trim(),
+        description: match[5].trim(),
+      });
+    }
+  }
+
+  return providers;
+}
+
+async function fetchProviders(timeout: number): Promise<LocusProvider[]> {
+  if (providerCache && Date.now() - cacheTime < CACHE_TTL) {
+    return providerCache;
+  }
+
+  try {
+    const res = await fetch(WAPI_INDEX_URL, {
+      signal: AbortSignal.timeout(timeout),
+    });
+
+    if (!res.ok) return providerCache ?? [];
+
+    const md = await res.text();
+    const parsed = parseMarkdownIndex(md);
+
+    if (parsed.length > 0) {
+      providerCache = parsed;
+      cacheTime = Date.now();
+    }
+
+    return providerCache ?? [];
+  } catch {
+    return providerCache ?? [];
+  }
+}
+
+export const locusAdapter: SourceAdapter = {
+  name: "locus" as any,
+  displayName: "Locus Wrapped APIs",
+
+  async search(query: string, options?: SourceSearchOptions): Promise<UnifiedAgent[]> {
+    const limit = options?.limit ?? 20;
+    const timeout = options?.timeout ?? 10000;
+    const lower = query.toLowerCase();
+    const terms = lower.split(/\s+/).filter(t => t.length > 2);
+
+    const providers = await fetchProviders(timeout);
+
+    // Score each provider by relevance
+    const scored = providers.map(provider => {
+      let score = 0;
+      const searchText = `${provider.name} ${provider.description} ${provider.category} ${provider.endpoints}`.toLowerCase();
+
+      for (const term of terms) {
+        if (provider.name.toLowerCase().includes(term)) score += 5;
+        if (provider.description.toLowerCase().includes(term)) score += 3;
+        if (provider.endpoints.toLowerCase().includes(term)) score += 2;
+        if (provider.category.includes(term)) score += 4;
+        if (searchText.includes(term)) score += 1;
+      }
+
+      return { provider, score };
+    })
+      .filter(s => s.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit);
+
+    return scored.map(s => mapLocusProvider(s.provider));
+  },
+
+  async ping(): Promise<boolean> {
+    try {
+      const res = await fetch(WAPI_INDEX_URL, {
+        signal: AbortSignal.timeout(5000),
+      });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  },
+};
+
+function mapLocusProvider(provider: LocusProvider): UnifiedAgent {
+  const endpointList = provider.endpoints.split(",").map(e => e.trim()).slice(0, 5);
+
+  return {
+    id: `locus:${provider.slug}`,
+    nativeId: provider.slug,
+    name: `${provider.name} (via Locus)`,
+    description: `${provider.description} Pay-per-use via USDC — no API key needed.`,
+    categories: [provider.category.split(" / ")[0].toLowerCase(), "api", "pay-per-use"],
+    capabilities: endpointList.map(e => `${provider.name}: ${e}`),
+    source: "locus" as any,
+    protocol: "http",
+    endpoints: {
+      http: `${LOCUS_API}/wrapped/${provider.slug}`,
+    },
+    pricing: {
+      model: "per-call",
+      amount: "0.01",
+      currency: "USDC",
+    },
+    verified: true,
+    lastSeen: Date.now(),
+    raw: {
+      type: "locus-wrapped-api",
+      provider: provider.slug,
+      category: provider.category,
+      endpoints: endpointList,
+      allEndpoints: provider.endpoints,
+    },
+  };
+}

package/src/sources/types.ts

@@ -14,7 +14,9 @@ export type AgentSource =
   | "adp"
   | "a2a-wellknown"
   | "l402-directory"
-  | "skills-registry";
+  | "skills-registry"
+  | "bankr"
+  | "locus";
 
 export type AgentProtocol = "acp" | "mcp" | "x402" | "a2a" | "http" | "l402" | "onchain" | "skill";
 

package/src/wallet/bridge.ts

@@ -19,6 +19,10 @@ const USDC_ADDRESSES: Record<string, Address> = {
   "base-sepolia": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
 };
 
+// Kompass treasury address — receives platform fee on payments
+const KOMPASS_TREASURY: Address = "0x2aB73f8CCee4ABE601cE71eCC82Bd9eC375FeBbA";
+const PLATFORM_FEE_BPS = 200; // 2% = 200 basis points
+
 // ── ACP Wallet Topup ─────────────────────────────────────
 
 /**
@@ -29,12 +33,17 @@ export async function topupACPWallet(
   wallet: KompassWallet,
   acpWalletAddress: Address,
   amountUSDC: number
-): Promise<{ txHash: Hex; amount: string }> {
+): Promise<{ txHash: Hex; amount: string; fee?: string }> {
   const network = wallet.getNetwork();
   const usdcAddress = USDC_ADDRESSES[network];
   if (!usdcAddress) throw new Error(`No USDC address for network: ${network}`);
 
-  const amount = parseUnits(String(amountUSDC), 6);
+  // Calculate platform fee (2%)
+  const feeUSDC = amountUSDC * PLATFORM_FEE_BPS / 10000;
+  const netAmount = amountUSDC - feeUSDC;
+  const totalNeeded = parseUnits(String(amountUSDC), 6);
+  const netAmountRaw = parseUnits(String(netAmount.toFixed(6)), 6);
+  const feeAmountRaw = totalNeeded - netAmountRaw;
 
   // Check balance first
   const balance = await wallet.getPublicClient().readContract({
@@ -44,25 +53,43 @@ export async function topupACPWallet(
     args: [wallet.getAddress()],
   });
 
-  if (balance < amount) {
+  if (balance < totalNeeded) {
     throw new Error(
       `Insufficient USDC: have ${formatUnits(balance, 6)}, need ${amountUSDC}. ` +
       `Fund your Kompass wallet at ${wallet.getAddress()} on ${network}.`
     );
   }
 
+  // Transfer net amount to ACP wallet
   const txHash = await (wallet.getWalletClient() as any).writeContract({
     address: usdcAddress,
     abi: USDC_ABI,
     functionName: "transfer",
-    args: [acpWalletAddress, amount],
+    args: [acpWalletAddress, netAmountRaw],
   });
 
   await wallet.getPublicClient().waitForTransactionReceipt({ hash: txHash });
 
-  console.log(`[Kompass Bridge] Transferred ${amountUSDC} USDC to ACP wallet ${acpWalletAddress.slice(0, 10)}... | tx: ${txHash}`);
+  // Transfer platform fee to Kompass treasury (skip if treasury == ACP wallet)
+  if (feeAmountRaw > 0n && KOMPASS_TREASURY.toLowerCase() !== acpWalletAddress.toLowerCase()) {
+    try {
+      const feeTx = await (wallet.getWalletClient() as any).writeContract({
+        address: usdcAddress,
+        abi: USDC_ABI,
+        functionName: "transfer",
+        args: [KOMPASS_TREASURY, feeAmountRaw],
+      });
+      await wallet.getPublicClient().waitForTransactionReceipt({ hash: feeTx });
+      console.log(`[Kompass Bridge] Platform fee: $${feeUSDC.toFixed(4)} USDC → treasury | tx: ${feeTx}`);
+    } catch (feeErr) {
+      // Fee transfer failure shouldn't block the job
+      console.log(`[Kompass Bridge] Fee transfer failed (non-blocking): ${feeErr instanceof Error ? feeErr.message : feeErr}`);
+    }
+  }
+
+  console.log(`[Kompass Bridge] Transferred ${netAmount.toFixed(4)} USDC to ACP wallet ${acpWalletAddress.slice(0, 10)}... | tx: ${txHash}`);
 
-  return { txHash, amount: String(amountUSDC) };
+  return { txHash, amount: String(netAmount.toFixed(4)), fee: feeUSDC.toFixed(4) };
 }
 
 // ── Lightning Swap (USDC → sats) ─────────────────────────

package/src/wallet/handlers/acp.ts

@@ -40,9 +40,10 @@ export async function handleACPPayment(
     // Job creation (REQUEST) and acceptance (NEGOTIATION) are FREE.
     // We topup only after confirming an agent accepted.
 
-    // Use ACP CLI with execFile (not execSync) to avoid shell injection
-    // Arguments passed as array, not concatenated string
-    const requirements = JSON.stringify({ description: task });
+    // Format requirements to match offering's expected schema.
+    // If the offering has a requirement template/schema, try to conform to it.
+    // Otherwise fall back to {description: task}.
+    const requirements = JSON.stringify(formatRequirements(task, offering));
 
     const { stdout } = await execFileAsync(
       "npx",
@@ -157,3 +158,68 @@ export async function handleACPPayment(
     };
   }
 }
+
+/**
+ * Format task requirements to match the offering's expected schema.
+ *
+ * ACP agents reject jobs when requirements don't match their offering's
+ * expected input format. This function:
+ * 1. Checks if the offering has a requirement schema/template
+ * 2. Tries to extract relevant fields from the natural language task
+ * 3. Falls back to {description: task} if no schema exists
+ */
+function formatRequirements(task: string, offering: any): Record<string, unknown> {
+  const schema = offering.requirement ?? offering.requirementSchema ?? offering.inputSchema;
+
+  // No schema defined — send description (most flexible)
+  if (!schema || typeof schema === "string") {
+    return { description: task };
+  }
+
+  // Schema is an object — try to populate its fields from the task
+  if (typeof schema === "object") {
+    const formatted: Record<string, unknown> = {};
+    const taskLower = task.toLowerCase();
+
+    for (const [key, spec] of Object.entries(schema)) {
+      const keyLower = key.toLowerCase();
+
+      // Try to extract Ethereum addresses for address-type fields
+      if (keyLower.includes("address") || keyLower.includes("token") || keyLower.includes("contract")) {
+        const addrMatch = task.match(/0x[a-fA-F0-9]{40}/);
+        if (addrMatch) {
+          formatted[key] = addrMatch[0];
+          continue;
+        }
+      }
+
+      // Try to extract chain/network
+      if (keyLower.includes("chain") || keyLower.includes("network")) {
+        const chains = ["base", "ethereum", "polygon", "arbitrum", "optimism", "bsc"];
+        const found = chains.find((c) => taskLower.includes(c));
+        formatted[key] = found ?? "base";
+        continue;
+      }
+
+      // Try to extract numeric amounts
+      if (keyLower.includes("amount") || keyLower.includes("quantity") || keyLower.includes("limit")) {
+        const numMatch = task.match(/\d+\.?\d*/);
+        if (numMatch) {
+          formatted[key] = parseFloat(numMatch[0]);
+          continue;
+        }
+      }
+
+      // For any other field, use the task description as the value
+      if (typeof spec === "string") {
+        formatted[key] = task; // Use full task as the value
+      }
+    }
+
+    // Always include description for context
+    formatted.description = task;
+    return formatted;
+  }
+
+  return { description: task };
+}

package/src/wallet/handlers/bankr.ts

@@ -0,0 +1,108 @@
+/**
+ * Bankr Payment Handler
+ * Routes trading tasks through Bankr's LLM Gateway
+ * POST prompt → poll for result
+ */
+
+import type { KompassWallet } from "../index.js";
+import type { UnifiedAgent } from "../../sources/types.js";
+
+const BANKR_API = "https://api.bankr.bot";
+
+export async function handleBankrPayment(
+  wallet: KompassWallet,
+  agent: UnifiedAgent,
+  task: string,
+): Promise<{ success: boolean; deliverable?: unknown; jobId?: string }> {
+  const apiKey = process.env.BANKR_API_KEY;
+  if (!apiKey) {
+    return {
+      success: false,
+      deliverable: {
+        error: "BANKR_API_KEY not configured. Set the BANKR_API_KEY environment variable.",
+        hint: "Get an API key from https://bankr.bot",
+      },
+    };
+  }
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "X-API-Key": apiKey,
+  };
+
+  try {
+    // Step 1: Submit prompt
+    const submitRes = await fetch(`${BANKR_API}/agent/prompt`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ prompt: task }),
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!submitRes.ok) {
+      const errBody = await submitRes.text().catch(() => "");
+      return {
+        success: false,
+        deliverable: { error: `Bankr API error: ${submitRes.status}`, details: errBody },
+      };
+    }
+
+    const submitData = await submitRes.json();
+    const jobId = submitData.jobId ?? submitData.job_id ?? submitData.id;
+
+    // If the response is immediate (no job polling needed)
+    if (!jobId || submitData.result || submitData.response) {
+      return {
+        success: true,
+        deliverable: submitData.result ?? submitData.response ?? submitData,
+      };
+    }
+
+    // Step 2: Poll for result
+    const maxAttempts = 30;
+    const pollInterval = 2000;
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+
+      const pollRes = await fetch(`${BANKR_API}/agent/job/${jobId}`, {
+        headers,
+        signal: AbortSignal.timeout(10000),
+      });
+
+      if (!pollRes.ok) continue;
+
+      const pollData = await pollRes.json();
+      const status = pollData.status?.toLowerCase();
+
+      if (status === "completed" || status === "done" || status === "success") {
+        return {
+          success: true,
+          deliverable: pollData.result ?? pollData.response ?? pollData,
+          jobId,
+        };
+      }
+
+      if (status === "failed" || status === "error") {
+        return {
+          success: false,
+          deliverable: { error: pollData.error ?? "Job failed", details: pollData },
+          jobId,
+        };
+      }
+
+      // Still pending, continue polling
+    }
+
+    return {
+      success: false,
+      deliverable: { error: "Job timed out after polling", jobId },
+      jobId,
+    };
+  } catch (err) {
+    return {
+      success: false,
+      deliverable: { error: err instanceof Error ? err.message : String(err) },
+    };
+  }
+}

package/src/wallet/handlers/locus.ts

@@ -0,0 +1,170 @@
+/**
+ * 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 first/most relevant endpoint
+      // For now use the first endpoint — the provider slug is already in the URL
+      const endpoint = availableEndpoints[0]?.toLowerCase().replace(/\s+/g, "-") || "search";
+
+      const callUrl = `${LOCUS_API}/wrapped/${provider}/${endpoint}`;
+
+      const callRes = await fetch(callUrl, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ query: task, prompt: task, q: task }),
+        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) },
+    };
+  }
+}

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";
   }
 }